Filament Email Templates Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require notebrainslab/filament-email-templates
   

   Publish the migration and config:

   php artisan vendor:publish --provider="Notebrainslab\FilamentEmailTemplates\FilamentEmailTemplatesServiceProvider" --tag="filament-email-templates:migrations"
   php artisan vendor:publish --provider="Notebrainslab\FilamentEmailTemplates\FilamentEmailTemplatesServiceProvider" --tag="filament-email-templates:config"
   php artisan migrate
   

2. Register the Plugin Add to app/Providers/Filament/AdminPanelProvider.php:

   ->plugin(Notebrainslab\FilamentEmailTemplates\FilamentEmailTemplatesPlugin::make())
   

3. First Use Case Create a template via the Filament UI:

   • Navigate to Email Templates → Create Template
   • Design your email using the Unlayer drag-and-drop editor
   • Define a key (e.g., auth.welcome) and merge tags (e.g., {{user.name}})

Implementation Patterns

Core Workflow

1. Design Phase

   • Use the Unlayer editor to build responsive emails visually.
   • Define merge tags (e.g., {{order.total}}) for dynamic content.
   • Save with a unique key (e.g., invoices.payment_reminder).

2. Integration with Mailables Use the HasEmailTemplate trait in your Mailable:

   use Notebrainslab\FilamentEmailTemplates\Traits\HasEmailTemplate;
   
   class WelcomeUser extends Mailable
   {
       use HasEmailTemplate;
   
       public function build()
       {
           return $this
               ->subject('Welcome, {{user.name}}!')
               ->template('auth.welcome')
               ->with([
                   'user' => $this->user,
               ]);
       }
   }
   

3. Dynamic Data Injection Pass data to templates via the with() method:

   ->with([
       'order' => $order,
       'user' => $user,
   ]);
   

   Access in merge tags: {{order.total}} or {{user.name}}.

4. Conditional Logic Use template conditions (e.g., {{#if user.is_premium}}Premium Content{{/if}}) for dynamic blocks.

Advanced Patterns

• Template Versioning Use the version field to track updates without breaking existing mailables.

• Reusable Components Create template snippets (e.g., headers/footers) and reuse them across templates.

• API-Driven Templates Fetch templates programmatically:

  $template = \Notebrainslab\FilamentEmailTemplates\Models\EmailTemplate::where('key', 'auth.welcome')->first();
  $html = $template->render(['user' => $user]);
  

• Testing Mock templates in tests:

  $this->app->bind(\Notebrainslab\FilamentEmailTemplates\Models\EmailTemplate::class, function () {
      return new class extends \Notebrainslab\FilamentEmailTemplates\Models\EmailTemplate {
          public function render(array $data) { return 'Mock HTML'; }
      };
  });
  

Gotchas and Tips

Pitfalls

1. Merge Tag Syntax

   • Issue: Merge tags like {{user.name}} fail if the dot (.) is not escaped or the variable is nested.
   • Fix: Use {{user.name}} (correct) instead of {{user.name}} (if nested objects fail, flatten data in with()).

2. Unlayer Editor Quirks

   • Issue: Custom CSS/JS may not persist after saving.
   • Fix: Use the Advanced Settings tab to inject global styles/scripts.

3. Caching Headaches

   • Issue: Template changes may not reflect immediately due to Laravel caching.
   • Fix: Clear config cache:

     php artisan config:clear
     

4. Dark Mode Conflicts

   • Issue: Custom colors may not adapt to dark mode.
   • Fix: Use Unlayer’s theme variables (e.g., --unlayer-primary) for dynamic theming.

Debugging Tips

1. Log Rendered Output Override the render() method in a custom template model:

   Log::debug('Template rendered:', ['html' => $html, 'data' => $data]);
   

2. Inspect Merge Tags Use {{debug}} in templates to dump variables:

   {{debug user}}
   

3. Check Template Existence Verify the key exists in the database:

   php artisan tinker
   >>> \Notebrainslab\FilamentEmailTemplates\Models\EmailTemplate::where('key', 'auth.welcome')->exists();
   

Extension Points

1. Custom Merge Tag Handlers Extend functionality by adding a service provider:

   EmailTemplate::extend(function ($template, $data) {
       $data['custom_var'] = 'value';
       return $data;
   });
   

2. Template Events Listen for template actions:

   Event::listen(\Notebrainslab\FilamentEmailTemplates\Events\TemplateSaved::class, function ($template) {
       // Post-save logic
   });
   

3. Override Unlayer Editor Customize the editor via config:

   'unlayer' => [
       'options' => [
           'toolbar' => ['bold', 'italic', 'custom-button'],
       ],
   ],
   

4. Localization Translate merge tags dynamically:

   ->with([
       'greeting' => __("Welcome, :name!", ['name' => $user->name]),
   ]);
   

   Use in template: {{greeting}}.