README

Discover mailables and notifications in a Laravel app, inspect required inputs, and render preview HTML safely.

This package is designed for internal preview tooling and admin UIs.

Features

Discover all app mailables and notifications.
Return structured metadata:
- short name
- full class
- subject (including dynamic placeholder parsing)
- input_requirements
Resolve required constructor input for a selected class.
For model-typed inputs, return up to 100 selectable DB options.
Render HTML previews for mailables and notifications.
Never sends email when rendering previews.

Requirements

PHP ^8.4
PHP ^8.3
Laravel ^11.0 || ^12.0

Installation

composer require charlielangridge/laravel-mail-previewer

The package auto-registers via Laravel package discovery.

Quick Start

use Charlielangridge\LaravelMailPreviewer\Facades\LaravelMailPreviewer;

$list = LaravelMailPreviewer::discover();

$requirements = LaravelMailPreviewer::inputRequirements(
    \App\Mail\FormCompletion::class
);

$issues = LaravelMailPreviewer::inputTypeHintingIssues();

$html = LaravelMailPreviewer::renderHtml(
    \App\Mail\FormCompletion::class,
    ['form' => 12]
);

API

`LaravelMailPreviewer::discover(): array`

Returns both mailables and notifications:

[
    'mailables' => [
        [
            'name' => 'FormCompletion',
            'class' => 'App\\Mail\\FormCompletion',
            'subject' => 'Hello **user->name**',
            'input_requirements' => [
                ['name' => 'form', 'type' => 'App\\Models\\Forms\\Form'],
            ],
        ],
    ],
    'notifications' => [
        // same shape
    ],
]

Subject extraction rules:

Uses class-level default subject when available.
Parses common subject definitions from class source:
- Envelope(subject: ...)
- ->subject(...)
Resolves local variables where possible:
- $subject = 'Test'; ->subject($subject) becomes Test
External/runtime references are converted to placeholders:
- 'Hello '.$this->user->name becomes Hello **user->name**

`LaravelMailPreviewer::inputRequirements(string $className): array`

Returns required constructor parameters for a mailable/notification.

If parameter type is an Eloquent model, includes options from DB (limit 100):

[
    [
        'name' => 'form',
        'type' => 'App\\Models\\Forms\\Form',
        'options' => [
            ['id' => 12, 'label' => 'Access Training Feedback'],
            // ...
        ],
    ],
    [
        'name' => 'token',
        'type' => 'string',
    ],
]

Notes:

Non-model parameters do not include options.
Unsupported classes return an empty array.

`LaravelMailPreviewer::inputTypeHintingIssues(): array`

Returns mailables/notifications where required constructor inputs are not properly type-hinted (missing type hint or resolved as mixed), so you can work through and fix them.

[
    'mailables' => [
        [
            'kind' => 'mailable',
            'name' => 'FormCompletion',
            'class' => 'App\\Mail\\FormCompletion',
            'untyped_input_requirements' => [
                [
                    'name' => 'form',
                    'current_type' => 'mixed',
                    'has_type_hint' => false,
                    'suggested_type' => 'App\\Models\\Forms\\Form',
                    'suggestion_reason' => 'parameter name matches an app model class name',
                ],
            ],
        ],
    ],
    'notifications' => [
        // same shape
    ],
]

Suggestion strategy:

Uses default parameter value type when present.
Attempts to map parameter names to app model classes.
Applies name heuristics (...Id => int, is... => bool, token/email/name/... => string).
Falls back to string.

`LaravelMailPreviewer::renderHtml(string $className, array $parameters = [], mixed $notifiable = null): ?string`

Renders HTML preview for a mailable or notification using Laravel's rendering pipeline.

$html = LaravelMailPreviewer::renderHtml(
    \App\Notifications\FormCompleted::class,
    ['form' => 12]
);

For model-typed constructor inputs, scalar values are treated as primary keys and resolved via findOrFail.

$notifiable is optional for notifications. If omitted, an internal anonymous notifiable is used.

Important:

This method does not call send/notify pathways.
It is for preview rendering only.

Tinker Examples

use Charlielangridge\LaravelMailPreviewer\Facades\LaravelMailPreviewer;

// 1) list discoverable items
LaravelMailPreviewer::discover();

// 2) get inputs for chosen class
LaravelMailPreviewer::inputRequirements(\App\Mail\FormCompletion::class);

// 3) audit classes with weak constructor type hints
LaravelMailPreviewer::inputTypeHintingIssues();

// 4) render html preview with selected values
$html = LaravelMailPreviewer::renderHtml(
    \App\Mail\FormCompletion::class,
    ['form' => 12]
);

$html;

Testing

composer test

Changelog

Please see CHANGELOG for details.

License

MIT. See LICENSE.md.

charlielangridge / laravel-mail-previewer

Maintainers

Details