Allow sending to use a "Message Object"

[atheken]

As per this feedback: https://twitter.com/reinink/status/737391939914326017

Add an overload for "sendEmail" (and other endpoints that make sense) to accept a Message Object, allowing easier construction of complex message payloads, and less rote memorization of parameter order.

[reinink]

Thanks @atheken, that would be great! 👍

[atheken]

@reinink No problem, I do most of the work on the Postmark-PHP lib, and I would be happy to get any feedback you have.

[reinink]

Awesome! I think have a message object would remove a lot of the pain. The issue for me really is just the long argument list in the send email function:

function sendEmail($from, $to, $subject, $htmlBody = NULL, $textBody = NULL,
        $tag = NULL, $trackOpens = true, $replyTo = NULL, $cc = NULL, $bcc = NULL,
        $headers = NULL, $attachments = NULL) {

It's very hard to write code for this, and I'm constantly referring back to the source code to get the parameters in the right order. The message object can provide a much nicer interface for this. This would allow the use of setters, and those setters can even be chainable. For example:

$message = (new PostmarkMessage())
    ->setFrom('[email protected]')
    ->setTo('[email protected]')
    ->setSubject('My Subject')
    ->setHtmlBody('<p>Some HTML message</p>')
    ->setTextBody('Some text message')
    ->setTag('test')
    ->setTrackOpens(true)
    ->setReplyTo('[email protected]')
    ->setCc('[email protected]')
    ->setBcc('[email protected]');

$client = new PostmarkClient($api_key);
$client->sendEmail($message);

This would also allow having multiple methods to set values that can multiple records, such as headers or attachments:

// Add one header
$message->addHeader('Message-ID', '<[email protected]>');

// Add one attachment
$message->addAttachment('readme.txt', 'dGVzdCBjb250ZW50', 'text/plain');

// Add multiple headers
$message->addHeaders([
    'Message-ID' => '<[email protected]>',
    'Something' => 'Else',
]);

// Add multiple attachments
$message->addAttachments([
    [
      'Name' => 'readme.txt',
      'Content' => 'dGVzdCBjb250ZW50',
      'ContentType' => 'text/plain'
    ],
    [
      'Name' => 'report.pdf',
      'Content' => 'dGVzdCBjb250ZW50',
      'ContentType' => 'application/octet-stream'
    ]
]);

Just some initial ideas! 😃

[reinink]

One last thought on this. What's cool is that you could make this change non breaking. Meaning if you pass in a Message object, it works, but if you simply use the old parameters, it could still work. You'd just have to check the first parameter to see if it's a string (indicating a from email address) or an instance of PostmarkMessage (or whatever you call it).

[atheken]

@reinink Yep, this was also what I was thinking (the "non-breaking" overload)... Ultimately, most of the work is to create the message object, if you have an interest in implementing that class, I'd gladly accept a PR for it. :-)

[ctessmer]

For the record, I'm running into this same pain point:

$send_result = $client->sendEmail($sender_signature, $to, $subject, $html_body, null, null, null, null, null, null, null, null, null, null, $stream_name);

Definitely not elegant. I've never submitted a PR before. Maybe I need to give it a go…

PS: I tried this str_repeate(null . ', ', 10) in place of those 10 nulls. Didn't work. ButI snickered to myself while typing it. "How clever you are Christian." FAIL!

[vladsandu]

@ctessmer, thank you for your feedback! I'm one of the maintainers for Postmark-PHP.

I definitely agree that currently using this endpoint is less than ideal and the ideas described above about creating a PostmarkMessage class and passing a Message object would be great to implement.

I will put it on my list and try to look into this in the following weeks, but if you'd like to submit a PR for improving this issue sooner, I'd be more than happy to review it for you.

[ctessmer]

@vladsandu Thanks for the response and for maintaining this library! Maybe I'll take a crack at a PR. I'll let you know!