Mailer Laravel Package

Getting Started

Begin by installing the package via Composer:

composer require spiral/mailer

Then register the mailer bootstrapper in your Spiral application’s app/config/boot.php (or equivalent bootstrap file):

(new Spiral\Boot\Bootloader\Bootloader())->addBootloader(\Spiral\Mailer\Bootloader\MailerBootloader::class);

After registration, configure your mailer transport(s) in app/config/mailer.php, for example:

return [
    'default' => 'smtp',
    'transports' => [
        'smtp' => [
            'dsn' => 'smtp://user:pass@localhost:25',
            'options' => ['timeout' => 10],
        ],
    ],
];

Your first use case will likely be sending a transactional email:

$mailer = $container->get(\Spiral\Mailer\MailerInterface::class);
$mailer->send('welcome@example.com', 'Welcome!', 'Hello, thanks for joining!', 'text/plain');

Implementation Patterns

Use message objects for richer composition and testability:

use Spiral\Mailer\Message\EmailMessage;

$message = (new EmailMessage())
    ->from('noreply@example.com')
    ->to('user@example.com')
    ->subject('Verify your account')
    ->textBody('Click here to verify: https://...')
    ->htmlBody('<a href="https://...">Verify</a>');

$mailer->send($message);

For workflow integration, inject MailerInterface into services or commands (e.g., user registration flow):

public function registerUser(UserDTO $dto): void
{
    // persist user...
    $this->mailer->send(
        (new EmailMessage())
            ->to($dto->email)
            ->subject('Welcome')
            ->htmlBody($this->view->render('emails/welcome', ['user' => $dto]))
    );
}

Use config-driven environment swapping: set MAILER_DSN in .env, referenced in mailer.php config, allowing seamless transition between local SMTP, Mailtrap, or production SMTP/SES without code changes.
Leverage dependency injection: the MailerInterface is bound to a service-aware instance—ideal for unit testing with mocks or mock mailers.

Gotchas and Tips

⚠️ No default transport: If no transport is defined or MAILER_DSN missing, send() fails silently or throws, depending on transport—always validate config in dev environments.
⚠️ Message types matter: Mixing string content types with EmailMessage objects can cause type-hint mismatches—prefer strongly-typed message builders for maintainability.
💡 Extensibility hooks: Extend AbstractTransport to add custom backends (e.g., AWS SES SDK, custom APIs); register them in config and bind via TransportInterface.
💡 Debugging: Enable debug mode in config to dump messages to php://stderr instead of sending—useful for local testing.
💡 Testing: Use Spiral\Mailer\Testing\CapturedMessageCollector (if available) or mock MailerInterface in unit tests—avoid sending real emails in CI.
💡 Template integration: Use Spiral’s View component to render HTML/text templates and inject into EmailMessage bodies for DRY, reusable email views.
⚠️ Dead in maintenance: Since last release was in 2020-04-30, verify compatibility with modern Spiral versions (≥3.0) or consider alternatives like Symfony Mailer if actively maintained features are needed.