README

Sending email through Mailgun is a breeze, when sending from one domain only.
For any additional domains, the calling code needs to determine which mailer transport to use.
This can be especially annoying when the mailer to use depends on the sender, which is often set inside the mailable.

Using this package, the calling code is no longer concerned with the configured mailers.

<?php declare(strict_types=1);

// app/Mail/ImportantMessage.php
class ImportantMessage extends \Illuminate\Mail\Mailable
{
    public function build() : self
    {
        return $this
            ->subject('Important message')
            ->from('you@acme.tld') // The sender is often determined _inside_ the mailable
            ->view('...', []);
    }
}

/** @var \App\Mail\ImportantMessage $mailable */

// Without this package, the calling code has to select the right mailer 
\Illuminate\Support\Facades\Mail::mailer('mailgun-acme.tld')->to('j.doe@example.net')->queue($mailable);

// This package will handle the mailer configuration for you. So the above is as simple as;
\Illuminate\Support\Facades\Mail::to('j.doe@example.net')->queue($mailable);

Installation

You can install the package via composer:

composer require skitlabs/laravel-mailgun-multiple-domains

How it works

This package contains a listener that hooks into the Illuminate\Mail\Events\MessageSending event, which is dispatched just before sending the e-mail.
It then reconfigures the current Transport, based on the from domain in the message. This works for direct and queued messages alike, with no extra configuration!

Thanks to Laravel's auto-discovery (❤), no assembly required!

Requirements

There are a few requirements for this to work;

PHP 8.0, or 8.1
Laravel >= 9.0
Laravel needs to use symfony/mailer internally (default)

Older versions

Not using laravel 9 (yet)? Version 2 of this package supports laravel 7 and 8.

composer require skitlabs/laravel-mailgun-multiple-domains=^2.0

Usage

If you've configured mailgun under mg.{domain.tld}, and your secret works for all domains you are sending from; you're ready to start sending e-mail! 👍

Let's say you're sending a message as sales@acme.app. Just before sending the message, this package will set the mailgun domain to: mg.acme.app.

What if I need to customize my settings, per domain?

Add the sending domains to your mailgun configuration in the key domains.

If a domain is not specified, it defaults to mg.{domain.tld}.
If the secret or endpoint are not configured, these fallback to your configured global defaults.

<?php declare(strict_types=1);

// config/services.php

return [
    // ... Other services

    'mailgun' => [
        'domain' => env('MAILGUN_DOMAIN'),
        'secret' => env('MAILGUN_SECRET'),
        'endpoint' => env('MAILGUN_ENDPOINT', 'api.mailgun.net'),
        'domains' => [
            'example.net' => [
                'domain' => 'custom-mg-domain.example.net',
                'secret' => 'overwrite-the-secret-or-null',
                'endpoint' => 'overwrite-the-endpoint-or-null',
            ],
            'awesome.app' => [
                'secret' => 'only-change-the-secret-for-this-domain',
            ],
        ],
    ],
];

What if I need to customize how these settings are determined?

If the standard way of resolving sender properties is not suitable for your use-case, create a custom resolver that implements MailGunSenderPropertiesResolver. See the default implementation for inspiration.

Once you have your own concrete implementation, overwrite the default bind in any of your service providers;

<?php declare(strict_types=1);

use Illuminate\Support\ServiceProvider;
use SkitLabs\LaravelMailGunMultipleDomains\Contracts\MailGunSenderPropertiesResolver;

// app/Providers/AppServiceProvider.php
class AppServiceProvider extends ServiceProvider
{
    public function register()
    {
        // ...

        $this->app->bind(MailGunSenderPropertiesResolver::class, static function () : MailGunSenderPropertiesResolver {
            return new \Acme\CustomSenderPropertiesResolver();        
        });
    }
}

What if my mailer has a different name?

Specify the name of your mailer, as the second argument, when instantiating ReconfigureMailGunOnMessageSending.

<?php declare(strict_types=1);

use Illuminate\Support\Facades\Config;
use SkitLabs\LaravelMailGunMultipleDomains\Contracts\MailGunSenderPropertiesResolver;
use SkitLabs\LaravelMailGunMultipleDomains\Listeners\ReconfigureMailGunOnMessageSending;

Config::set('mail.default', 'custom-mailer-name');
Config::set('mail.mailers.custom-mailer-name', [
    'transport' => 'mailgun',
]);

/** @var MailGunSenderPropertiesResolver $resolver */
$handler = new ReconfigureMailGunOnMessageSending($resolver, 'custom-mailer-name');

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

The MIT License (MIT). Please see License File for more information.

skitlabs / laravel-mailgun-multiple-domains

Maintainers

Details