(wip) update

README.md

@@ -6,7 +6,7 @@ This module provides functionality to send emails via the Mailgun API and store
 
 See [composer.json](./composer.json)
 
-+ silverstripe/framework ^4
++ silverstripe/framework ^5
 + Symbiote's [Queued Jobs](https://github.com/symbiote/silverstripe-queuedjobs) module
 + Mailgun PHP SDK ^3, kriswallsmith/buzz, nyholm/psr7
 
@@ -17,7 +17,7 @@ You need:
 * A Mailgun account
 * At least one non-sandbox Mailgun mailing domain ([verified is best](https://documentation.mailgun.com/en/latest/user_manual.html#verifying-your-domain)) in your choice of region
 * A Mailgun API key or a [Mailgun Domain Sending Key](https://www.mailgun.com/blog/mailgun-ip-pools-domain-keys) for the relevant mailing domain (the latter is recommended)
-* MailgunEmail and MailgunMailer configured in your project (see below)
+* The correct configuration in your project (see below)
 
 ## Installing
 
@@ -27,224 +27,23 @@ composer require nswdpc/silverstripe-mailgun-sync
 
 ## Configuration
 
-### Mailgun account
-
-Configuration of your Mailgun domain and account is beyond the scope of this document but is straightforward.
-
-You should verify your domain to avoid message delivery issues. The best starting point is [Verifying a Domain](https://documentation.mailgun.com/en/latest/user_manual.html#verifying-your-domain).
-
-MXToolBox.com is a useful tool to check your mailing domain has valid DMARC records.
-
-### Module
-
-Add the following to your project's yaml config:
-```yml
----
-Name: local-mailgunsync-config
-After:
-  - '#mailgunsync'
----
-# API config
-NSWDPC\Messaging\Mailgun\Connector\Base:
-  # your Mailgun mailing domain
-  api_domain: 'configured.mailgun.domain'
-  # your API key or Domain Sending Key
-  api_key: 'xxxx'
-  # the endpoint region, if you use EU set this value to 'API_ENDPOINT_EU'
-  # for the default region, leave empty
-  api_endpoint_region: ''
-  # this setting triggers o:testmode='yes' in messages
-  api_testmode: true|false
-  # You will probably want this as true, when false some clients will show 'Sent on behalf of' text
-  always_set_sender: true
-  # set this to override the From header, this is useful if your application sends out mail from anyone (see DMARC below)
-  always_from: '[email protected]'
-  # Whether to send via a job - see below
-  send_via_job: 'yes|no|when-attachments'
-  # When set, messages with no 'To' header are delivered here.
-  default_recipient: ''
-  # grab this from your Mailgun account control panel
-  webhook_signing_key: ''
-  # whether you want to store webhook requests
-  webhooks_enabled: true|false
-  # the current or new filter variable (see webhooks documentation in ./docs)
-  webhook_filter_variable: ''
-  # the previous one, to allow variable rotation
-  webhook_previous_filter_variable: ''
----
-# Configure the mailer
-Name: local-mailer
-After:
-  # Override core email configuration
-  - '#emailconfig'
-  # replace TaggableEmail with MailgunEmail
-  - '#nswdpc-taggable-email'
----
-SilverStripe\Core\Injector\Injector:
-  SilverStripe\Control\Email\Email:
-    class: 'NSWDPC\Messaging\Mailgun\MailgunEmail'
-  SilverStripe\Control\Email\Mailer:
-    class: 'NSWDPC\Messaging\Mailgun\MailgunMailer'
-```
-
-> Remember to flush configuration after a configuration change.
-
-See [detailed configuration, including project tags](./docs/en/005-detailed_configuration.md)
-
-## Sending
-
-### Mailer
-
-For a good example of this, look at the MailgunSyncTest class. Messages are sent using the default Silverstripe Email API:
-
-```php
-use SilverStripe\Control\Email\Email;
-
-$email = Email::create();
-$email->setFrom($from);
-$email->setTo($to);
-$email->setSubject($subject);
-```
-To add custom parameters used by Mailgun you call setCustomParameters():
-```php
-
-// variables
-$variables = [
-    'test' => 'true',
-    'foo' => 'bar',
-];
-
-//options
-$options = [
-    'testmode' => 'yes',
-    'tag' => ['tag1','tag2','tag4'],
-    'tracking' => 'yes',
-    'require-tls' => 'yes'
-];
-
-// headers
-$headers = [
-    'X-Test-Header' => 'testing'
-];
-
-$recipient_variables = [
-    '[email protected]' => ["unique_id" => "testing_123"]
-];
-
-$args = [
-    'options' => $options,
-    'variables' => $variables,
-    'headers' => $headers,
-    'recipient-variables' => $recipient_variables
-];
-
-$email->setCustomParameters($args)
-```
-Where `$args` is an array of [your custom parameters](https://documentation.mailgun.com/en/latest/api-sending.html#sending). Calling setCustomParameters() multiple times will overwrite previous parameters.
-
-Send the message:
-```php
-$response = $email->send();
-```
-
-The response will either be a Mailgun message-id OR a `Symbiote\QueuedJobs\DataObjects\QueuedJobDescriptor` instance if you are sending via the queued job.
-
-### Via API connector
-
-You can send directly via the API connector, which handles client setup and the like based on configuration.
-For a good example of this, look at the MailgunMailer class
-
-```php
-use NSWDPC\Messaging\Mailgun\Connector\Message;
-
-//set parameters
-$parameters = [
-    'to' => ...,
-    'from' => ...,
-    'o:tag' => ['tag1','tag2']
-    // etc
-];
-$connector = Message::create();
-$response = $connector->send($parameters);
-```
-The response will either be a Mailgun message-id OR a `Symbiote\QueuedJobs\DataObjects\QueuedJobDescriptor` instance if you are sending via the queued job.
-
-### Direct to Mailgun PHP SDK
-
-If you like, you can send messages and interact with the Mailgun API via the Mailgun PHP SDK:
-
-```php
-use Mailgun\Mailgun;
-
-$client = Mailgun::create($api_key);
-// set things up then send
-$response = $client->messages()->send($domain, $parameters);
-```
-
-The response will be a `Mailgun\Model\Message\SendResponse` instance if successful.
-
-See the [Mailgun PHP SDK documentation](https://github.com/mailgun/mailgun-php) for examples.
-
-## Queued Jobs
-
-The module uses the [Queued Jobs](https://github.com/symbiote/silverstripe-queuedjobs) module to deliver email at a later time.
-
-This way, a website request that involves delivering an email will not be held up by API issues.
-
-### SendJob
-
-This is a queued job that can be used to send emails depending on the ```send_via_job``` config value -
-+ 'yes' - all the time
-+ 'when-attachments' - only when attachments are present, or
-+ 'no' - never (in which case messages will never send via a Queued Job)
-
-Messages are handed off to this queued job, which is configured to send after one minute. Once delivered, the message parameters are cleared to reduce space used by large messages.
-
-This job is marked as 'broken' immediately upon an API or other general error. Please read the Queued Jobs Health Check documentation to get assistance with Broken job reporting.
-
-### TruncateJob
-
-Use this job to clear out older MailgunEvent webhook records. If you don't use webhooks to store events, this job can remain unused.
-
-### RequeueJob
-
-Use this job to kick broken SendJob instances, which happen from time-to-time due to API or connectivity issues.
-
-This job will:
-1. Take all job descriptor records for SendJob that are Broken
-1. Reset their status, processing counts and worker value to default initial values
-1. Set them to start after a minute
-1. Save the record
-
-On the next queue run, these jobs will attempt to send again.
-
-## Manual Resubmission
-
-Messages can be resent from the Mailgun control panel. This depends on your Message Retention setting for the relevant mailing domain in Mailgun.
-
-## DMARC considerations
-
-When sending email it's wise to consider how you maintain the quality of your mailing domain (and IP(s)).
-
-If your mailing domain is "mg.example.com" and you send "From: [email protected]" DMARC rules will most likely kick in at the recipient mail server and your message will be quarantined or rejected (unless example.net designates example.com as a permitted sender).  Instead, use a From header of "[email protected]" or "[email protected]" in your messages.
-
-Your Reply-To header can be any valid address.
-
-See [dmarc.org](https://dmarc.org) for more information on the importance of DMARC, SPF and DKIM
-
-
-## Tests
+See [Getting Started](./docs/en/001-index.md)
 
-Unit tests: [./tests](./tests). Tests use the [TestMessage](./tests/TestMessage.php) connector.
+### Breaking changes
 
-### Sending emails using sandbox/testmode
+## 5.0 release
 
-For acceptance testing, you can use a combination of the Mailgun sandbox domain and API testmode.
+This version refactored the module to support the `silverstripe/framework` change to using `symfony/mailer` and is not backwards compatible with previous versions. When updating your project, be aware of the following changes:
 
-+ Sandbox domain: set the `api_domain` value in configuration to the sandbox domain provided by Mailgun. Remember to list approved recipients in the sandbox domain settings in the Mailgun control panel.
-+ Test mode: set the `api_testmode` value to true. In testmode, Mailgun accepts but does not deliver messages.
++ Configuration is done via a symfony mailer DSN, either in project yml or environment variable
++ MailgunMailer was removed, almost all functionality was moved to the `MailgunSyncApiTransport`
++ Namespace updates to reflect psr-4
++ The `api_domain`, `api_key` and `api_endpoint_region` configuration values were removed (see DSN)
++ Default recipient handling was removed
++ 'Always from' handling was removed, Email.send_all_emails_from is now the only way to do this
++ All client connectors that extend `Base` must now provide a `Dsn` or a string that a `Dsn` can be created from:
 
-## Breaking changes in 1.0 release
+## 1.0 release
 
 Version 1 removed unused features to reduce the complexity of this module.
 

_config/config.yml

@@ -1,28 +1,19 @@
 ---
-Name: mailgunsync
+Name: 'mailgunsync'
 ---
 # API config
 NSWDPC\Messaging\Mailgun\Connector\Base:
-  api_domain: ''
-  api_key: ''
+  # API settings
   api_testmode: false
-  api_endpoint_region: ''
-  webhooks_enabled: true
+  # whether to enable webhooks or not
+  webhooks_enabled: false
+  # the Mailgun webhook signing key
   webhook_signing_key: ''
   # the current or new filter variable
   webhook_filter_variable: ''
   # the previous one, to allow variable rotation
   webhook_previous_filter_variable: ''
-  always_set_sender : true
+  # whether to always set the Sender header (true) or not (false)
+  always_set_sender: true
   # yes|no|when-attachments
-  send_via_job : 'when-attachments'
-  default_recipient : ''
-# Mailer config
-NSWDPC\Messaging\Mailgun\Email\MailgunMailer:
-   always_from: ''
----
-Name: mailgunsyncqueue
----
-Symbiote\QueuedJobs\DataObjects\QueuedJobDescriptor:
-  db:
-    SavedJobData : 'NSWDPC\Messaging\Mailgun\ORM\FieldType\DBLongText'
+  send_via_job: 'when-attachments'

_config/mailer.yml

@@ -0,0 +1,10 @@
+---
+Name: 'mailgunsync-mailer'
+After:
+  '#mailer'
+---
+SilverStripe\Core\Injector\Injector:
+  # override the core transport factory to ensure that the Mailgun Api transport
+  # factor is registered as a transport factory
+  SilverStripe\Control\Email\TransportFactory:
+    class: 'NSWDPC\Messaging\Mailgun\Transport\TransportFactory'

_config/queuedjobs.yml

@@ -0,0 +1,6 @@
+---
+Name: 'mailgunsync-queue'
+---
+Symbiote\QueuedJobs\DataObjects\QueuedJobDescriptor:
+  db:
+    SavedJobData : 'NSWDPC\Messaging\Mailgun\ORM\FieldType\DBLongText'

_config/routes.yml

@@ -1,8 +1,8 @@
 ---
-Name: nswdpc_mailgunsync_routes
+Name: 'mailgunsync-routes'
 After:
   - '#coreroutes'
 ---
 Silverstripe\Control\Director:
   rules:
-    '_wh//$Action/$ID/$OtherID': 'NSWDPC\Messaging\Mailgun\MailgunWebHook'
+    '_wh//$Action/$ID/$OtherID': 'NSWDPC\Messaging\Mailgun\Controllers\MailgunWebHook'

_config/taggable.yml

@@ -1,5 +1,5 @@
 ---
-Name: 'mailgun-taggable-notifications'
+Name: 'mailgunsync-taggable-notifications'
 After:
   - '#nswdpc-taggable-notifications'
 ---