Mailing Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ekyna/mailing-bundle
   php bin/console ekyna:mailing:install
   

   • Verify the bundle is registered in config/bundles.php (Symfony 4+).

2. Database Migration:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

   • Checks for ekyna_mailing tables (mailing, mailing_list, subscriber).

3. First Use Case:

   • Create a Mailing List:

     $list = $mailingManager->createList('Newsletter', 'newsletter@example.com');
     

   • Add Subscribers:

     $subscriber = $mailingManager->createSubscriber('john@example.com', 'John Doe');
     $list->addSubscriber($subscriber);
     

   • Send a Test Mailing:

     $mailing = $mailingManager->createMailing($list, 'Welcome', 'welcome_template');
     $mailingManager->send($mailing);
     

Key Files to Review

• config/packages/ekyna_mailing.yaml (default config).
• src/Ekyna/MailingBundle/Manager/MailingManager.php (core logic).
• templates/ekyna_mailing/ (default Twig templates).

Implementation Patterns

Workflows

1. Campaign Management:

   • Create/Update:

     $mailing = $mailingManager->createMailing($list, 'Subject', 'template_name', ['var' => 'value']);
     $mailingManager->update($mailing);
     

   • Schedule:

     $mailing->setSendAt(new \DateTime('+1 day'));
     $mailingManager->schedule($mailing);
     

2. Subscriber Segmentation:

   • Filter lists via Doctrine queries:

     $subscribers = $mailingManager->getSubscribersByList($listId, ['active' => true]);
     

3. Template Integration:

   • Extend Twig templates in templates/ekyna_mailing/mailing/ (override defaults).
   • Pass dynamic data:

     {# templates/ekyna_mailing/mailing/welcome.html.twig #}
     <p>Hello {{ subscriber.name }}!</p>
     

4. Bulk Actions:

   • Import subscribers from CSV:

     php bin/console ekyna:mailing:import-subscribers path/to/file.csv
     

Integration Tips

• Symfony Events: Listen to ekyna.mailing.mailing.sent to log analytics:

  // config/services.yaml
  Ekyna\MailingBundle\EventListener\MailingListener:
      tags:
          - { name: kernel.event_listener, event: ekyna.mailing.mailing.sent, method: onMailingSent }
  

• Swiftmailer Integration: Configure transport in config/packages/ekyna_mailing.yaml:

  ekyna_mailing:
      transport: 'gmail'
      username: 'your@gmail.com'
      password: 'app_%env(MAIL_PASSWORD)%'
  

• API Layer: Expose endpoints via API Platform or custom controllers:

  #[Route('/api/mailings', methods: ['POST'])]
  public function createMailing(MailingManager $manager, Request $request): Mailing
  {
      $data = json_decode($request->getContent(), true);
      return $manager->createMailing($data['list_id'], $data['subject'], $data['template']);
  }
  

Gotchas and Tips

Pitfalls

1. Deprecated Symfony Version:

   • Last release in 2015 targets Symfony 2.3–2.7. For Symfony 4/5/6:
     • Use a wrapper or fork (e.g., symfony/mailer for modern alternatives).
     • Patch Composer\InstalledVersions conflicts manually if forced to use.

2. Missing Features:

   • Attachments: Not implemented. Workaround:

     // Manually inject Swiftmailer attachments
     $mailing->setSwiftMessage($mailer->createMessage()
         ->attachFromPath('/path/to/file.pdf')
     );
     

   • Recipient Uniqueness: No built-in deduplication. Add a unique constraint in migrations:

     $this->addUniqueConstraint('subscriber', ['email']);
     

3. Template Overrides:

   • Overriding templates requires exact path matching (e.g., templates/ekyna_mailing/mailing/welcome.html.twig).
   • Clear cache after changes:

     php bin/console cache:clear
     

4. Queue System:

   • No native queue support. Use Symfony Messenger or a cron job to process mailings:

     * * * * * php bin/console ekyna:mailing:send-pending
     

Debugging

• Log Mailings: Enable debug mode in config/packages/dev/ekyna_mailing.yaml:

  ekyna_mailing:
      debug: true
  

  • Logs appear in var/log/dev.log.

• Common Errors:

  • "Mailing list not found": Verify $listId matches the database.
  • Twig errors: Check template paths and variables (e.g., {{ subscriber.name }} must exist).

Extension Points

1. Custom Subscriber Fields: Extend the Subscriber entity:

   // src/Entity/CustomSubscriber.php
   #[ORM\Entity]
   class CustomSubscriber extends Subscriber
   {
       #[ORM\Column]
       private string $customField;
   }
   

   Update migrations and forms accordingly.

2. Event Subscribers: Hook into lifecycle events (e.g., ekyna.mailing.subscriber.created):

   // src/EventListener/CustomListener.php
   class CustomListener implements EventSubscriberInterface
   {
       public static function getSubscribedEvents(): array
       {
           return [
               EkynaMailingEvents::SUBSCRIBER_CREATED => 'onSubscriberCreated',
           ];
       }
   
       public function onSubscriberCreated(SubscriberEvent $event): void
       {
           // Add logic (e.g., send welcome email)
       }
   }
   

3. Testing: Use the MailingManager in tests with a test database:

   public function testMailingCreation(): void
   {
       $list = $this->createMock(List::class);
       $manager = $this->getMailingManager();
       $mailing = $manager->createMailing($list, 'Test', 'test_template');
   
       $this->assertInstanceOf(Mailing::class, $mailing);
   }