Skip to content

Xammie/mailbook

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Mailbook

Latest Version on Packagist GitHub Tests Action Status GitHub Code Style Action Status Total Downloads

Mailbook is a Laravel package that lets you easily inspect your mails without having to actually trigger it in your application.

Example screenshot

View demo

Installation

You can install the package via composer:

composer require --dev xammie/mailbook

Next install mailbook into your application

php artisan mailbook:install

Usage

The mailbook:install command will create a route file named routes/mailbook.php. In this file you can register your emails.

// This will use dependency injection if your mailable has parameters
Mailbook::add(VerificationMail::class);

// Use a closure to customize the parameters of the mail instance
Mailbook::add(function (): VerificationMail {
    $user = User::factory()->make();

    return new VerificationMail($user, '/example/url')
});

Next head over to /mailbook to preview the mailables.

Registering mails

You can both register mailables that live in App\Mails and email notifications in App\Notifications.

// Mailable
Mailbook::add(VerificationMail::class);

// Notification
Mailbook::add(InvoiceCreatedNotification::class);

You can also use dependency injection in the closure.

// With dependency injection
Mailbook::add(function (VerificationService $verificationService): VerificationMail {
    return new VerificationMail($verificationService, '/example/url');
});

// Without dependency injection
Mailbook::add(function (): VerificationMail {
    $verificationService = app(VerificationService::class);
    
    return new VerificationMail($verificationService, '/example/url');
});

Variants

When creating mails you might have a couple of different scenario's that you want to test for one mail, you can use variants to solve this.

// Use a closure to customize the parameters of the mail instance
Mailbook::add(OrderCreatedMail::class)
    ->variant('1 item', fn () => new OrderCreatedMail(Order::factory()->withOneProduct()->create()))
    ->variant('2 items', fn () => new OrderCreatedMail(Order::factory()->withTwoProducts()->create()));

Localization

When your application supports multiple languages you need to easily preview your mails in these languages. To enable this feature you have to add the following code to the mailbook.php config file.

'locales' => [
    'en' => 'English',
    'nl' => 'Dutch',
    'de' => 'German',
    'es' => 'Spanish'
],

This will display a dropdown in mailbook which you can use to switch to a different language.

Localization

Using the database

Most of the time your mailables will need database models. Sometimes you will even preform queries when rendering these mailables. Mailbook can automatically rollback database changes after rendering. You can enable it in the config with.

'database_rollback' => true,

You can now safely use factories and other queries when registering your mailables.

// All database changes are rolled back after rendering the mail.
Mailbook::add(function (): OrderShippedMail {
    $order = Order::factory()->create();
    $tracker = Tracker::factory()->create();
        
    return new OrderShippedMail($order, $tracker);
});

Database rollback is disabled by default.

Customization

You can publish the config file with:

php artisan vendor:publish --tag="mailbook-config"

This is the contents of the published config file:

return [
    'enabled' => env('APP_ENV') === 'local',
    'database_rollback' => false,
    'display_preview' => true,
    'route_prefix' => '/mailbook',
    'middlewares' => [Xammie\Mailbook\Http\Middlewares\RollbackDatabase::class],
    'show_credits' => true,
];

Optionally, you can publish the views using

php artisan vendor:publish --tag="mailbook-views"

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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