Pd Mailer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require appaydin/pd-mailer
   

   Ensure Pd\MailerBundle\PdMailerBundle::class is registered in config/bundles.php.

2. Configuration: Create config/packages/mailer.yaml with basic settings:

   logger_active: true
   template_active: true
   list_count: 30
   active_language: ['en']
   

3. First Use Case: Send a templated email with logging:

   use Pd\MailerBundle\Email;
   
   $email = new Email();
   $email
       ->from('noreply@example.com')
       ->to('user@example.com')
       ->subject('Welcome')
       ->html(['name' => 'John']) // Template data
       ->getHeaders()->addTextHeader('template', 'welcome_email'); // Template ID
   
   $this->get('mailer')->send($email);
   

Key Files to Review

• config/packages/mailer.yaml (Configuration)
• Pd\MailerBundle\Email (Email class)
• pdAdmin panel (Template management)

Implementation Patterns

Core Workflow

1. Email Creation: Use Pd\MailerBundle\Email instead of Symfony's native Email for logging/templating support.

   $email = (new Email())
       ->from('sender@example.com')
       ->to('recipient@example.com')
       ->subject('Test')
       ->html(['key' => 'value'])
       ->getHeaders()->addTextHeader('template', 'template_id');
   

2. Sending Emails: Inject the mailer service (autowired in Symfony 5+):

   $this->mailer->send($email); // Logs and processes templates automatically
   

3. Template Management:

   • Define templates in pdAdmin under the Mail Templates section.
   • Use Twig templates (e.g., templates/emails/welcome_email.html.twig).
   • Reference templates via the template header.

Integration Tips

• Queue Emails: Use Symfony Messenger for async sending (requires additional setup):

  # config/packages/messenger.yaml
  framework:
      messenger:
          transports:
              async: '%env(MAILER_DSN)%'
  

• Language Support: Dynamically set active_language in config or per-email:

  $email->getHeaders()->addTextHeader('language', 'tr');
  

• Custom Templates: Extend the base template path:

  template_path: '%kernel.project_dir%/templates/custom_emails'
  

• Logging: Disable logging for non-critical emails:

  logger_active: false
  

Gotchas and Tips

Common Pitfalls

1. Template Not Found:

   • Ensure the template header matches the ID in pdAdmin.
   • Verify template_active: true in config.
   • Check template_path points to the correct directory.

2. Logging Overhead:

   • Disabling logger_active reduces database writes but loses audit trails.
   • For high-volume systems, consider batching logs or using a queue.

3. Deprecated Features:

   • Avoid using Swiftmailer directly; wrap with Pd\MailerBundle\Email.

4. Language Mismatches:

   • If emails render incorrectly, ensure the language header matches a value in active_language.

5. Symfony 5+ Compatibility:

   • The bundle is tested with Symfony Mailer, but some Swiftmailer-specific features may not work.

Debugging Tips

• Check Logs: pdAdmin’s Mail Logs section lists sent emails, errors, and template usage.

• Template Debugging: Use Twig’s {{ dump() }} in templates to inspect passed data:

  {{ dump(html_data) }}
  

• Header Inspection: Dump headers to verify template/language settings:

  var_dump($email->getHeaders()->all());
  

Extension Points

1. Custom Email Class: Extend Pd\MailerBundle\Email to add domain-specific methods:

   class CustomEmail extends Email {
       public function setUnsubscribeLink(string $link): self {
           $this->html['unsubscribe_link'] = $link;
           return $this;
       }
   }
   

2. Override Template Path: Dynamically set paths per email:

   $email->getHeaders()->addTextHeader('template_path', '/custom/path');
   

3. Event Listeners: Subscribe to mailer.message.sent events for post-send logic:

   // src/EventListener/MailListener.php
   public function onMailSent(MailSentEvent $event) {
       // Custom logic (e.g., analytics)
   }
   

4. Database Schema: Extend the mail_log table for custom fields (e.g., campaign tracking):

   // Migrations
   Schema::table('mail_log', function (Blueprint $table) {
       $table->string('campaign_id')->nullable();
   });
   

Configuration Quirks

• list_count: Limits entries per page in pdAdmin; set to 0 for no limit (not recommended for production).

• base_template: If defined, all templates inherit from this base (e.g., for shared headers/footers).

• Autowiring: Ensure autowire: true is set in config/services.yaml for dependency injection:

  services:
      _defaults:
          autowire: true