Download the PHP package blackpig-creatif/epitre without Composer

Epitre

An editable email copy layer for Laravel Mailables, managed through a Filament v5 panel.

Epitre sits between your Mailable classes and their output. Each template has a Blade view as its default. Editors can override the subject and body per locale through the Filament panel without touching code. If no DB record exists, the Blade view is used as-is.

Requirements

• PHP 8.2+
• Laravel 11+
• Filament 5.0+
• spatie/laravel-translatable
• lara-zeus/spatie-translatable (Filament translatable plugin)

Installation

Run the migration:

Register the plugin in your PanelProvider:

Epitre will register SpatieTranslatablePlugin automatically if it is not already present. It reads your locale list from config('app.locales') if that key exists (expected format: ['en' => 'English', 'fr' => 'Francais']), falling back to app()->getLocale().

Quick Start

1. Generate a template class

This creates:

• app/BlackpigCreatif/Epitre/Templates/ContactConfirmationTemplate.php
• resources/views/mail/epitre/contact-confirmation.blade.php

2. Define tokens and resolution logic

Open the generated class and fill in the tokens your template uses:

3. Register the template in your service provider

4. Wire up your Mailable

Add the HasEpitreTemplate trait and implement the two required members:

The trait provides envelope() and content(). Do not implement those methods yourself.

Converting an Existing Mailable

If you have a Mailable already in production, the migration is straightforward.

Before:

Steps:

1. Generate the template class, pointing at your existing Blade view:

Open the generated class and set $view to your existing view, define any tokens, and implement resolve():

2. Register the template in your service provider:

3. Update the Mailable. Remove envelope() and content(), add the trait and the two required members:

Your existing Blade view continues to work unchanged since no DB record exists yet. Editors can customise the copy through the panel at any point, and the Blade view remains the fallback if they haven't.

How Resolution Works

When a Mailable using HasEpitreTemplate is sent, Epitre resolves the content in this order:

Subject: If a DB record exists with a subject for the current locale, it is used with tokens replaced. Otherwise, the template $label is used as the subject.

Body: If a DB record exists with a body for the current locale, it is rendered as an HTML string with tokens replaced. If a $layout is set on the template, the resolved HTML is passed to the layout view as $body instead. Otherwise the body is returned as a raw htmlString with no wrapping. If no DB record exists, the Blade view is rendered via Content(view: ...) with epitreData() passed as view data.

This means your Blade view is always the working default. Editors only override when they want to.

Template Classes

All template classes extend EpitreTemplate:

The $tokens array is informational only. It is displayed in the Filament editor sidebar so editors know what substitutions are available. The resolve() method maps token strings to their runtime values given the data array from epitreData().

Layouts

When editors save content through the Filament panel, Epitre renders it as HTML with tokens replaced. Without a layout, this is returned as a raw htmlString — no wrapping, no styling.

If your emails use a mail layout (Laravel's <x-mail::message>, a custom component, or any Blade view), set $layout on the template to a Blade view path. Epitre will render that view with two variables available: $body (the resolved HTML) and everything from epitreData().

Create the layout view:

Epitre renders layout views through Laravel's mail rendering pipeline, which is the only way <x-mail::message> and related components are available. This pipeline also inlines CSS from your mail theme into the output, which is necessary for email client compatibility. Your stored HTML body is output raw via {!! $body !!} — nothing is converted to or processed as Markdown. The pipeline name is a Laravel implementation detail you do not need to think about.

The $layout only applies when a DB record exists. The $view default continues to use its own layout as normal.

Filament Resource

Registering EpitrePlugin adds an Email Templates resource to your panel.

List view shows all registered templates with their current status:

Edit view lets editors set the subject and body per locale. The sidebar shows the available tokens for that template. Saving creates or updates the DB record. Leaving a field empty falls back to the Blade view default.

Reset to default (visible only when a DB record exists) deletes the record and restores the Blade view default. Requires confirmation.

Translation

Subject and body are stored as translatable JSON columns via spatie/laravel-translatable. The Filament editor uses the locale switcher from lara-zeus/spatie-translatable to manage per-locale content.

Configure your available locales in config/app.php:

Epitre reads this at boot time to configure the translatable plugin. If you are already registering SpatieTranslatablePlugin yourself with locales set, Epitre will not overwrite them.

Testing

Changelog

Please see CHANGELOG for recent changes.

Credits

• Blackpig Creatif
• All Contributors

License

MIT. See LICENSE for details.