A more flexible email message builder for Laravel 5 including chained methods, reusable message type configurations, and email layout and template view management.

Note: All Larablocks packages will have releases in line with the major Laravel framework version release. (Ex. Pigeon 5.4.* is tested to work with Laravel 5.4.* while Pigeon 5.1.* is tested to worked with Laravel 5.1.*)

Add larablocks/pigeon as a requirement to composer.json:

{
    "require": {
        "larablocks/pigeon": "~5.4"
    }
}

Update your packages with composer update or install with composer install.

To wire this up in your Laravel project you need to add the service provider. Open app.php, and add a new item to the providers array.

Larablocks\Pigeon\PigeonServiceProvider::class,

Then you may add a Facade for more convenient usage. In your app.php config file add the following line to the aliases array.

'Pigeon' => Larablocks\Pigeon\Pigeon::class,

Note: The Pigeon facade will load automatically, so you don't have to add it to the app.php file but you may still want to keep record of the alias.

To publish the default config file config/pigeon.php along with the default email view files use the artisan command:

php artisan vendor:publish --provider="Larablocks\Pigeon\PigeonServiceProvider"

If you wish to not publish the view files and only publish the config then use the artisan command:

php artisan vendor:publish --provider="Larablocks\Pigeon\PigeonServiceProvider" --tag="config"

Pigeon::

Pigeon will load all properties set in the default area of your config before you construct your message.

####Set message addresses:

All these address add methods can be used with any of the address add functions (to, cc, bcc, replyTo, from, sender)

Add a single address with no name

Pigeon::to('[email protected]') 
Pigeon::cc('[email protected]') 
Pigeon::bcc('[email protected]') 
Pigeon::replyTo('[email protected]') 
Pigeon::from('[email protected]') 
Pigeon::sender('[email protected]') 

Add a single address with name

Pigeon::to('[email protected]', 'John Doe')
....

Add array of addresses with no names

Pigeon::to(['[email protected]', '[email protected]']) 
...

Add array of addresses some with names, some without names

Pigeon::to(['[email protected]' => 'John Doe', '[email protected]']) 
...

####Set Subject:

Pigeon::subject('My Subject') 

####File Attachments:

Attach a single file with no options

Pigeon::attach('/path/to/file/attachment')

Attach a single file with options

Pigeon::attach('/path/to/file/attachment', ['as' => 'Attachment', 'mime' => 'jpg'])

Attach an array of files

Pigeon::attach([
    [
     'path' => '/path/to/file/attachment1'
     'options' => []
    ],
    [
     'path' => '/path/to/file/attachment2'
     'options' => ['as' => 'Attachment 2', 'mime' => 'pdf']
    ]
])

####Set layout view file:

Pigeon::layout('emails.layouts.my_layout_view')

####Set template view file:

Pigeon::template('emails.templates.my_template_view')

####Passing View Variables:

Passing simple variables:

Pigeon::pass([
 'stringVariable' => 'test string', 
 'intVariable' => 2, 
 'boolVariable' => true
])

Passing object variables:

$user = new User();
$user->first_name = 'John';
$user->last_name = 'Doe';
Pigeon::pass([
 'userObjectVariable' => $user
])

If pass() is used more than once it will merge previously passed variables with the current passed set.

Note: Make sure all variables pre-defined in your layout and template view files are passed to your Pigeon message.

####Clearing View Variables:

Clear all previously passed view variables

Pigeon::clear()

Custom message types will be configured in the config/pigeon.php file. In this file you can find examples on how to properly set up a custom message type.

Set your defaults for all messages sent with Pigeon in config\pigeon.php

'default' => [
    'to' => [],
    'cc' => [],
    'bcc' => [],
    'replyTo' => [],
    'from' => [], // if nothing is entered here, your mail.php default will still be used
    'sender' => [],
    'attachments' => [],
    'subject' => 'Pigeon Delivery',
    'layout' => 'emails.layouts.default',
    'template' => 'emails.templates.default',
    'message_variables' => []
]

####Load Custom Message:

Set your defaults for a particular message type to be sent with Pigeon in config\pigeon.php

'custom_message_type' => [
    'from' => ['[email protected]' => 'My Custom App'],
    'subject' => 'My Pigeon Custom Message',
    'layout' => 'emails.layouts.default',
    'template' => 'emails.templates.default'
]

This will load all the message properties from your config defined for custom_message_type.

Pigeon::type('custom_message_type');

Default -> Custom Message (if set and loaded) -> Properties set with individual Pigeon functions

####Send Message:

Pigeon::send();

####Send Raw Message:

Pass a string as a param for the send() function and it will use the string as a raw message send and will ignore any view files or view variables assigned.

Pigeon::send('This is my raw message');

Pigeon::to(['[email protected]', '[email protected]'])
->cc('[email protected]')
->bcc('[email protected]')
->subject('This is the Subject')
->attach('/path/to/file/attachment')
->layout('emails.layouts.my_layout_view')
->template('emails.templates.my_template_view')
->pass(['firstVariable' => 'test string', 'secondVariable' => 2, 'thirdVariable' => true])
->send();

Pigeon::to('[email protected]')->subject('Testing Pigeon')->send('Sending myself a quick raw message');

Pigeon::type('custom_message_type')->to('[email protected]')->send();

To pass Pigeon as a dependency will will pass the interface Larablocks\Pigeon\PigeonInterface. For now the only library that implements this interface is Larablocks\Pigeon\IlluminateMailer provided by Laravel but we want to allow for other mailing libraries to be used in the future. The config/pigeon.php config file for Pigeon automatically sets IlluminateMailer as the default mailer library for you.

'library' => 'IlluminateMailer',

###Passing Pigeon to a constructor:

public function __construct(Larablocks\Pigeon\PigeonInterface $pigeon) 
{
$this->pigeon = $pigeon;
}

###Starting a new default message:

$this->pigeon->to('[email protected]')->subject('Pigeon Raw Test Message')->send('Sending myself a quick raw message');

###Starting a new custom message type:

$this->pigeon->type('custom_message_type')->to('[email protected]')->send();

Pigeon is open-sourced software licensed under the MIT license