Mailbook

To use Mailbook, install it via Composer as a development dependency and then run the installation command to set up the necessary routes and configuration.

1. Install the package:

   composer require --dev xammie/mailbook

2. Run the installer:

   php artisan mailbook:install

This creates routes/mailbook.php, where you will register your mailables.

To customize the Mailbook behavior or appearance, you can publish the configuration file or the Blade views using Artisan commands.

# Publish configuration
php artisan vendor:publish --tag="mailbook-config"

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

If your mailables require database models or perform queries during rendering, you can enable automatic rollbacks in config/mailbook.php. This ensures that any factories or queries used during registration do not persist changes to your database.

// In config/mailbook.php
'database_rollback' => true,

// Usage in routes/mailbook.php
Mailbook::add(function (): OrderShippedMail {
    $order = Order::factory()->create();
    $tracker = Tracker::factory()->create();
        
    return new OrderShippedMail($order, $tracker);
});

To preview mails in different languages, add a locales array to your config/mailbook.php file. This will add a language dropdown to the Mailbook UI.

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

You can enable a feature in the Mailbook UI that allows you to send the currently selected email to a specific address using your default mail driver. Configure this in config/mailbook.php.

// In config/mailbook.php
'send' => true,
'send_to' => 'test@mailbook.dev',

Use the mailbook:install Artisan command to set up Mailbook in your Laravel application. This command publishes the necessary configuration, routes, and view files required for the dashboard to function.

When executed, the command performs the following actions:

• Creates routes/mailbook.php to register the dashboard routes.
• Creates a Mail class (either app/Mail/MailbookMail.php or a variant depending on your Envelope support) used for the internal mailbook processes.
• Creates resources/views/mail/mailbook.blade.php for the dashboard UI.

If the target files already exist, the command will skip them to prevent overwriting your existing code.

php artisan mailbook:install

When registering notifications that require a notifiable user, use the ::to() method. You can pass a model instance or a plain email address.

$user = User::factory()->create();

// Send to a specific user model
Mailbook::to($user)->add(WelcomeNotification::class);

// Send to a specific email address
Mailbook::to('example@mailbook.dev')->add(WelcomeNotification::class);

Organize your mail previews using category() and group().

• category(): Creates a named section in the UI.
• group(): Groups multiple mailables together. If you call to() before group(), all mailables inside that group will use the same recipient.

// Grouping under a category
Mailbook::category('Invoices')->group(function () {
    Mailbook::add(InvoiceCreatedNotification::class);
    Mailbook::add(InvoicePaidNotification::class);
});

// Grouping with a shared recipient
Mailbook::to('example@mailbook.dev')->group(function () {
    Mailbook::add(WelcomeNotification::class);
    Mailbook::add(TrialEndedNotification::class);
});

// Chaining both category and recipient
Mailbook::to('example@mailbook.dev')
    ->category('Invoices')
    ->group(function () {
        // ...
    });

Use the variant() method to register multiple versions of the same mailable. This is useful for testing different data states (e.g., an order with one item vs. multiple items) for a single mail class.

Mailbook::add(OrderCreatedMail::class)
    ->variant('1 item', fn () => new OrderCreatedMail(Order::factory()->withOneProduct()->create()))
    ->variant('2 items', fn () => new OrderCreatedMail(Order::factory()->withTwoProducts()->create()));

The mailbook.send_to configuration key determines the email address that receives sent mails.

• It must be a string representing a valid email address.
• If an array is provided, Mailbook will use the first element ($to[0]).
• It cannot be an empty string or '0'.

If the configuration is invalid or missing, the system will fail to resolve a recipient via getSendToStrict(), but getSendTo() will gracefully return null.

// Example configuration in a Laravel config file
'mailbook' => [
    'send_to' => 'developer@example.com',
],