Laravel Mailcoach Unlayer Laravel Package

Getting Started

Minimal Setup Steps

1. Installation Require the package via Composer in a Laravel project with Mailcoach installed:

   composer require spatie/laravel-mailcoach-unlayer
   

   Publish the package configuration (if needed):

   php artisan vendor:publish --provider="Spatie\MailcoachUnlayer\MailcoachUnlayerServiceProvider"
   

2. Configuration Ensure your config/mailcoach.php includes the Unlayer editor as an option:

   'editor' => [
       'default' => 'unlayer',
       'options' => [
           'unlayer' => [
               'enabled' => true,
               'api_key' => env('UNLAYER_API_KEY'), // Required
           ],
       ],
   ],
   

   Add your Unlayer API key to .env:

   UNLAYER_API_KEY=your_api_key_here
   

3. First Use Case

   • Navigate to Mailcoach’s Templates section in the admin panel.
   • Create or edit a template and select Unlayer as the editor.
   • Start designing emails with Unlayer’s drag-and-drop interface.

Implementation Patterns

Workflows

1. Template Creation

   • Use Unlayer for visual email design without manual HTML/CSS.
   • Save templates directly in Mailcoach’s database, linked to campaigns.
   • Example:

     $template = Mailcoach::templates()->create([
         'name' => 'Welcome Email',
         'editor' => 'unlayer',
         'content' => $unlayerJsonContent, // Generated by Unlayer
     ]);
     

2. Campaign Integration

   • Attach Unlayer-designed templates to campaigns:

     $campaign = Mailcoach::campaigns()->create([
         'name' => 'Promo Campaign',
         'template_id' => $template->id,
     ]);
     

3. Dynamic Content

   • Use Mailcoach’s personalization features (e.g., {{ user.name }}) alongside Unlayer’s dynamic blocks.
   • Unlayer’s JSON output can include placeholders that Mailcoach replaces at send time.

Integration Tips

• API-Driven Workflows Fetch Unlayer’s pre-designed templates via its API and import them into Mailcoach:

  $unlayerTemplate = Unlayer::getTemplate($templateId);
  $mailcoachTemplate = Mailcoach::templates()->create([
      'content' => $unlayerTemplate['json'],
  ]);
  

• Fallback Editors Configure a fallback editor (e.g., mailcoach or tinymce) in config/mailcoach.php if Unlayer fails:

  'editor' => [
      'default' => 'unlayer',
      'fallback' => 'mailcoach',
  ],
  

• Custom Styling Extend Unlayer’s default styles by overriding its CSS in Mailcoach’s assets or via the unlayer config:

  'unlayer' => [
      'custom_css' => file_get_contents(public_path('css/unlayer-overrides.css')),
  ],
  

Gotchas and Tips

Pitfalls

1. API Key Management

   • Issue: Forgetting to set UNLAYER_API_KEY in .env causes silent failures.
   • Fix: Validate the key during template creation:

     if (empty(config('mailcoach.editor.options.unlayer.api_key'))) {
         throw new \RuntimeException('Unlayer API key not configured.');
     }
     

2. Content Size Limits

   • Issue: Unlayer’s JSON output may exceed Mailcoach’s database column limits (e.g., content field).
   • Fix: Compress large templates or use Mailcoach’s content field for metadata and store the JSON in a separate table.

3. Caching Quirks

   • Issue: Unlayer’s editor assets may not update after package updates.
   • Fix: Clear Laravel’s cache and view cache:

     php artisan cache:clear
     php artisan view:clear
     

4. Dynamic Content Conflicts

   • Issue: Unlayer’s dynamic blocks (e.g., {{ block }}) may conflict with Mailcoach’s personalization syntax.
   • Fix: Use unique delimiters (e.g., {{{ user.name }}}) or escape placeholders in Unlayer’s JSON.

Debugging

• Editor Not Loading Check browser console for 403/404 errors on Unlayer’s API endpoints. Verify:

  • API key is correct.
  • CORS settings allow your domain (if using Unlayer’s cloud service).
  • No JavaScript errors in Mailcoach’s admin panel.

• Template Rendering Issues Use Mailcoach’s preview feature to test Unlayer templates:

  $preview = Mailcoach::templates()->find($templateId)->preview(['user' => $user]);
  

  Inspect the rendered HTML for missing styles or broken placeholders.

Extension Points

1. Custom Unlayer Config Override Unlayer’s default settings (e.g., toolbar options) via the config:

   'unlayer' => [
       'toolbar' => [
           'options' => ['bold', 'italic', 'undo', 'redo'],
       ],
   ],
   

2. Webhook Integration Trigger actions in Laravel when Unlayer templates are updated via its API:

   // In a route or controller
   $hook = app(\Spatie\MailcoachUnlayer\Listeners\UnlayerWebhookListener::class);
   $hook->handle($request);
   

3. Template Validation Add custom validation to Unlayer-generated content before saving:

   use Spatie\MailcoachUnlayer\Validators\UnlayerContentValidator;
   
   $validator = new UnlayerContentValidator();
   if (!$validator->validate($template->content)) {
       throw new \InvalidArgumentException('Invalid Unlayer template structure.');
   }
   

4. Local Development For offline testing, use Unlayer’s local development mode and proxy its API through Laravel’s routes/api.php:

   Route::get('/unlayer-api/{path}', function ($path) {
       return response()->file(public_path("unlayer-local/{$path}"));
   });