Newsletter Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dywee/newsletter-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Dywee\NewsletterBundle\DyweeNewsletterBundle::class => ['all' => true],
   ];
   

2. Routing Add to config/routes.yaml:

   dywee_newsletter:
       resource: "@DyweeNewsletterBundle/Resources/config/routing.yml"
       prefix: /newsletter
   

3. First Use Case

   • Subscribers Management: Access /newsletter/subscriber to view/list subscribers.
   • Newsletter Creation: Use the admin panel (if DyweeCoreBundle is installed) to create campaigns via /newsletter/campaign.

Implementation Patterns

Core Workflows

1. Subscriber Management

   • CRUD via Controller: Extend Dywee\NewsletterBundle\Controller\SubscriberController for custom logic.
   • Form Integration: Use the SubscriberType form (if available) in your templates:

     {{ form_start(form) }}
         {{ form_widget(form.email) }}
         {{ form_widget(form.consent) }}
     {{ form_end(form) }}
     

   • Validation: Leverage Symfony’s validator for email format and consent checks.

2. Campaign Creation

   • Admin Panel: If DyweeCoreBundle is installed, use its CRUD generator for Campaign entity.
   • Manual Setup: Create a Campaign entity with fields like title, content, sent_at, and status.
   • Sending Logic: Override Dywee\NewsletterBundle\Service\CampaignSender to customize email dispatch:

     $sender = $this->container->get('dywee_newsletter.campaign_sender');
     $sender->send($campaign, $subscribers);
     

3. Templates and Emails

   • Twig Integration: Store email templates in templates/newsletter/emails/. Example:

     {# templates/newsletter/emails/welcome.html.twig #}
     <h1>Welcome, {{ subscriber.email }}!</h1>
     

   • Dynamic Content: Pass variables via CampaignSender:

     $sender->setTemplateVars(['subscriber' => $subscriber]);
     

4. Event-Driven Extensions

   • Subscriber Events: Listen for newsletter.subscriber.created or newsletter.campaign.sent:

     // src/EventListener/NewsletterListener.php
     public function onSubscriberCreated(SubscriberEvent $event) {
         // Custom logic (e.g., log, notify)
     }
     

   • Register Listener:

     # config/services.yaml
     Dywee\NewsletterBundle\EventListener\NewsletterListener:
         tags:
             - { name: kernel.event_listener, event: newsletter.subscriber.created, method: onSubscriberCreated }
     

Gotchas and Tips

Pitfalls

1. Missing DyweeCoreBundle

   • The bundle assumes DyweeCoreBundle for admin features. Without it:
     • Manual CRUD setup is required for Subscriber/Campaign entities.
     • Use Symfony’s make:crud or make:entity to scaffold controllers/forms.

2. Routing Conflicts

   • Prefix routes explicitly in config/routes.yaml to avoid clashes with other bundles:

     dywee_newsletter:
         prefix: /admin/newsletter  # Avoid root conflicts
     

3. Email Template Paths

   • Ensure templates are in templates/newsletter/emails/ or configure a custom path via dependency injection:

     $templating->setPath('custom/newsletter/templates');
     

4. Database Migrations

   • The bundle may not include migrations. Run:

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

Debugging Tips

1. Subscriber Not Saved?

   • Check if the Subscriber entity is properly mapped in SubscriberController:

     $subscriber = new Subscriber();
     $subscriber->setEmail($request->request->get('email'));
     $em->persist($subscriber);
     $em->flush(); // Ensure flush() is called
     

2. Emails Not Sending?

   • Verify the CampaignSender service is bound and the Swiftmailer bundle is configured:

     # config/packages/swiftmailer.yaml
     swiftmailer:
         transport: %env(MAILER_DSN)%
     

3. Admin Panel Missing

   • If DyweeCoreBundle is missing, manually create routes for Subscriber/Campaign:

     app_subscriber:
         resource: '@AppController/SubscriberController'
         type: annotation
     

Extension Points

1. Custom Subscriber Fields

   • Extend the Subscriber entity:

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

   • Update the form type (SubscriberType) to include new fields.

2. Bulk Actions

   • Add a BulkSubscriberController to handle exports/imports:

     public function export(SubscriberRepository $repo): Response {
         $subscribers = $repo->findAll();
         $csv = $this->csvExporter->export($subscribers);
         return new Response($csv, 200, ['Content-Type' => 'text/csv']);
     }
     

3. Webhook Integration

   • Trigger actions on external events (e.g., Mailchimp sync):

     public function onMailchimpSync(MailchimpEvent $event) {
         $this->entityManager->flush();
     }