README

Filament Mail Previewer adds a Filament page that discovers your app mailables and notifications, asks for any required constructor inputs, and renders the email HTML side-by-side in desktop and mobile frames.

It uses charlielangridge/laravel-mail-previewer under the hood to discover classes and render previews.

Requirements

PHP ^8.3
Laravel app with Filament ^5.0
A Filament panel where you can register plugins

Installation

Install the package:

composer require charlielangridge/filament-mail-previewer

The package auto-discovers its service provider.

Register The Plugin In Your Filament Panel

Add the plugin to your panel provider (example: app/Providers/Filament/AdminPanelProvider.php):

use CharlieLangridge\FilamentMailPreviewer\FilamentMailPreviewerPlugin;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugins([
            FilamentMailPreviewerPlugin::make(),
        ]);
}

This registers:

a navigation page: Mail Previewer
a preview page used after selecting a mailable/notification

Filament Theme Setup (Important)

If you are using a custom Filament theme, include this package's Blade files in your Tailwind content sources so page styles/classes are picked up:

@source '../../../../vendor/charlielangridge/filament-mail-previewer/resources/**/*.blade.php';

Then rebuild your assets.

If you have not created a custom Filament theme yet, follow the Filament docs first:

https://filamentphp.com/docs/4.x/styling/overview#creating-a-custom-theme

Optional Configuration

Publish config if you want to override the facade class used to talk to the underlying Laravel mail previewer package:

php artisan vendor:publish --tag="filament-mail-previewer-config"

Published config:

return [
    'laravel_mail_previewer_facade' => \Charlielangridge\LaravelMailPreviewer\Facades\LaravelMailPreviewer::class,
    'authorization' => [
        'mode' => 'none',
        'gate_ability' => 'viewFilamentMailPreviewer',
        'policy' => [
            'model' => null,
            'ability' => 'viewAny',
        ],
        'callback' => null,
    ],
];

In most apps you do not need to change this.

Authorization (Optional)

By default, access is open to users who can access your panel (authorization.mode = none).

You can restrict the plugin using one of the following approaches.

Gate-based authorization

Set:

'authorization' => [
    'mode' => 'gate',
    'gate_ability' => 'viewFilamentMailPreviewer',
],

Then define the gate in your app (example in AuthServiceProvider):

Gate::define('viewFilamentMailPreviewer', fn (User $user): bool => $user->is_admin);

Policy-based authorization

Set:

'authorization' => [
    'mode' => 'policy',
    'policy' => [
        'model' => \App\Support\MailPreviewerAccess::class,
        'ability' => 'viewAny',
    ],
],

Then register a policy for that model and implement the ability:

class MailPreviewerAccessPolicy
{
    public function viewAny(User $user): bool
    {
        return $user->is_admin;
    }
}

Callback authorization

Use a config callback:

'authorization' => [
    'callback' => fn (?Authenticatable $user): bool => (bool) $user?->is_admin,
],

Or define it directly in your panel plugin registration:

FilamentMailPreviewerPlugin::make()
    ->authorizeUsing(fn (?Authenticatable $user): bool => (bool) $user?->is_admin);

When a callback is set, it takes precedence over mode.

Usage

Open your Filament panel.
Go to Mail Previewer in navigation.
Select a mailable or notification row and click Preview.
Fill required inputs in the modal.
Submit to open the rendered email preview page.

The preview page shows:

desktop frame
mobile frame
heading + resolved subject

How Inputs Are Handled

The plugin automatically builds a form from discovered constructor/input requirements:

model inputs become searchable selects
array inputs are entered as JSON
integer inputs are numeric fields
fields with date in the name become date pickers
other values are captured in textareas

For notifications, a notifiable model input is added automatically when possible (usually defaults to the authenticated user in the modal).

Troubleshooting

If the table is empty or you see the install notice:

ensure charlielangridge/laravel-mail-previewer is installed (it is a dependency of this plugin)
ensure your mailables/notifications are discoverable in your app
clear caches and reload:

php artisan optimize:clear

Testing

composer test

Changelog

See CHANGELOG.md.

Contributing

See .github/CONTRIBUTING.md.

Security

See .github/SECURITY.md.

Credits

Charlie Langridge

License

MIT. See LICENSE.md.

charlielangridge / filament-mail-previewer

Maintainers

Details