Newsletter Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bytes-commerce/newsletter-bundle
   

   Add to config/bundles.php:

   BytesCommerce\NewsletterBundle\BytesCommerceNewsletterBundle::class => ['all' => true],
   

2. Database Migration Run the bundle’s migration (check src/Resources/migrations/ for schema):

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

3. First Use Case: Subscribe a User Inject the NewsletterManager service and call:

   $newsletterManager = $this->container->get('bytes_commerce_newsletter.manager');
   $newsletterManager->subscribe($user, 'general'); // 'general' is the newsletter type
   

4. Configuration Override defaults in config/packages/bytes_commerce_newsletter.yaml:

   bytes_commerce_newsletter:
       newsletter_types:
           general: {name: 'General Newsletter', description: 'Weekly updates'}
       email:
           from: 'noreply@example.com'
           subject: 'Welcome to our Newsletter!'
   

Implementation Patterns

Core Workflows

1. Subscription Management

   • Subscribe a User:

     $newsletterManager->subscribe($user, 'general');
     

   • Unsubscribe a User:

     $newsletterManager->unsubscribe($user, 'general');
     

   • Toggle Subscription:

     $newsletterManager->toggleSubscription($user, 'general');
     

2. Bulk Operations Use the NewsletterRepository to fetch subscribers:

   $subscribers = $newsletterRepository->findByNewsletterType('general');
   

3. Event-Driven Integration Listen for NewsletterSubscribedEvent or NewsletterUnsubscribedEvent:

   // src/EventListener/NewsletterListener.php
   public function onNewsletterSubscribed(NewsletterSubscribedEvent $event) {
       // Send welcome email, log analytics, etc.
   }
   

4. Custom Newsletter Types Extend the NewsletterType entity or use the NewsletterTypeManager:

   $newsletterTypeManager->createNewsletterType('promotions', [
       'name' => 'Promotions',
       'description' => 'Exclusive offers',
   ]);
   

Integration Tips

• Symfony Forms: Use the BytesCommerceNewsletterType form field for subscription forms.
• Twig Templates: Access subscriber status in templates:

  {% if app.user is subscribed to 'general' %}
      <p>You're subscribed!</p>
  {% else %}
      <a href="{{ path('subscribe') }}">Subscribe</a>
  {% endif %}
  

• API Endpoints: Expose subscription logic via API Platform or custom controllers:

  #[Route('/subscribe/{type}', name: 'api_subscribe', methods: ['POST'])]
  public function subscribe(NewsletterManager $manager, string $type): JsonResponse {
      $manager->subscribe($this->getUser(), $type);
      return new JsonResponse(['status' => 'subscribed']);
  }
  

Gotchas and Tips

Pitfalls

1. Missing Migrations

   • Issue: Forgetting to run migrations after installation causes NewsletterSubscriber table errors.
   • Fix: Always run doctrine:migrations:migrate post-install.

2. Newsletter Type Not Found

   • Issue: Using a non-existent newsletter type (e.g., 'promo' instead of 'promotions') throws NewsletterTypeNotFoundException.
   • Fix: Validate types before use or fetch available types:

     $types = $newsletterTypeManager->getAllNewsletterTypes();
     

3. Duplicate Subscriptions

   • Issue: The bundle doesn’t enforce uniqueness by default. Subscribers can appear multiple times for the same type.
   • Fix: Add a unique constraint in the migration or use a UNIQUE index:

     $table->unique(['user_id', 'newsletter_type']);
     

4. Email Configuration Overrides

   • Issue: Custom email templates or senders may conflict with bundle defaults.
   • Fix: Override the bytes_commerce_newsletter.email config or extend the NewsletterEmailService.

Debugging

• Enable Logging Add to config/packages/monolog.yaml:

  handlers:
      bytes_newsletter:
          type: stream
          path: "%kernel.logs_dir%/newsletter.log"
          level: debug
  

  Logs subscription/unsubscription events and errors.

• Check Event Dispatching Ensure events are dispatched by verifying the EventDispatcher is bound to the bundle’s services.

Extension Points

1. Custom Subscriber Entity Extend the NewsletterSubscriber entity to add fields (e.g., consent_date):

   // src/Entity/CustomNewsletterSubscriber.php
   class CustomNewsletterSubscriber extends NewsletterSubscriber {
       #[ORM\Column(type: 'datetime')]
       private $consentDate;
   }
   

   Update the bundle’s Resources/config/doctrine/NewsletterSubscriber.orm.xml to use your entity.

2. Custom Email Service Implement BytesCommerce\NewsletterBundle\Service\NewsletterEmailServiceInterface:

   class CustomNewsletterEmailService implements NewsletterEmailServiceInterface {
       public function sendWelcomeEmail(User $user, string $newsletterType): void {
           // Custom logic (e.g., send via Mailgun)
       }
   }
   

   Register as a service with the bytes_commerce_newsletter.email_service tag.

3. GDPR Compliance Extensions Add a consent_required flag to newsletter types and validate in the subscribe method:

   if ($newsletterType->isConsentRequired() && !$user->hasConsented()) {
       throw new \RuntimeException('Consent required for this newsletter.');
   }
   

Config Quirks

• Newsletter Type Slugs Slugs (e.g., 'general') are case-sensitive. Use the exact slug defined in newsletter_types.
• Default Newsletter Type The bundle assumes 'general' exists by default. Add it to your config if missing:

  bytes_commerce_newsletter:
      newsletter_types:
          general: ~