README

This package provides a flexible way to assist you in extending the Laravel mail service, it is the missing multi-mail implementation for Laravel 5.3.

The Laravel mail service provides a number of elegant ways to send e-mails, such as Mailer (the Mail facade), Mailable, MailableMailer, and the new Mail Notification. Before getting started using this package, make sure you have read the official mail documentation. This package will not change the way you are already familiar with sending e-mails, but help you customize the Laravel mail service, such as managing multi mail drivers at runtime, handling messages that are ultimately sent.

Installation
Architecture
Usage Examples
License

Installation

Install this package using the Composer manager:

$ composer require elfsundae/laravel-multi-mail

Replace Illuminate\Mail\MailServiceProvider::class with ElfSundae\Multimail\MailServiceProvider::class in the config/app.php file.

Architecture

ElfSundae\Multimail\Mailer (extends Illuminate\Mail\Mailer)

The Mailer class is the facade and the maincenter of the Laravel mail system, all sending tasks will be handled by this class. You may access it using the Mail facade or app('mailer') helper function, as well as the Mailer type-hint or dependency injection.
ElfSundae\Multimail\SwiftMailerManager

The SwiftMailerManager singleton manages all Swift Mailer instances and their corresponding Swift Transport instances for the Mailer, it creates, caches, resets or destroys them. Each Swift Mailer instance is identified by the driver name of its transporter, such as smtp, mailgun, etc. You may access the manager via Mail::getSwiftMailerManager(), app('swift.manager'), SwiftMailerManager type-hint or dependency injection.
ElfSundae\Multimail\MessageHelper

It provides several helper methods for operating the mail messages, such as getting domain names of the email addresses for the mail recipients.

Usage Examples

Below are several examples of usage. Remember, you can do any customization as you want.

Custom Mail Drivers

Laravel ships with a handful of mail drivers, but you may want to write your own drivers to send emails via other mail services. Laravel makes it simple. By using the extend method of the TransportManager singleton, you can register a custom driver creator.

<?php

namespace App\Providers;

use Illuminate\Mail\TransportManager;
use Illuminate\Support\ServiceProvider;
use App\Support\Mail\FooTransport;

class AppServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->resolving(function (TransportManager $manager) {
            $manager->extend('foo', function ($app) {
                $config = $app['config']['services.foo'];

                return new FooTransport($config['key'], $config['secret']);
            });
        });
    }
}

Changing The Default Driver

Instead of using the mail driver that specified in the config/mail.php file, you may change the default driver at runtime via the mailDriver method.

Mail::mailDriver('mailgun')->to($user)->send(new OrderShipped($order));

💡 Note: Changing the mail driver at runtime will not affect the driver of a queueing sending job, it is only effectual during the current app lifetime.

Processing The Final Messages

This package makes it possible to process every final mail message just before sending the mail. To do so, register a global message handler via the registerSendingMessageHandler method.

<?php

namespace App\Providers;

use ElfSundae\Multimail\Mailer;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->resolving(function (Mailer $mailer) {
            $mailer->registerSendingMessageHandler(function ($message) {
                $message->addBcc('syslog@example.com');
            });
        });
    }
}

The first parameter passed to the handler is the mail message typed of Swift_Message, and you are free to type-hint additional dependencies.

$mailer->registerSendingMessageHandler(
    function (CacheRepository $cache, SwiftMailerManager $swift, $message, $mailer) {
        //
    }
);

In addition to Closure, the handler can also be registered with a class name. Before sending mail, the sendingMail method of this class will be called.

$mailer->registerSendingMessageHandler('App\Mail\Handler\SendingMessage');

Of course you can specify the method name:

$mailer->registerSendingMessageHandler('App\Mail\Handler\SendingMessage@sendingMailHandler');

Altering Driver For Mail Message

The return value of the sending message handler can be a mail driver name, and by this way the mail will be sent using the specified driver.

$mailer->registerSendingMessageHandler(function ($message) {
    if (preg_match_all(
        '#@(.+\.)?(qq.com|126.com|163.com|sina.com|sina.cn)$#im',
        implode(PHP_EOL, MessageHelper::getRecipients($message))
    )) {
        return 'directmail';
    }
});

Resetting Swift Mailers

Using the resetMailer or resetMailers method of the SwiftMailerManager, you can reset created Swift Mailer instances.

$this->updateMailConfig();

Mail::getSwiftMailerManager()->resetMailers();

License

The MIT License.

elfsundae / laravel-multi-mail

Maintainers

Details