Adds support for file attachments in messages.

I've only been able to test it with Postmark, since I don't have an account with the others, but in theory it works with them too – I've poured over the docs for each of them, so it should be correct for all of them.

There are unit tests for everything new I've added, and I've updated any existing tests for things I've modified. I've tried to match the coding standards already in place, let me know if I've done something differently!

~~Major caveat: Buzz isn't supported by this for mailers that use raw POST messages (SendGrid and MailGun). I couldn't figure out in the few minutes I spent looking at it how to just upload files with POST in Buzz (and I'm not the only one). If anyone can figure it out please let me know, but for now this just ignores the attachments and continues like before if you use Buzz. Guzzle should be fine, and Postmark and Mandrill just base64 encode attachments so they should work on Buzz still. Summary: Buzz + SendGrid/MailGun = no attachments~~ Buzz should be working too.

(There was also an issue preventing the Postmark tests being run – they were being manually included into a different file, so weren't being run. I've fixed that, but they weren't passing, so they pass now too!)

cc: #2

Postmark example:

// Usual setup
$adapter = new \Stampie\Adapter\Guzzle(new \Guzzle\Service\Client());
$mailer  = new \Stampie\Mailer\Postmark($adapter, 'apikey');
$to = new \Stampie\Identity('[email protected]');

$message = new CustomMessage($to); // Implements \Stampie\Message\AttachmentContainerInterface
$message->setAttachments(array(
    new \Stampie\Attachment('path/to/file.jpg', 'attachment.jpg', 'image/jpg'), // Normal attachment
    new \Stampie\Attachment('path/to/other.jpg', 'other.jpg', 'image/jpg', 'cid:[email protected]'), // Can be embedded using <img src="cid:[email protected]">
));
$mailer->send($message);

This PR removes the HTTP adapters and instead we rely on the HTTP client abstraction HTTPlug. This comes with many benefits:

• we support far more adapters (like Guzzle 6)
• we do use PSR7
• We have less code to test and maintain

Hi @henrikbjorn,

As GuzzleHttp is out and namespaces change a bit, do you plan to support guzzlehttp/guzzle; which namespace is \GuzzleHttp, and has a modified API compared to guzzle 3.*?

Tried to do something, but Unit tests are kind of blocking me at this point... :)

Hi,

This adds the implementation of Cc/Bcc for Mandrill. There were 2 ways to do it, as exposed on the Mandrill API doc:

• Updating the identity to set a type, which is then parsed by Mandrill.
• Adding a bcc_address option

I found the first one more maintainable. Not sure how to handle tests in a proper way.

This remove the setHttpClient, setServerToken and getServerToken from MailerInterface.

The MailerInterface contract is now only about sending messages without exposing implementation details to clients.

Also the MailerInterface::send method no longer returns a boolean. If no exception is thrown, then the message was successfully sent.

Close #93.

Todo

• [x] Update mailers to not return a boolean.
• [x] Introduce our own exception interface.
• [x] Add changelog entries.

On receiving a successful response for an email, we send back a boolean true.

There is a need sometimes to log futther Instead we can send back the Response object and let the 'Message ID' from postmark. Returning back the response object will give more leverage to the calling function.

Thanks, -Ketan.

One thing I wasn't sure about is what to do with ['options' => ['transactional' => true]] in the payload data.

It's explained on https://developers.sparkpost.com/api/transmissions.html#transmissions-create-post

In my case, all mail is transactional, but others using Stampie may be using it for marketing purposes.

Is there a clean way of making that parameter configurable? Maybe in the message metadata, but that feels sort of dirty.

@Stampie/collaborators this discussion is about a BC breaking change, so a decision has to be taken before releasing the 1.0 version. If no decision is taken, the release itself will force the decision to be no (at least until 2.0).

The current MailerInterface looks like this: https://github.com/Stampie/Stampie/blob/293be7036b977be7fbb15e2fcf2140255de2b0c7/lib/MailerInterface.php#L12-L35

I suggest to simplify it to this:

interface MailerInterface
{
    /**
     * @param MessageInterface $message
     *
     * @throws Exception on failure
     */
    public function send(MessageInterface $message): void;
}

Here are my reasoning for the different changes:

• forcing the usage of a server token makes it harder to implement things. Each adapter has a different meaning for it (being an API key, a username+password, etc...), meaning that using the getter and setter requires checking the implementation being used anyway (and so the fact that the methods are in the interface is useless). I think the authentication should be an implementation detail of the Mailer: each mailer would be free to take one or multiple parameters for the auth (allowing to split the username and password for instance, which might make it easier to use env variables for instance), and also to decide whether the auth credentials should be mutable and exposed to consuming code (IMO, they should not)
• the fact that the mailer uses a HTTPlug client should be an implementation detail as well (for instance, in Stampie extra, it does not use a HTTP client, but another Stampie mailer, for which it can fortunately forward the setter, but this is weird), and I see no reason to make it mutable either (so it should be a constructor argument)
• instantiating a new mailer currently creates a broken object (as mandatory dependencies are not passed in the constructor)
• the configuration API of mailers is already wider than the MailerInterface (they all have a setMessageFactory setter for instance)
• returning a boolean from send makes debugging harder because you don't have an explanation on failure. And in practice, our own implementations are already all throwing exceptions on failures instead of returning true. So our signature is already @return true @throws ApiException @throws HttpException in practice. Returning true and never false looks weird. Even if we reject the change from @return true to @return void (with or without return type depending on PHP support), we should at least update the interface to document our actual contract.

what do you think @Stampie/collaborators ?

...HTTP 200 OK

Sample 200 OK responses from Mandrill:

[
    {
        "email": "[email protected]",
        "status": "sent",
        "_id": "e985ec5dbced4fcd9eae1226ec475a55",
        "reject_reason": null
    }
]

[
    {
        "email": "[email protected]",
        "status": "rejected",
        "_id": "e985ec5dbced4fcd9eae1226ec475a55",
        "reject_reason": "invalid-sender"
    }
]

I'm getting the following error on using MailGun:

Fatal error:  Uncaught exception 'Guzzle\Http\Exception\ClientErrorResponseException' with message 'Client error response
[status code] 400
[reason phrase] BAD REQUEST
[url] https://api.mailgun.net/v2/mg.mydomain.com/messages' in vendor\guzzle\guzzle\src\Guzzle\Http\Exception\BadResponseException.php:43

Stack trace:

#0 vendor\guzzle\guzzle\src\Guzzle\Http\Message\Request.php(145): Guzzle\Http\Exception\BadResponseException::factory(Object(Guzzle\Http\Message\EntityEnclosingRequest), Object(Guzzle\Http\Message\Response))

#1 [internal function]: Guzzle\Http\Message\Request::onRequestError(Object(Guzzle\Common\Event), 'request.error', Object(Symfony\Component\EventDispatcher\EventDispatcher))

#2 vendor\symfony\event-dispatcher\Symfony\Component\EventDispatcher\EventDispatcher.php(164): call_user_func(Array, Object(Guzzle\Common\Event), 'request.error', Object(Symfony\Component\EventDispatcher\EventDispatcher))

#3 vendor\symfony\eve in vendor\guzzle\guzzle\src\Guzzle\Http\Exception\BadResponseException.php on line 43

The code is working fine with Mandrill.

This aim to clean the test suite to reduce tests complexity.

@stof is it what you have in mind for #96?

• [x] Rewrite MailGun tests.
• [x] Rewrite Mandrill tests.
• [x] Rewrite Postmark tests.
• [x] Rewrite SendGrid tests.