Skip to content

Commit

Permalink
Updating docs
Browse files Browse the repository at this point in the history 
Signed-off-by: Chris Hallgren <[email protected]>
  • Loading branch information
@challgren
challgren committed Dec 28, 2019
1 parent 30ccb58 commit 11cf0d3
Show file tree
Hide file tree
Showing 3 changed files with 94 additions and 83 deletions.
23 changes: 7 additions & 16 deletions UPGRADE.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,11 @@
# OUTDATED
# Upgrade from 1.x to 3.x
The release `3.0.0` is a major rewrite of `1.x` with some breaking changes. If you are upgrading to `3.x`, please follow the read the below points and update your codebase.
# Upgrade from 4.x to 5.x
The release `5.0.0` is a major update of `4.x` with some breaking changes. If you are upgrading to `5.x`, please follow the read the below points and update your codebase.

## Configuration
First, update your transport configuration in `app.php`, and use `Mailgun.Mailgun`.
First, move your transport configuration from `app.php` to `app_local.php`.

```php
'EmailTransport' => [
...
'mailgun' => [
'className' => 'Mailgun.Mailgun',
'apiEndpoint' => 'https://api.mailgun.net/v3', // optional, api endpoint
Expand All @@ -16,19 +14,12 @@ First, update your transport configuration in `app.php`, and use `Mailgun.Mailgu
]
]
```
> In 1.x, the className was `MailgunEmail.Mailgun`. Additionaly, you can change the API url as well, leave blank to use the default api endpoint.
#### Load Plugin
Change the plugin name in your `Plugin::load()`.
```php
Plugin::load(‘Mailgun');
```
> In `1.x`, the plugin name was `MailgunEmail`.

## Usage
In `1.x`, for setting custom headers and options, the `addHeaders()` was used. In `3.x`, we have separate functions to do all these jobs.
- [Custom Headers](https://github.com/narendravaghela/cakephp-mailgun#custom-headers)
- [Additional Options](https://github.com/narendravaghela/cakephp-mailgun#additional-options)
In `4.x`, MailgunEmail provided convenience methods to change the email. As of CakePHP 4.0 using `Cake\Mailer\Email` is deprecated, so we've added a new MailgunTrait that works on `Cake\Mailer\Email` and `Cake\Mailer\Mailer`. And a default `Mailgun\Mailer\MailgunMailer` to support upgrading CakePHP 3.x code to CakePHP 4.x code.

- [Custom Headers](https://github.com/narendravaghela/cakephp-mailgun/tree/master/docs#custom-headers)
- [Additional Options](https://github.com/narendravaghela/cakephp-mailgun/tree/master/docs#additional-options)
- And more...

Please use appropriate method to set headers, options, recipient variables, etc.
Expand Down
142 changes: 75 additions & 67 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,12 @@
# CakePHP Mailgun Plugin Documentation

## FYI
These documents need updating for CakePHP 4.0 as we now have a Email, Mailer, and Trait available
## Version Map
See [Version Map](https://github.com/narendravaghela/cakephp-mailgun/wiki)

## Installation

You can install this plugin into your CakePHP application using [composer](http://getcomposer.org).

```ssh
composer require narendravaghela/cakephp-mailgun
```sh
$ composer require narendravaghela/cakephp-mailgun
```

[Load the plugin](https://book.cakephp.org/4.0/en/plugins.html#loading-a-plugin) in your `src/Application.php`'s boostrap() using:
Expand All @@ -18,7 +16,7 @@ $ bin/cake plugin load Mailgun

## Configuration

Set your Mailgun Api key and domain in `EmailTransport` settings in app.php or app_local.php
Set your Mailgun Api key and domain in `EmailTransport` settings in `app_local.php`

```php
'EmailTransport' => [
Expand Down Expand Up @@ -48,44 +46,50 @@ And create new delivery profile in `Email` settings.
```

## Usage
This plugin is compromised of 4 separate classes.

You can now simply use the CakePHP's `Email` to send an email via Mailgun.
`Mailgun\Mailer\MailgunTransport` Transport that converts the CakePHP message and sends it via the Mailgun API.

```php
$email = new MailgunEmail();
$email->setFrom(['[email protected]' => 'CakePHP Mailgun'])
->setTo('[email protected]')
->addCc('[email protected]')
->setSubject('Email from CakePHP Mailgun plugin')
->send('Message from CakePHP Mailgun plugin');
```
`Mailgun\Mailer\MailgunTrait` Trait that adds convenience methods for setting additional options that you can use in your custom mailer.

`Mailgun\Mailer\MailgunMailer` Mailer that adds the MailgunTrait to a `Cake\Mailer\Mailer` class. You can either extend this class or use the MailgunTrait.

`Mailgun\Mailer\MailgunEmail` **DEPRECATED** Email that adds the MailgunTrait to a `Cake\Mailer\Email` class.

That is it.
### Basic Usage
Once you've configured your transport you can begin sending emails by calling `Cake\Mailer\Mailer::setTransport('mailgun')` or use the provided MailgunEmail or MailgunMailer. To set additional options when using Mailgun you may manually set the headers with `Cake\Mailer\Mailer::addHeaders(['X-Mailgun-Tag' => ['welcome', 'newuser'])`

## Advance Use
You can also use more options to customise the email message.
### Advanced Usage
If you have a custom `Cake\Mailer\Mailer` and you'd like convenience methods such as setTestMode(), deliveryBy(), etc add `use Mailgun\Mailer\MailgunTrait;` to the top of your class. Don't forget to update your Mailer's transport to use `'mailgun'`

### Additional Reading
[CakePHP Mailer 4.x](https://book.cakephp.org/4/en/core-libraries/email.html)

[Mailgun User Manual](https://documentation.mailgun.com/en/latest/user_manual.html)

## Documentation

### Custom Headers
You can pass your own headers. It must be prefixed with "X-". Use the default `Email::setHeaders` method like,
You can pass your own headers. It must be prefixed with "X-". Use the default `MailgunMailer::addHeaders` method like,

```php
$email = new MailgunEmail();
$email = new MailgunMailer();
$email->setFrom(['[email protected]' => 'CakePHP Mailgun'])
->setTo('[email protected]')
->setHeaders([
->addHeaders([
'X-Custom' => 'headervalue',
'X-MyHeader' => 'myvalue'
])
->setSubject('Email from CakePHP Mailgun plugin')
->send('Message from CakePHP Mailgun plugin');
->deliver('Message from CakePHP Mailgun plugin');
```

### Attachments
Set your attachments using `Email::setAttachments` method.
Set your attachments using `MailgunMailer::setAttachments` method. Mailgun API supports a max of 25MBs of attachments per message.

```php
$email = new MailgunEmail();
$email->setFrom(['you@yourdomain.com' => 'CakePHP Mailgun'])
$email = new MailgunMailer();
$email->setFrom(['you@example.com' => 'CakePHP Mailgun'])
->setTo('[email protected]')
->setAttachments([
'cake_icon1.png' => Configure::read('App.imageBaseUrl') . 'cake.icon.png',
Expand All @@ -94,38 +98,39 @@ $email->setFrom(['[email protected]' => 'CakePHP Mailgun'])
WWW_ROOT . 'favicon.ico'
])
->setSubject('Email from CakePHP Mailgun plugin')
->send('Message from CakePHP Mailgun plugin');
->deliver('Message from CakePHP Mailgun plugin');
```

> To send inline attachment, use `contentId` parameter while setting attachment. And then you can reference it in your HTML like `<img src="cid:cake.icon.png">`
### Template
### CakePHP Templates
You can use the your CakePHP's layout and template as your email's HTML body.

```php
$email = new MailgunEmail();
$email->setFrom(['[email protected]' => 'CakePHP Mailgun'])
->setTo('[email protected]')
->setLayout('newsletter') // in src/Template/Layout/Email/html/newsletter.ctp
->setTemplate('mailgun_email') // in src/Template/Email/html/mailgun_email.ctp
->send();
$email = new MailgunMailer();
$email->setFrom(['[email protected]' => 'CakePHP Mailgun'])
->setTo('[email protected]')
->viewBuilder()
->setLayout('newsletter') // in src/Template/Layout/Email/html/newsletter.ctp
->setTemplate('mailgun_email'); // in src/Template/Email/html/mailgun_email.ctp

$email->send();
```
> Mailgun does not provide template kind of thing :)

### Batch Sending
Mailgun provides an option to send email to a group of recipients through a single API call. Simple, add multiple recipients using `Email::setTo()` like,

```php
$email = new MailgunEmail();
$email = new MailgunMailer();
$email->setFrom(['[email protected]' => 'CakePHP Mailgun'])
->setTo('[email protected]')
->addTo(['[email protected]', '[email protected]']) // alternate way to add multiple
->setSubject('Email from CakePHP Mailgun plugin')
->send('Message from CakePHP Mailgun plugin');
->deliver('Message from CakePHP Mailgun plugin');
```

#### Recipient Variables
In case of sending batch emails, also use Recipient Variables. Otherwise, all recipients’ email addresses will show up in the to field for each recipient. To do so, you need to call `MailgunEmail->setRecipientVars()` method.
In case of sending batch emails, also use Recipient Variables. Otherwise, all recipients’ email addresses will show up in the to field for each recipient. To do so, you need to call `MailgunTrait->setRecipientVars()` method.
This also allows you to replace email content with recipient specific data. E.g. you would like to say recipient's name in the email body.

```php
Expand All @@ -135,108 +140,111 @@ $recipientVars = [
'[email protected]' => ['name' => 'John', 'city' => 'Toronto']
];

$email = new MailgunEmail();
$email = new MailgunMailer();
$email->setFrom(['[email protected]' => 'CakePHP Mailgun'])
->setTo('[email protected]')
->addTo(['[email protected]', '[email protected]'])
->setRecipientVars($recipientVars)
->setSubject('Hello %recipient.name%, welcome to %recipient.city%!')
->send('Message from CakePHP Mailgun plugin');
->deliver('Message from CakePHP Mailgun plugin');
```
> The keys of recipient variables must be the email address of recipients. Once set, you can use the %recipient.varname% in subject or body.
### Custom Message Data
You can attache some data to message. The data can be used in any webhook events related to the email. Use `setMailgunVars()` method and pass the required data. Read [this](https://documentation.mailgun.com/en/latest/user_manual.html#attaching-data-to-messages) for more details.
You can attach some data to message. The data can be used in any webhook events related to the email. Use `MailgunTrait->setMailgunVars()` method and pass the required data. Read [this](https://documentation.mailgun.com/en/latest/user_manual.html#attaching-data-to-messages) for more details.

```php
$email = new MailgunEmail();
$email = new MailgunMailer();
$email->setMailgunVars('my-custom-data', ["my_message_id" => 123])
->setFrom(['[email protected]' => 'CakePHP Mailgun'])
->setTo('[email protected]')
->addTo(['[email protected]', '[email protected]'])
->setSubject('Hello %recipient.name%, welcome to %recipient.city%!')
->send('Message from CakePHP Mailgun plugin');
->deliver('Message from CakePHP Mailgun plugin');
```

> The data must be an `Array`.
### Additional Options
You can also set a few more options in you email request like tagging, delivery time, test mode etc. For this, you need to use the `MailgunEmail->testMode()` method. Read [this](https://documentation.mailgun.com/en/latest/api-sending.html#sending) for detailed information.
You can also set a few more options in you email request like tagging, delivery time, test mode etc. For this, you need to use the `MailgunTrait->testMode()` method. Read [this](https://documentation.mailgun.com/en/latest/api-sending.html#sending) for detailed information.

#### Tagging
Tags are more in Mailgun's tracking features. You can assign multiple tags to email. Use `MailgunEmail->setTags()` as option name.
Tags are more in Mailgun's tracking features. You can assign multiple tags to email. Use `MailgunTrait->setTags()` as option name.

```php
$email = new MailgunEmail();
$email = new MailgunMailer();
$email->setTags('monthly newsletter');
$email->setTags(['newsletter', 'monthly newsletter']); // if multiple
$email->setFrom(['[email protected]' => 'CakePHP Mailgun'])
->setTo('[email protected]')
->addTo(['[email protected]', '[email protected]'])
->setSubject('Hello %recipient.name%, welcome to %recipient.city%!')
->send('Message from CakePHP Mailgun plugin');
->deliver('Message from CakePHP Mailgun plugin');
```

#### DKIM signature
You can enable/disable DKIM signature validation. Use `MailgunEmail->enableDkim()`
You can enable/disable DKIM signature validation. Use `MailgunTrait->enableDkim()`

```php
$email = new MailgunEmail();
$email->enableDkim();
$email = new MailgunMailer();
$email->enableDkim(true);
```
> Pass `true` or `false`. Default `true`.
#### Delivery Time
You can set the desired time of email message delivety. Use `MailgunEmail->deliverBy()`.
You can set the desired time of email message delivety. Use `MailgunTrait->deliverBy()`.

```php
$email = new MailgunEmail();
$email = new MailgunMailer();
$email->deliverBy(new \DateTime(strtotime('+1 day')));
```

> Note: Messages can be scheduled for a maximum of 3 days in the future as per Mailgun documentation. Pass a valid unix timestamp as a value.
#### Test Mode
Enables sending in test mode. Use `MailgunEmail->testMode()`
Enables sending in test mode. Use `MailgunTrait->testMode()`

```php
$email = new MailgunEmail();
$email->testMode();
$email = new MailgunMailer();
$email->testMode(true);
```
> Pass `true` or `false`. Default `false`.
#### Tracking Clicks
Enables/Disables click tracking on a per-message basis. Use `MailgunEmail->trackClicks`.
Enables/Disables click tracking on a per-message basis. Use `MailgunTrait->trackClicks`.

```php
$email = new MailgunEmail();
$email->trackClicks();
$email = new MailgunMailer();
$email->trackClicks(false);
```
> Pass `true` or `false`. Default `true`.
> Pass `true` or `false` or `null` to track clicks on HTML only email. Default `true`.
#### Tracking Opens
Enables/Disables click tracking on a per-message basis. Use `MailgunEmail->trackOpens`.
Enables/Disables click tracking on a per-message basis. Use `MailgunTrait->trackOpens`.

```php
$email = new MailgunEmail();
$email->trackClicks();
$email = new MailgunMailer();
$email->trackOpens(false);
```
> Pass `true` or `false`. Default `true`.
#### Require TLS
Sets the email sending over TLS connection. Use `MailgunEmail->requireTls()`.
Sets the email sending over TLS connection. Use `MailgunTrait->requireTls()`.

```php
$email = new MailgunEmail();
$email = new MailgunMailerl();
$email->requireTls(true);
```
> Pass `true` or `false`. Default `false`.
#### Skip Verification
Enables/Disable the hostname and certificate verification to establish TLS connection. Use `MailgunEmail->skipVerification()`
Enables/Disable the hostname and certificate verification to establish TLS connection. Use `MailgunTrait->skipVerification()`

```php
$email = new MailgunEmail();
$email->skipVerification();
$email = new MailgunMailer();
$email->skipVerification(true);
```
> Pass `true` or `false`. Default `false`.
## Problem?
If you face any issue or errors while upgrading, please open an issue [here](https://github.com/narendravaghela/cakephp-mailgun/issues).
12 changes: 12 additions & 0 deletions src/Mailer/MailgunMailer.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,4 +22,16 @@
class MailgunMailer extends Mailer
{
use MailgunTrait;

/**
* Constructor
*
* @param array|string|null $config Array of configs, or string to load configs from app.php
*/
public function __construct($config = null)
{
parent::__construct($config);

$this->setTransport('mailgun');
}
}

0 comments on commit 11cf0d3

Please sign in to comment.