Alert Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Run composer require deslynx/alert-bundle in your Laravel project. No additional configuration is required for basic usage (Symfony Flex auto-registers the bundle).

2. First Use Case: Logging Alerts Inject the AlertService into a controller or service:

   use DesLynx\AlertBundle\Service\AlertService;
   
   public function __construct(private AlertService $alertService) {}
   
   public function handleCriticalError()
   {
       $this->alertService->alert('Database connection failed', 'error');
   }
   

   This sends an email alert via the configured Monolog handler.

3. Where to Look First

   • Configuration: config/alert.php (auto-generated by Flex).
   • Service: AlertService (main entry point).
   • Monolog Handler: DesLynx\AlertBundle\Handler\AlertHandler (for custom logging).

Implementation Patterns

Core Workflows

1. Sending Alerts Programmatically Use AlertService to trigger alerts with context:

   $this->alertService->alert(
       'Payment gateway timeout',
       'warning',
       ['user_id' => 123, 'amount' => 99.99]
   );
   

   • Levels: error, warning, info (maps to Monolog levels).
   • Context: Passed as an associative array for email templating.

2. Integrating with Monolog The bundle adds an AlertHandler to your Monolog stack. Customize it in config/logging.php:

   'channels' => [
       'alert' => [
           'type' => 'custom',
           'path' => DesLynx\AlertBundle\Handler\AlertHandler::class,
       ],
   ],
   

   Log alerts directly via the Log facade:

   \Log::alert('Critical failure', ['context' => 'data']);
   

3. Email Templates Override default templates in resources/views/vendor/alert/:

   • alert_email.html.twig (Symfony Twig) or alert_email.blade.php (Laravel Blade).
   • Access context via $alert (e.g., {{ $alert.level }}, {{ $alert.message }}).

4. Queueing Alerts Disable immediate email sending by setting 'sync' => false in config/alert.php and queue the SendAlertEmail job:

   $this->alertService->queueAlert('Scheduled maintenance', 'info');
   

Advanced Patterns

• Dynamic Recipients: Extend AlertService to fetch recipients from a database:

  $recipients = User::where('role', 'admin')->pluck('email');
  $this->alertService->setRecipients($recipients);
  

• Slack/Webhook Alerts: Implement a custom AlertTransport (see Extension Points).

Gotchas and Tips

Pitfalls

1. Configuration Overrides

   • If emails aren’t sending, verify config/alert.php:

     'from' => 'alerts@example.com', // Required
     'to' => ['admin@example.com'],  // Default recipients
     'sync' => true,                 // Set to false for queued alerts
     

   • Symfony vs. Laravel: The bundle is Symfony-first. In Laravel, ensure config/logging.php includes the alert channel.

2. Monolog Handler Conflicts

   • If alerts aren’t logged, check your Monolog stack in config/logging.php. The AlertHandler must be added to a channel (e.g., single or stack).
   • Debug: Temporarily add a StreamHandler to the alert channel to verify logs:

     'alert' => [
         'type' => 'stream',
         'path' => storage_path('logs/alert.log'),
         'level' => 'debug',
     ],
     

3. Template Caching

   • Clear views after modifying templates:

     php artisan view:clear
     

   • For Blade templates, ensure the alert_email.blade.php path is correct (Laravel may not auto-discover Symfony’s vendor/ views).

4. Queue Failures

   • If using queues (sync: false), ensure the SendAlertEmail job is registered in App\Console\Kernel:

     protected $commands = [
         \DesLynx\AlertBundle\Command\SendAlertEmail::class,
     ];
     

Debugging Tips

• Log Levels: Use Log::alert(), Log::warning(), etc., to ensure the correct Monolog level is triggered.
• Context Data: Verify context is passed correctly—missing keys in templates will show as null.
• Email Testing: Use a local SMTP server (e.g., MailHog) to test emails without spamming real addresses.

Extension Points

1. Custom Transports Implement DesLynx\AlertBundle\Transport\AlertTransportInterface to add Slack, PagerDuty, etc.:

   class SlackTransport implements AlertTransportInterface {
       public function send(Alert $alert): void {
           // Send to Slack webhook
       }
   }
   

   Register it in config/alert.php:

   'transports' => [
       'email' => DesLynx\AlertBundle\Transport\EmailTransport::class,
       'slack' => App\Transport\SlackTransport::class,
   ],
   

2. Alert Levels Extend the AlertLevel enum (Symfony) or override levels in config/alert.php:

   'levels' => [
       'critical' => \Monolog\Logger::ERROR,
       'high' => \Monolog\Logger::WARNING,
   ],
   

3. Monolog Processor Add a custom processor to modify alert data before sending:

   // config/logging.php
   'processors' => [
       DesLynx\AlertBundle\Processor\AlertProcessor::class,
   ],