[GH-28] Allow setting message streams transport-wide or per message

[beberlei]

Two ways to optionally set the MessageStream option on a message:

Globally for the whole transport:

$transport = new Postmark($token, $messageStream);

Only for one message, by using the header that Postmarks SMTP sending is using:

$message->getHeaders()->addTextHeader('X-PM-Message-Stream', 'broadcasts');

Fixes #28

[beberlei]

I saw the discussion in #20 about not adding special handling and detecting this in the API instead. However in this csae its necessary, if you have a message stream set as default, then it would be present in the API request, and probably not overwritten by the header that is sent as well.

[beberlei]

The style of both files are inconsistent, there are a few tabs and a few spaces lines. My editor wants either one, it would make the diff quite huge. Probably necessary to fix the styling afterwards.

[vladsandu]

As mentioned in #28 , our API sending endpoints already support setting the MessageStream via the X-PM-Message-Stream header, like it's done for SMTP.

So swiftmailer-postmark currently has support for setting the stream per message via:

$message->getHeaders()->addTextHeader('X-PM-Message-Stream', 'your-custom-stream');

---

This PR would additionally give customers the ability to set the default MessageStream at transport-level. Setting the stream at message-level would override the transport-level default stream.

This could be a useful improvement, but is also a different design compared to what we have been doing for other libraries.

@atheken what is your opinion on this?

[beberlei]

@vladsandu for me thats a violation of the Siwftmailer contract. The Message Stream used is interenal to the Transport object. It should not concern the code sending the message.

]The problem becomes apparent when using Mailcoach, which uses Swiftmailer and supports many different Backends, including Postmark. Now the code of Mailcoach will not add setting this header in their code sending messages, because it could also use Mailgun or any other provider. The abstraction should allow this config.

How about another approach, where you allow users to set default headers that are attached to all messages via the transport?

[vladsandu]

@beberlei sorry for the big delay in replying here. I was on PTO during the past few weeks.

I understand your use case now and it definitely makes sense.

Comparing the current implementation and the new approach that you suggested (allowing users to set transport-level default headers), I do prefer the new approach more.

It would solve a more general problem and allow users to set any default headers, not just MessageStream and also, the idea of having default headers and overriding them per-message basis seems a bit more intuitive to use.

If you are interested in contributing for this new approach, I would be more than happy to get it released shortly after. Otherwise, we'll look into adding this in the next few weeks.

[mfn]

Please don't make anything private, you don't know in what ways other users/customers need to customize things.

Suggested change

	private function processMessageStream(&$payload, $message)
	protected function processMessageStream(&$payload, $message)

See also #33

[beberlei]

The methods in this code are all mostly private, i keep to the existing style. No need to combine #33 into this here.

[beberlei]

@vladsandu I opened #35 with the option to set default headers.