Hermes Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require 2lenet/hermes-bundle
   

   Ensure your project uses Symfony Mailer (HermesBundle depends on it).

2. Configure Symfony Mailer Add transport configuration in config/packages/mailer.yaml (Symfony) or bridge it to Laravel’s config/mail.php using spatie/laravel-symfony-mailer.

3. Enable the Bundle Register in config/bundles.php (Symfony) or create a Laravel service provider to bootstrap HermesBundle’s services.

4. First Use Case: Send a Templated Email Use the CruditBundle admin panel to create an email template (via the dashboard) or trigger it programmatically:

   // Example using Symfony's DI (adapt for Laravel)
   $mailer = $container->get('hermes.mailer');
   $mailer->send('template_name', ['user' => $user]);
   

5. Verify the Dashboard Access /admin/hermes (default route) to manage templates, recipients, and sent emails.

Implementation Patterns

Core Workflows

1. Template-Based Email Sending

• Pattern: Use Twig templates stored in templates/hermes/ (default location).

• Laravel Adaptation: Mount Twig templates in Laravel’s resources/views/vendor/hermes/ and configure the template path in HermesBundle’s config.

• Example:

  {# templates/hermes/welcome.twig #}
  <h1>Welcome, {{ user.name }}!</h1>
  <p>Your account is now active.</p>
  

• Trigger via Code:

  // Symfony (adapt for Laravel)
  $mailer = $this->get('hermes.mailer');
  $mailer->send('welcome', ['user' => $user], ['to' => $user->email]);
  

2. Admin Panel Management

• Pattern: Use CruditBundle’s CRUD interfaces to manage:
  • Email Templates: Define subject, body, and variables.
  • Recipients: Add BCC/CC lists or sublists (e.g., ['newsletter' => [$user1, $user2]]).
  • Attachments: Upload files via the dashboard.
• Laravel Note: If not using CruditBundle, replicate the admin panel with Laravel’s Nova, Filament, or custom controllers.

3. Recipient Management

• Pattern: Use MailRecipient entities to track sent emails, statuses (sent, failed, etc.), and unsubscribes.
• Example:

  $recipient = new MailRecipient();
  $recipient->setEmail($user->email);
  $recipient->setStatus(MailRecipient::STATUS_SENT);
  $entityManager->persist($recipient);
  

4. Sublists for CC/BCC

• Pattern: Group recipients into sublists (e.g., ['marketing' => [$email1, $email2]]) for segmented campaigns.
• Usage:

  $mailer->send('newsletter', [], [
      'cc' => ['marketing' => ['user1@example.com', 'user2@example.com']],
  ]);
  

5. Drafts and Scheduling

• Pattern: Save emails as drafts in the database and send them later.

• Example:

  $mail = new Mail();
  $mail->setTemplate('welcome');
  $mail->setVariables(['user' => $user]);
  $mail->setStatus(Mail::STATUS_DRAFT);
  $entityManager->persist($mail);
  

• Send Later:

  $mail->setStatus(Mail::STATUS_PENDING);
  $mail->setSentAt(new \DateTime('+1 day')); // Schedule for tomorrow
  

6. Attachments

• Pattern: Attach files to emails via the admin panel or code.
• Example:

  $mailer->send('invoice', ['user' => $user], [
      'attachments' => [
          new \Symfony\Component\Mime\Part\FilePart('path/to/invoice.pdf'),
      ],
  ]);
  

7. Translatable Emails

• Pattern: Use HermesBundle’s translatable feature to support multiple languages.
• Example:

  {# templates/hermes/welcome.twig #}
  <h1>{{ 'welcome.title'|trans }}</h1>
  

• Configure translations in config/packages/translation.yaml (Symfony) or Laravel’s config/app.php.

Integration Tips

Laravel-Specific Adaptations

1. Service Provider Bridge: Create a Laravel service provider to register HermesBundle’s services:

   // app/Providers/HermesServiceProvider.php
   namespace App\Providers;
   use Illuminate\Support\ServiceProvider;
   use Symfony\Component\DependencyInjection\ContainerInterface;
   
   class HermesServiceProvider extends ServiceProvider
   {
       public function register()
       {
           $this->app->singleton('hermes.mailer', function ($app) {
               return new \Hermes\Mailer\Mailer(
                   $app['symfony.mailer.transport'],
                   $app['hermes.template.manager']
               );
           });
       }
   }
   

2. Twig Integration: Use tightenco/jigsaw or spatie/laravel-twig-view to render Twig templates in Laravel:

   // config/services.php
   'twig' => [
       'paths' => [
           resource_path('views/vendor/hermes'),
       ],
   ],
   

3. Queue Support: Extend HermesBundle to use Laravel’s queues for async sending:

   // app/Console/Commands/SendHermesEmails.php
   namespace App\Console\Commands;
   use Illuminate\Bus\Queueable;
   use Illuminate\Queue\SerializesModels;
   use Illuminate\Queue\InteractsWithQueue;
   use Illuminate\Console\Command;
   use Hermes\Mailer\Mailer;
   
   class SendHermesEmails extends Command
   {
       use InteractsWithQueue, SerializesModels;
   
       protected $mailer;
   
       public function __construct(Mailer $mailer)
       {
           $this->mailer = $mailer;
       }
   
       public function handle()
       {
           $this->mailer->sendQueuedEmails();
       }
   }
   

4. Database Migrations: Adapt HermesBundle’s Doctrine entities to Laravel’s Eloquent:

   // app/Models/Mail.php
   namespace App\Models;
   use Illuminate\Database\Eloquent\Model;
   
   class Mail extends Model
   {
       const STATUS_DRAFT = 'draft';
       const STATUS_SENT = 'sent';
       // ...
   }
   

Symfony Mailer Bridge

Use spatie/laravel-symfony-mailer to integrate Symfony Mailer into Laravel:

composer require spatie/laravel-symfony-mailer

Configure in config/mail.php:

'driver' => env('MAIL_DRIVER', 'symfony'),
'symfony' => [
    'dsn' => env('MAIL_SYMFONY_DSN', 'null://localhost'),
],

Gotchas and Tips

Pitfalls

1. CruditBundle Dependency:

   • Issue: HermesBundle assumes CruditBundle for the admin panel. If not using Crudit, you’ll need to:
     • Fork the bundle and remove Crudit-specific code.
     • Rebuild the admin panel using Laravel’s admin packages (e.g., Nova, Filament).
   • Workaround: Override the bundle’s routes and controllers to point to Laravel’s routes.

2. Template Path Configuration:

   • Issue: HermesBundle defaults to templates/hermes/. In Laravel, this may not exist.
   • Fix: Configure the template path in HermesBundle’s config:

     # config/packages/hermes.yaml (Symfony)
     hermes:
         template_dir: '%kernel.project_dir%/resources/views/vendor/hermes'
     

     Or in Laravel’s config:

     // config/hermes.php
     return [
         'template_dir' => resource_path('views/vendor/hermes'),
     ];
     

3. Symfony Mailer vs. Laravel Mail:

   • Issue: HermesBundle uses Symfony Mailer’s API, which differs from Laravel’s Mail::send().
   • Fix: Create a facade or helper to abstract differences:

     // app/Facades/Hermes.php
     namespace App\Facades;
     use Illuminate\Support\Facades\Facade;
     
     class Hermes extends Facade
     {
         protected static function getFacadeAccessor()
         {
             return 'hermes.mailer';
         }
     }
     

4. Entity Manager Conflicts:

   • Issue: HermesBundle uses Doctrine’s EntityManager. In Laravel, this may conflict with Eloquent.
   • Fix: Use a custom entity manager or map Doctrine entities to Eloquent models.