Getting Started

Minimal Setup

Installation

composer require cooperspeele/twig-mailer-bundle

Add to config/bundles.php (Symfony):

Cooperspeele\TwigMailerBundle\TwigMailerBundle::class => ['all' => true],

Configure Twig Mailer Update config/packages/twig_mailer.yaml (Symfony) or manually configure in Laravel via config/twig_mailer.php:

twig_mailer:
    mailer: 'mailer' // Laravel's default mailer
    from_address: 'noreply@example.com'
    from_name: 'Your App'

First Use Case Create a Twig template (resources/views/emails/welcome.twig):

<html>
    <body>
        <h1>Welcome, {{ name }}!</h1>
    </body>
</html>

Send an email in Laravel:

use Cooperspeele\TwigMailerBundle\Mailer\TwigMailer;

$mailer = app(TwigMailer::class);
$mailer->send('emails.welcome', ['name' => 'John'], 'Welcome Email', [
    'to' => 'user@example.com'
]);

Implementation Patterns

Workflows

Template-Based Emails
- Store all email templates in resources/views/emails/ with .twig extension.
- Use Twig syntax for dynamic content (e.g., {{ user.name }}).
Reusable Components
- Create partials (e.g., header.twig, footer.twig) in resources/views/emails/_partials/.
- Include them in templates:
```
{% include '_partials/header.twig' %}
```

Dynamic Recipients

Loop through users in Twig:

{% for user in users %}
    <p>{{ user.email }}: {{ user.message }}</p>
{% endfor %}

Pass an array of recipients in Laravel:

$mailer->send('emails/newsletter', ['users' => $users], 'Newsletter', [
    'to' => ['user1@example.com', 'user2@example.com']
]);

Attachments

Attach files via Laravel’s Mailable or directly:

$mailer->send('emails/invoice', ['invoice' => $invoice], 'Invoice', [
    'to' => 'client@example.com',
    'attachments' => ['/path/to/invoice.pdf' => 'invoice.pdf']
]);

Queueing Emails

Use Laravel’s queue system with the Twig mailer:

$mailer->queue('emails/welcome', ['name' => 'John'], 'Welcome Email', [
    'to' => 'user@example.com'
]);

Integration Tips

Laravel Notifications: Extend Mailable to use TwigMailer:

public function build()
{
    return $this->markdown('emails.welcome')
                ->with(['name' => $this->user->name]);
}

(Note: Requires minor adjustments to use Twig instead of Blade.)

Testing: Use Laravel’s MailFake or mock TwigMailer in tests:

$mailer = Mockery::mock(TwigMailer::class);
$mailer->shouldReceive('send')->once();

Gotchas and Tips

Pitfalls

Twig vs. Blade Confusion
- The bundle uses Twig, not Blade. Avoid mixing syntax (e.g., @foreach won’t work).
- Fix: Stick to Twig tags ({% %}) and functions ({{ }}).
Mailer Configuration Overrides
- If mailer key in twig_mailer.yaml is misconfigured, emails may fail silently.
- Debug: Check Laravel’s config/mail.php for valid transport settings (e.g., mailgun, ses).
Template Paths
- Twig templates must be in resources/views/emails/ or a custom path configured in the bundle.
- Fix: Set twig_mailer.template_path in config if using a non-standard path.
Caching Issues
- Twig templates aren’t auto-reloaded in development. Clear cache after changes:
```
php artisan view:clear
```
Recipient Format
- The to parameter expects an array or string (e.g., ['user@example.com'] or 'user@example.com').
- Gotcha: Passing a raw string without brackets may cause errors.

Debugging

Enable Twig Debugging: Add to config/twig_mailer.php:
```
twig_mailer:
    debug: true
```
Errors will show detailed Twig stack traces.

Log Sent Emails: Use Laravel’s mail log:

Mail::pretend(true); // Log emails instead of sending

Extension Points

Custom Twig Extensions Add extensions in config/twig_mailer.php:

twig_mailer:
    twig:
        extensions:
            - App\Twig\CustomExtension

Override Mailer Class Bind a custom mailer in AppServiceProvider:

$this->app->bind(TwigMailer::class, function ($app) {
    return new CustomTwigMailer($app['mailer'], $app['twig']);
});

Event Listeners Listen for TwigMailerEvents (if the bundle emits them) or wrap the mailer in a decorator for pre/post-send logic.

Performance Tips

Precompile Twig Templates: Run php artisan twig:compile to cache templates (useful for production).

Batch Emails: For bulk sends, queue emails with delays to avoid rate limits:

$mailer->later(now()->addMinutes(5), 'emails/newsletter', [...], 'Newsletter', ['to' => $recipients]);

Twig Mailer Bundle Laravel Package