Merge pull request #1 from zf-fr/architecture

Set interfaces

README.md

@@ -9,11 +9,88 @@ the provider
 ## Dependencies
 
 * PHP 7.0+
+* Guzzle 6.0+
 
 ## Installation
 
 Installation of ZfrMail is only officially supported using Composer:
 
 ```sh
 php composer.phar require 'zfr/zfr-mail:1.*'
-```
+```
+
+## Usage
+
+### Creating a mail
+
+The first thing is to create a mail. Mails are immutable and follow a similar logic to PSR-7 objects. There are
+two different kinds of mails in ZfrMail:
+
+* Rendered mails: those are mails that you are rendering yourself, so you set manually the text and HTML body. ZfrMail
+does not come with any integration with template engine such as Twig or Plates. It's up to you to render them.
+* Templated mails: some providers like Postmark or Mandrill provide a template system where the templates are stored
+in the provider. This allows non-technical people to edit the mail, and make maintenance easier. Make sure that the
+provider you are using supports templated emails before using it.
+
+For instance, here is how you can create a simple rendered email:
+
+```php
+$mail = (new RenderedMail())->withFrom('[email protected]')
+    ->withTo('[email protected]')
+    ->withSubject('Hello')
+    ->withTextBody('This is a mail')
+    ->withHtmlBody('<p>This is a mail</p>');
+```
+
+And a templated email:
+
+```php
+$mail = (new TemplatedMail())->withFrom('[email protected]')
+    ->withTo('[email protected]')
+    ->withTemplate('templ-1234')
+    ->withTemplateVariables(['first_name' => 'Foo']);
+```
+
+Mail can also accepts options. Those options are specific to the mail provider you're using. For instance, if
+you are using Postmark, the accepted options are (we're following Postmark convention on naming to make it easy):
+
+* `Tag`
+* `InlineCss`
+* `TrackOpens`
+* `Headers`
+
+### Configuring a mailer
+
+For now, ZfrMail provides integration with Postmark only. In order to configure Postmark, add the following code
+to your config:
+
+```php
+return [
+    'zfr_mail' => [
+        'postmark' => [
+            'server_token' => 'YOUR_SERVER_TOKEN'
+        ]
+    ],
+];
+```
+
+The server token can be found in your Postmark account.
+
+### Using the mailer
+
+You can now inject the `ZfrMail\Mailer\PostmarkMailer` class into your services. This class comes with a single
+`send` method. The mailer will automatically either send a templated or rendered mail for you:
+
+```php
+$mailer->send($mail);
+```
+
+> ZfrMail is meant to be a lightweight solution with minimal overhead. As a consequence, it does not any validation
+to check whether your email addresses are valid, or if you are properly formatting the options according to your
+chosen provider.
+
+## To-do
+
+* Add more providers
+* Better error support (for now it will throw Guzzle exceptions, but we may create some pre-defined exceptions
+in the future and extract those from the Guzzle error)

composer.json

@@ -20,8 +20,7 @@
     "require": {
         "php": "^7.0",
         "guzzlehttp/guzzle": "^6.0",
-        "container-interop/container-interop": "^1.1",
-        "psr/http-message": "^1.0"
+        "container-interop/container-interop": "^1.1"
     },
     "require-dev": {
         "phpunit/phpunit": "^5.2",

config/dependencies.global.php

@@ -1,6 +1,12 @@
 <?php
 
+use ZfrMail\Container\PostmarkMailerFactory;
+use ZfrMail\Mailer\PostmarkMailer;
+
 return [
     'dependencies' => [
+        'factories' => [
+            PostmarkMailer::class => PostmarkMailerFactory::class
+        ]
     ],
 ];

src/Container/PostmarkMailerFactory.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace ZfrMail\Container;
+
+use GuzzleHttp\Client as HttpClient;
+use Interop\Container\ContainerInterface;
+use ZfrMail\Exception\RuntimeException;
+use ZfrMail\Mailer\PostmarkMailer;
+
+/**
+ * @author Michaël Gallego
+ */
+class PostmarkMailerFactory
+{
+    /**
+     * @param  ContainerInterface $container
+     * @return PostmarkMailer
+     */
+    public function __invoke(ContainerInterface $container): PostmarkMailer
+    {
+        $config = $container->get('config');
+
+        if (!isset($config['zfr_mail']['postmark']['server_token'])) {
+            throw new RuntimeException(
+                "You didn't properly configure Postmark ZfrMail. Make sure to include the server token"
+            );
+        }
+
+        return new PostmarkMailer($config['zfr_mail']['postmark']['server_token'], new HttpClient());
+    }
+}

src/Exception/ExceptionInterface.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace ZfrMail\Exception;
+
+/**
+ * @author Michaël Gallego
+ */
+interface ExceptionInterface
+{
+}

src/Exception/RuntimeException.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace ZfrMail\Exception;
+
+use RuntimeException as BaseRuntimeException;
+
+/**
+ * @author Michaël Gallego
+ */
+class RuntimeException extends BaseRuntimeException implements ExceptionInterface
+{
+}

src/Mail/AbstractMail.php

@@ -0,0 +1,188 @@
+<?php
+
+namespace ZfrMail\Mail;
+
+/**
+ * @author Michaël Gallego
+ */
+abstract class AbstractMail implements MailInterface
+{
+    /**
+     * @var string
+     */
+    private $from = '';
+
+    /**
+     * @var string
+     */
+    private $to = '';
+
+    /**
+     * @var array
+     */
+    private $cc = [];
+
+    /**
+     * @var array
+     */
+    private $bcc = [];
+
+    /**
+     * @var string
+     */
+    private $replyTo = '';
+
+    /**
+     * @var AttachmentInterface[]
+     */
+    private $attachments = [];
+
+    /**
+     * @var array
+     */
+    private $options = [];
+
+    /**
+     * {@inheritDoc}
+     */
+    public function withFrom(string $from): MailInterface
+    {
+        $new = clone $this;
+        $new->from = $from;
+
+        return $new;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getFrom(): string
+    {
+        return $this->from;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function withTo(string $to): MailInterface
+    {
+        $new = clone $this;
+        $new->to = $to;
+
+        return $new;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getTo(): string
+    {
+        return $this->to;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function withCc(array $cc): MailInterface
+    {
+        $new = clone $this;
+        $new->cc = $cc;
+
+        return $new;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getCc(): array
+    {
+        return $this->cc;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function withBcc(array $bcc): MailInterface
+    {
+        $new = clone $this;
+        $new->bcc = $bcc;
+
+        return $new;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getBcc(): array
+    {
+        return $this->bcc;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function withReplyTo(string $replyTo): MailInterface
+    {
+        $new = clone $this;
+        $new->replyTo = $replyTo;
+
+        return $new;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getReplyTo(): string
+    {
+        return $this->replyTo;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function withAddedAttachment(AttachmentInterface $attachment): MailInterface
+    {
+        $new = clone $this;
+        $new->attachments[] = $attachment;
+
+        return $new;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function withAttachments(array $attachments): MailInterface
+    {
+        $new = clone $this;
+        $new->attachments = $attachments;
+
+        return $new;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getAttachments(): array
+    {
+        return $this->attachments;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function withOptions(array $options): MailInterface
+    {
+        $new = clone $this;
+        $new->options = $options;
+
+        return $new;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getOptions(): array
+    {
+        return $this->options;
+    }
+}