Esendex Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require boskee/esendex-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Boskee\EsendexBundle\BoskeeEsendexBundle::class => ['all' => true],
   ];
   

2. Configure Credentials: Add Esendex API credentials to config/packages/boskee_esendex.yaml:

   boskee_esendex:
       username: '%env(ESENDEX_USERNAME)%'
       password: '%env(ESENDEX_PASSWORD)%'
       account_reference: '%env(ESENDEX_ACCOUNT_REF)%'
   

3. First Use Case: Inject the EsendexClient service and send a test email:

   use Boskee\EsendexBundle\Service\EsendexClient;
   
   class EmailService {
       public function __construct(private EsendexClient $esendex) {}
   
       public function sendTestEmail(): void {
           $email = $this->esendex->email()
               ->from('sender@example.com')
               ->to('recipient@example.com')
               ->subject('Test Email')
               ->text('Hello from Esendex!');
           $this->esendex->send($email);
       }
   }
   

Implementation Patterns

Common Workflows

1. Email Sending: Use the fluent interface for emails:

   $email = $this->esendex->email()
       ->from('no-reply@example.com')
       ->to('user@example.com')
       ->subject('Welcome!')
       ->html('<h1>Welcome!</h1>')
       ->addAttachment('/path/to/file.pdf');
   $this->esendex->send($email);
   

2. SMS Integration: Send SMS messages via the same client:

   $sms = $this->esendex->sms()
       ->to('+441234567890')
       ->from('YourBrand')
       ->text('Your verification code is 123456.');
   $this->esendex->send($sms);
   

3. Batch Processing: Queue emails/SMS for later sending (if Esendex supports it):

   $this->esendex->queue()->send($email);
   

4. Template-Based Emails: Use Esendex templates (if configured):

   $email = $this->esendex->email()
       ->from('no-reply@example.com')
       ->to('user@example.com')
       ->templateId(12345)
       ->templateData(['name' => 'John']);
   

Integration Tips

• Symfony Messenger: Dispatch Esendex messages as async jobs:

  use Boskee\EsendexBundle\Message\SendEmailMessage;
  
  $bus->dispatch(new SendEmailMessage($email));
  

• Twig Integration: Pass email data to Twig templates:

  {# templates/emails/welcome.html.twig #}
  <h1>Welcome, {{ user.name }}!</h1>
  

  $email->html($this->twig->render('emails/welcome.html.twig', ['user' => $user]));
  

• Validation: Validate recipient lists before sending:

  $this->esendex->validateRecipients($email);
  

Gotchas and Tips

Pitfalls

1. Deprecated Symfony2 Syntax: The bundle assumes Symfony2-style configuration (config.yml). Update to config/packages/ format:

   # config/packages/boskee_esendex.yaml
   boskee_esendex:
       username: '%env(ESENDEX_USERNAME)%'
       password: '%env(ESENDEX_PASSWORD)%'
   

2. Missing Error Handling: Wrap Esendex calls in try-catch blocks:

   try {
       $this->esendex->send($email);
   } catch (\Boskee\EsendexBundle\Exception\EsendexException $e) {
       $this->logger->error('Esendex error: ' . $e->getMessage());
       // Retry or notify admin
   }
   

3. Rate Limits: Esendex may throttle requests. Implement exponential backoff:

   use Symfony\Component\Stopwatch\Stopwatch;
   
   $stopwatch = new Stopwatch();
   $event = $stopwatch->start('esendex_send');
   $this->esendex->send($email);
   $event->stop();
   if ($event->getDuration() > 1000) { // >1s
       sleep(2); // Backoff
   }
   

4. Environment Variables: Ensure .env contains:

   ESENDEX_USERNAME=your_username
   ESENDEX_PASSWORD=your_password
   ESENDEX_ACCOUNT_REF=your_ref
   

Debugging

• Enable API Logging: Add to config/packages/boskee_esendex.yaml:

  boskee_esendex:
      debug: true
  

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

• Test Mode: Use Esendex’s sandbox environment:

  boskee_esendex:
      sandbox: true
  

Extension Points

1. Custom Services: Extend the EsendexClient to add domain logic:

   class CustomEsendexClient extends EsendexClient {
       public function sendTransactionalEmail(User $user, string $template) {
           $email = $this->email()
               ->from('no-reply@example.com')
               ->to($user->email)
               ->templateId($this->getTemplateId($template))
               ->templateData(['user' => $user]);
           $this->send($email);
       }
   }
   

2. Event Listeners: Listen for Esendex events (e.g., EsendexMessageSentEvent):

   use Boskee\EsendexBundle\Event\EsendexMessageSentEvent;
   use Symfony\Component\EventDispatcher\GenericEventDispatcher;
   
   $dispatcher->addListener(EsendexMessageSentEvent::class, function (EsendexMessageSentEvent $event) {
       $this->analytics->track('email_sent', ['recipient' => $event->getRecipient()]);
   });
   

3. Override SDK: Replace the underlying Esendex SDK for custom logic:

   # config/packages/boskee_esendex.yaml
   boskee_esendex:
       client_class: App\Service\CustomEsendexClient