Alert Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require atc/alert-bundle "~1"
   

   Ensure your project uses Symfony 2.4 (compatibility constraint).

2. Enable Bundle: Register in app/AppKernel.php:

   new Atc\Bundle\AlertBundle\AtcAlertBundle(),
   

3. Configure: Add to app/config/config.yml:

   atc_alert:
       mail_from_default: "alerts@yourdomain.com"
       sms_url: "https://rest.nexmo.com/sms/json"  # Replace with your SMS provider
       sms_key: "%env(SMS_API_KEY)%"               # Use env vars for secrets
       sms_secret: "%env(SMS_API_SECRET)%"
       mailjet_public: null                        # Optional (use ShiftMailer fallback)
   

4. First Use Case: Send an email alert in a controller:

   $this->get('atc_alert.alert.manager')->createMailAlert(
       'user@example.com',
       $this->renderView('emails/alert.twig', ['data' => $data]),
       'Alert Subject'
   );
   

Implementation Patterns

Core Workflows

1. Service Injection: Inject the manager via dependency injection (recommended for controllers/services):

   use Atc\Bundle\AlertBundle\Manager\AlertManager;
   
   class UserController extends Controller {
       public function __construct(AlertManager $alertManager) {
           $this->alertManager = $alertManager;
       }
   }
   

2. Templating: Use Twig for email/SMS body templates (e.g., emails/alert.twig):

   {# emails/alert.twig #}
   <p>Hello {{ user.name }}, your alert: {{ alert.message }}</p>
   

3. Batch Alerts: Queue alerts for delayed sending (e.g., via cron):

   $this->alertManager->createMailAlert($email, $body, $subject, null, new \DateTime('+1 hour'));
   

4. Multi-Channel Alerts: Send SMS + email simultaneously:

   $this->alertManager->createSmsMailAlert(
       '0612345678',  // SMS recipient
       'user@example.com',  // Email recipient
       'Your code: 1234',
       'Security Alert'
   );
   

Integration Tips

• Environment Variables: Store sms_key/sms_secret in .env:

  SMS_API_KEY=your_key_here
  SMS_API_SECRET=your_secret_here
  

• Custom Providers: Extend Atc\Bundle\AlertBundle\Provider\SmsProviderInterface for non-Nexmo APIs (e.g., Twilio).
• Logging: Wrap calls in try-catch to log failures:

  try {
      $this->alertManager->createSmsAlert($phone, $message);
  } catch (\Exception $e) {
      $this->get('logger')->error('SMS failed', ['exception' => $e]);
  }
  

Gotchas and Tips

Pitfalls

1. Symfony Version Lock: The bundle only supports Symfony 2.4. Upgrading to Symfony 3+ requires forking and modernizing dependencies (e.g., Swiftmailer 6+).

2. SMS Provider Assumptions:

   • Hardcoded to Nexmo’s API. Custom providers require interface implementation.
   • No retry logic for failed SMS deliveries.

3. Template Rendering:

   • renderView() uses Symfony’s Twig service. Ensure Twig is configured if using custom paths.
   • No built-in template validation: Invalid paths throw runtime errors.

4. Configuration Overrides:

   • Default from addresses (mail_from_default, sms_from_default) are global. Override per-call if needed:

     $this->alertManager->createMailAlert($email, $body, $subject, 'custom@from.com');
     

Debugging Tips

• Enable Debug Mode: Symfony’s debug toolbar shows Swiftmailer/SMS logs if enabled.
• Check Provider Responses: Nexmo returns JSON; log the raw response for errors:

  $smsProvider = $this->get('atc_alert.sms.provider.nexmo');
  $response = $smsProvider->send($to, $body);
  $this->get('logger')->debug('Nexmo Response', ['response' => $response]);
  

• Test SMS Locally: Use a mock provider (implement SmsProviderInterface) to avoid API costs during development.

Extension Points

1. Add New Channels: Implement Atc\Bundle\AlertBundle\Provider\AlertProviderInterface for Slack/Teams alerts.
2. Queue Support: Integrate with Symfony Messenger or Doctrine Messages for async processing:

   $message = new AlertMessage($email, $body, $subject);
   $this->get('messenger')->dispatch($message);
   

3. Custom Alert Types: Extend the manager to support push notifications or webhooks:

   class ExtendedAlertManager extends AlertManager {
       public function createPushAlert($token, $title, $body) {
           // ...
       }
   }