Ccdn Message Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require codeconsortium/ccdn-message-bundle
   

   Register the bundle in app/AppKernel.php:

   new CodeConsortium\CCDNMessageBundle\CCDNMessageBundle(),
   

2. First Use Case Inject the message service into a controller or service:

   use CodeConsortium\CCDNMessageBundle\Service\MessageService;
   
   class MyController extends Controller
   {
       public function __construct(MessageService $messageService)
       {
           $this->messageService = $messageService;
       }
   
       public function sendMessageAction()
       {
           $this->messageService->send('recipient@example.com', 'Hello', 'Test message');
           return new Response('Message sent!');
       }
   }
   

3. Configuration Check app/config/config.yml for default settings (if any) or override in app/config/packages/ccdn_message.yml:

   ccdn_message:
       default_from: 'noreply@example.com'
       transport: 'smtp' # or 'mail' for PHP's mail()
   

Implementation Patterns

Core Workflows

1. Sending Messages Use the MessageService to send messages via different transports:

   // SMTP
   $this->messageService->send('user@example.com', 'Subject', 'Body');
   
   // With attachments
   $this->messageService->sendWithAttachment(
       'user@example.com',
       'Subject',
       'Body',
       ['/path/to/file.pdf']
   );
   

2. Templates & Dynamic Content Use Twig templates for dynamic messages:

   $this->messageService->sendTemplate(
       'user@example.com',
       'emails/welcome.twig',
       ['name' => 'John']
   );
   

3. Queueing Messages For async processing, integrate with Symfony’s Messenger component:

   # config/packages/messenger.yaml
   framework:
       messenger:
           transports:
               ccdn_message: '%env(MESSENGER_TRANSPORT_DSN)%'
           routing:
               'CodeConsortium\CCDNMessageBundle\Message\SendMessage': ccdn_message
   

4. Event Listeners Extend functionality via events (e.g., logging, analytics):

   // src/EventListener/MessageListener.php
   class MessageListener
   {
       public function onMessageSent(SendMessageEvent $event)
       {
           // Custom logic (e.g., analytics)
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\MessageListener:
           tags:
               - { name: kernel.event_listener, event: ccdn.message.sent, method: onMessageSent }
   

Integration Tips

1. Doctrine Integration Attach messages to entities via lifecycle callbacks:

   // src/Entity/User.php
   public function prePersist()
   {
       $this->messageService->sendWelcomeEmail($this->email);
   }
   

2. Validation Validate recipient emails before sending:

   use Symfony\Component\Validator\Constraints as Assert;
   
   $email = 'user@example.com';
   $validator = $this->validator;
   $errors = $validator->validate($email, [
       new Assert\Email(),
   ]);
   

3. Testing Mock the MessageService in PHPUnit:

   $mockService = $this->createMock(MessageService::class);
   $mockService->expects($this->once())
               ->method('send')
               ->with('user@example.com', 'Subject', 'Body');
   
   $controller = new MyController($mockService);
   

Gotchas and Tips

Pitfalls

1. Deprecation Warnings

   • The bundle targets Symfony 2.4 and PHP 5.3.2, which may cause compatibility issues with modern Laravel (Symfony 5+/PHP 7.4+). Test thoroughly or fork the bundle for updates.

2. Missing Documentation

   • The README is minimal. Key methods (e.g., sendWithAttachment) may lack examples. Check the Service/MessageService.php source for undocumented features.

3. Transport Configuration

   • SMTP settings must be explicitly configured in config.yml:

     ccdn_message:
         transport: smtp
         smtp_host: smtp.example.com
         smtp_port: 587
         smtp_user: user@example.com
         smtp_password: '%env(SMTP_PASSWORD)%'
     

4. Event System Quirks

   • Events like ccdn.message.sent may not be documented. Verify available events in Event/SendMessageEvent.php.

Debugging Tips

1. Enable Debugging Add logging to config.yml:

   ccdn_message:
       debug: true
   

   Check logs in var/log/dev.log for transport errors.

2. Common Errors

   • "Class not found": Ensure the bundle is registered in AppKernel.php.
   • SMTP failures: Verify credentials and firewall rules (e.g., smtp_port may be blocked).

3. Extension Points

   • Override the MessageService to add custom logic:

     // src/Service/CustomMessageService.php
     class CustomMessageService extends \CodeConsortium\CCDNMessageBundle\Service\MessageService
     {
         public function send($to, $subject, $body)
         {
             // Pre-process $body or $subject
             parent::send($to, $subject, $body);
         }
     }
     

     Register the override in services.yaml:

     services:
         CodeConsortium\CCDNMessageBundle\Service\MessageService: '@App\Service\CustomMessageService'
     

Pro Tips

1. Bulk Sending Use batch processing to avoid rate limits:

   $recipients = ['a@example.com', 'b@example.com'];
   foreach ($recipients as $email) {
       $this->messageService->send($email, 'Batch Subject', 'Batch Body');
   }
   

2. Local Testing Use a local mail catcher (e.g., MailHog) for development:

   ccdn_message:
       transport: mail
       mailer_path: '/usr/sbin/sendmail -t -i' # MailHog's sendmail path
   

3. Security

   • Sanitize dynamic content in templates to prevent email injection:

     {{ message.body|e('html') }}