mputkowski / laravel-discord-alerts
Post exception reports and custom messages to a Discord channel through a bot.
Package info
github.com/mputkowski/laravel-discord-alerts
pkg:composer/mputkowski/laravel-discord-alerts
Requires
- php: ^8.2
- guzzlehttp/guzzle: ^7.8.2 || ^8.0
- illuminate/console: ^11.0|^12.0|^13.0
- illuminate/contracts: ^11.0|^12.0|^13.0
- illuminate/support: ^11.0|^12.0|^13.0
Requires (Dev)
- orchestra/testbench: ^9.0|^10.0|^11.0
- phpunit/phpunit: ^10.5|^11.5|^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-20 15:01:32 UTC
README
Send exception reports and custom messages from a Laravel application to a Discord text channel using an existing Discord bot. Each application posts to its own channel, configured entirely through environment variables.
- Rich embeds, colour-coded by level, with trace, request or console context
- Cache-based de-duplication of repeated exceptions
- Optional role, user,
@hereor@everyonementions with tightly scopedallowed_mentions - Safe by design: never throws into your application, never sends request bodies, headers, cookies or query strings
- Silent no-op when unconfigured, so local and CI environments need no changes
Requirements
| Supported | |
|---|---|
| PHP | 8.2 – 8.5 |
| Laravel | 11 – 13 |
Upgrading from 0.x: 1.0 requires PHP 8.2+ and Laravel 11+ (13 is supported). Stay on
^0.1for older PHP or Laravel versions. The config file and environment variables are unchanged.
Installation
This package is not published to Packagist. Add the repository to the consuming application's composer.json:
{
"repositories": [
{ "type": "vcs", "url": "https://github.com/mputkowski/laravel-discord-alerts.git" }
],
"require": {
"mputkowski/laravel-discord-alerts": "^1.0"
}
}
composer update mputkowski/laravel-discord-alerts
Composer resolves versions from git tags.
The service provider and the DiscordAlerts facade alias are registered through package auto-discovery. To customise the configuration, publish it:
php artisan vendor:publish --tag=discord-alerts-config
Discord setup
- Use your existing bot and copy its token.
- Create one text channel per application and grant the bot View Channel, Send Messages and Embed Links on it (permission integer
19456, or150528with Mention Everyone). - Enable Developer Mode in Discord, right-click the channel and choose Copy Channel ID.
- To ping a role, the role must be mentionable, or the bot needs the Mention Everyone permission (
131072).
Configuration
DISCORD_ALERTS_BOT_TOKEN= DISCORD_ALERTS_CHANNEL_ID= DISCORD_ALERTS_MENTION= # optional, exception reports only
If the token or the channel ID is empty, nothing is sent.
DISCORD_ALERTS_MENTION accepts role:123, user:123, everyone or here. A bare ID is treated as a role.
| Option | Default | Description |
|---|---|---|
bot_token |
env('DISCORD_ALERTS_BOT_TOKEN') |
Discord bot token |
channel_id |
env('DISCORD_ALERTS_CHANNEL_ID') |
Default channel |
channels |
[] |
Named channels, e.g. 'billing' => env('DISCORD_ALERTS_CHANNEL_BILLING') |
mention |
env('DISCORD_ALERTS_MENTION') |
Ping added to exception reports |
ignore |
[] |
Extra exception classes that are never reported |
dedupe.enabled |
true |
Suppress identical exceptions |
dedupe.ttl |
300 |
Seconds an identical exception (class, file, line, message with numbers and quoted values ignored) is suppressed |
dedupe.store |
null |
Cache store, null for the default |
timeout |
3 |
Connect and request timeout in seconds |
trace_frames |
5 |
Trace frames included in the embed |
date_format |
H:i d.m.Y |
PHP date format of the embed footer, in the app timezone |
Usage
Reporting exceptions
In bootstrap/app.php:
use mputkowski\DiscordAlerts\Facades\DiscordAlerts; ->withExceptions(function (Exceptions $exceptions) { $exceptions->report(function (Throwable $e) { DiscordAlerts::report($e); }); })
The following are skipped automatically: exceptions your handler does not report ($dontReport), those listed in the ignore option, authentication, authorization, validation, model-not-found and token-mismatch exceptions, and HTTP exceptions with a 4xx status (other 5xx HTTP exceptions are reported, but 503, which is what maintenance mode throws, is skipped).
Each report contains the exception class, message, location, a trimmed stack trace and context: for HTTP requests the method, URL without query string, user ID and IP; for console commands the command name (arguments and options are omitted); for queue jobs the job class and queue.
Custom messages
DiscordAlerts::send('Deploy finished'); DiscordAlerts::send('Payment failed', [ 'channel' => 'billing', // named channel or raw channel ID 'level' => 'error', // info (default) | warning | error 'title' => 'Stripe webhook', 'fields' => [ 'Order' => '#1234', 'Amount' => '49.00 EUR', ], 'mention' => 'role:123456', // send() only pings when asked ]);
| Level | Colour | Title prefix |
|---|---|---|
info |
blue | none |
warning |
orange | 🟠 |
error |
red | 🚨 |
Message text, titles and fields are markdown-escaped. Both report() and send() return a boolean indicating whether Discord accepted the message and never throw.
Test command
php artisan discord-alerts:test
Sends a test message to the default channel and reports whether it was delivered.
Behaviour and limits
- Delivery is synchronous with a short timeout. Failed calls (including rate limits) are dropped, not retried.
- If the cache store is unavailable, de-duplication is skipped so the alert is still sent.
- Content is truncated to Discord's limits (4096-character description, 25 fields, 6000 characters per embed) without breaking code blocks.
Testing
composer install vendor/bin/phpunit
CI runs the suite against PHP 8.2 – 8.5 and Laravel 11 – 13.