Laravel Discord Alerts Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-discord-alerts
   

   Publish the config file:

   php artisan vendor:publish --provider="Spatie\DiscordAlerts\DiscordAlertsServiceProvider"
   

2. Configuration: Edit .env and config/discord-alerts.php:

   DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/your-webhook-url
   

   return [
       'webhook_url' => env('DISCORD_WEBHOOK_URL'),
       'default_channel' => env('DISCORD_DEFAULT_CHANNEL', null),
       'default_username' => env('DISCORD_DEFAULT_USERNAME', 'Laravel App'),
       'default_avatar_url' => env('DISCORD_DEFAULT_AVATAR_URL', null),
   ];
   

3. First Use Case: Send a basic message in a controller or command:

   use Spatie\DiscordAlerts\Facades\DiscordAlert;
   
   DiscordAlert::message("Your app just deployed successfully!");
   

Implementation Patterns

Core Workflows

1. Basic Alerts:

   // Simple message
   DiscordAlert::message("User {$user->name} signed up!");
   
   // With embeds (rich formatting)
   DiscordAlert::embed(function ($embed) use ($user) {
       $embed->title("New User")
             ->description("{$user->name} ({$user->email})")
             ->color('green')
             ->addField('Role', $user->role)
             ->timestamp(now());
   });
   

2. Contextual Alerts: Attach data to alerts for debugging/logging:

   DiscordAlert::message("Payment failed for {$order->id}", [
       'order_id' => $order->id,
       'amount' => $order->amount,
       'user_id' => $order->user_id,
   ]);
   

3. Conditional Alerts: Use in exception handlers or middleware:

   try {
       // Risky operation
   } catch (\Exception $e) {
       DiscordAlert::message("Error in Order Processing", [
           'exception' => $e->getMessage(),
           'trace' => $e->getTraceAsString(),
       ]);
   }
   

4. Scheduled Alerts: Dispatch alerts via Laravel’s scheduler:

   // app/Console/Kernel.php
   protected function schedule(Schedule $schedule) {
       $schedule->call(function () {
           DiscordAlert::message("Nightly backup started at " . now()->format('H:i'));
       })->daily();
   }
   

5. Dynamic Webhook Routing: Override the default webhook per alert:

   DiscordAlert::message("Critical alert!", [], [
       'webhook_url' => 'https://discord.com/api/webhooks/critical-alerts'
   ]);
   

Integration Tips

1. Laravel Events: Bind alerts to events in EventServiceProvider:

   protected $listen = [
       'OrderShipped' => [
           function ($event) {
               DiscordAlert::message("Order #{$event->order->id} shipped to {$event->order->customer}");
           },
       ],
   ];
   

2. Queue Workers: Ensure the queue worker is running to handle async Discord calls:

   php artisan queue:work
   

   For production, use supervisor or foreman.

3. Testing: Mock the facade in tests:

   DiscordAlert::shouldReceive('message')
               ->once()
               ->with('Test alert');
   

4. Environment-Specific Config: Use .env to toggle alerts in staging/production:

   DISCORD_WEBHOOK_URL=production?https://prod-webhook:https://staging-webhook
   

Gotchas and Tips

Pitfalls

1. Webhook Rate Limits: Discord enforces rate limits. If alerts fail silently, check:

   • Queue retries (default: 3).
   • Discord’s API status.
   • Add error logging:

     DiscordAlert::catch(function ($exception) {
         Log::error("Discord alert failed: " . $exception->getMessage());
     });
     

2. Async Failures: Since alerts run in the background, use fail() to handle sync failures:

   try {
       DiscordAlert::message("Critical alert!");
   } catch (\Exception $e) {
       // Handle sync failure (e.g., queue misconfigured)
       abort(503, "Alerts disabled");
   }
   

3. Embed Limitations: Discord embeds have strict limits. Validate:

   • Title/description length (<256 chars).
   • Fields (<25 total).
   • Image/thumbnail URLs must be publicly accessible.

4. Webhook Permissions: Ensure your bot/user has permissions to send messages in the target channel. Test with:

   DiscordAlert::message("Test message", [], [
       'webhook_url' => 'https://discord.com/api/webhooks/test-url'
   ]);
   

Debugging

1. Queue Logs: Check storage/logs/laravel.log for queue job failures. Enable debug mode:

   config(['discord-alerts.debug' => true]);
   

2. Webhook Validation: Use Discord’s webhook tester to verify your webhook URL.

3. Common Errors:

   • 401 Unauthorized: Invalid webhook URL or token.
   • 403 Forbidden: Missing permissions or rate-limited.
   • 429 Too Many Requests: Exceeding rate limits (add delays or batch alerts).

Extension Points

1. Custom Alert Classes: Extend Spatie\DiscordAlerts\Alert for reusable alert types:

   namespace App\Alerts;
   
   use Spatie\DiscordAlerts\Alert;
   
   class DeploymentAlert extends Alert {
       public function __construct(string $environment, string $status) {
           $this->message = "Deployment to {$environment}: {$status}";
           $this->embed(function ($embed) {
               $embed->color($status === 'success' ? 'green' : 'red');
           });
       }
   }
   

   Usage:

   app()->make(DeploymentAlert::class, ['environment' => 'production', 'status' => 'success']);
   

2. Middleware: Add alert logic to middleware (e.g., HandleInactiveUsers):

   public function handle($request, Closure $next) {
       if ($user->isInactive()) {
           DiscordAlert::message("User {$user->name} inactive for 30 days");
       }
       return $next($request);
   }
   

3. Dynamic Content: Use Blade-like syntax for dynamic messages:

   DiscordAlert::message(view('discord.alerts.order_created', ['order' => $order])->render());
   

4. Local Testing: Use ngrok to expose a local webhook for testing:

   ngrok http 8000
   

   Configure .env:

   DISCORD_WEBHOOK_URL=http://localhost:8000/webhook