Download the PHP package nightshift-foundry/laravel-alertstream without Composer

AlertStream - Laravel Alert & Exception Reporting

A lightweight, extensible Laravel package that captures exceptions and sends rich alerts to Slack, Teams, Discord, and Mail, plus any custom destination you build. No configuration required for exception reporting, queue-friendly, and runs completely off your request hot path.

Features

• 🚨 Automatic exception reporting - no code changes required after install
• 📡 Built-in channels - Slack, Microsoft Teams, Discord, Mail (one env var to activate each)
• 🔌 Fully extensible - implement one interface and tag it; AlertStream discovers it automatically
• ⚡ Queue-friendly - runs async via a queue worker by default, or inline synchronously if preferred
• 📋 Rich context - exception class, severity, URL, user ID, IP, user agent, environment
• 📸 Snapshots - persist exceptions to the database with a secure, hash-based URL for full stacktrace viewing
• 🛡️ Throttling - prevent alert storms by limiting duplicates per minute
• 🔗 Deduplication - group identical exceptions into a single snapshot with occurrence count
• 🎯 Severity mapping - override auto-detected severity per exception class via config
• 🧩 Context enrichers - plug in custom callables to add tenant ID, git SHA, or any data to every alert
• 🔔 Notification channel - use AlertStream as a Laravel notification channel alongside mail, SMS, etc.
• 💚 Health check endpoint - JSON endpoint to verify AlertStream status from monitoring dashboards
• 🔄 Webhook retry - automatic retry with backoff on transient webhook failures

Installation

Publish the config:

Built-in Channels

Activate any channel by adding its name to ALERTSTREAM_CHANNELS and supplying its credentials. No code changes needed.

Slack

Microsoft Teams

Teams no longer supports direct incoming webhooks the way Slack and Discord do. The reliable approach is a Power Automate flow that receives the alert payload and posts it as a formatted chat message.

1. Create the flow

1. Go to make.powerautomate.com and create a new Instant cloud flow
2. Choose "When an HTTP request is received" as the trigger
3. Add a "Post message in a chat or channel" action — set Post as to Flow bot, choose your team and channel

4. Set the Message field to the expression:

5. Save the flow — the HTTP trigger URL will appear on the trigger step. Copy it.

2. Configure the package

That's it. AlertStream POSTs an HTML-formatted payload to your flow, which passes the message straight through to the channel. The message includes severity-coded colours, bold exception details, file location, environment, and a View Full Stacktrace link when snapshots are enabled.

Note: The HTTP trigger URL contains a SAS token and acts as a secret — treat it like a password and store it in your .env, never in source control.

Discord

Mail

Multiple channels at once:

Custom Channels

Need PagerDuty, Telegram, OpsGenie, or your own internal system? Implement the AlertChannel contract and tag it. AlertStream discovers it automatically alongside the built-in ones.

1. Implement the contract

2. Register and tag it in any service provider

AlertStream iterates every class tagged alertstream.channel, built-in or custom, and calls send() on each one. No config keys to add, no arrays to update.

Automatic Exception Reporting

Once installed, all application exceptions are captured automatically with no changes to app/Exceptions/Handler.php.

Every alert includes:

Toggle reporting:

Muting Exceptions

Some exceptions are noise: 404s, validation errors, unauthenticated requests. AlertStream ships with sensible defaults already muted, and you can extend the list freely.

Default muted exceptions

These are ignored out of the box:

Adding your own muted exceptions

Append to the mute array in config/alertstream.php:

Muting is class-hierarchy aware, so muting a parent class also suppresses all its subclasses.

Unmuting a default at runtime

If you need to re-enable reporting for a default muted class, call report() on the Handler in a service provider:

Queue Configuration

Why queue matters

When an exception is thrown, AlertStream needs to send HTTP requests to Slack, Teams, Discord, etc. These calls can take 100-500 ms each. With the queue enabled, this work is handed off to a background worker instantly and the request returns to the user without waiting. With the queue disabled, all channel calls happen inline, adding their latency directly to the response time.

Recommendation: keep the queue enabled in production (ALERTSTREAM_QUEUE=true, the default). Use false only in local dev or when you have no queue worker.

Queue on (default, recommended for production)

When the queue is on, you must have at least one queue worker running, otherwise alerts will sit in the queue unprocessed. If you don't have a worker, set ALERTSTREAM_QUEUE=false instead.

Preferred: give AlertStream its own named queue. This isolates alert jobs from your business jobs and lets you tune their worker independently:

If ALERTSTREAM_QUEUE_NAME is not set, jobs are pushed to the default queue and any existing worker that processes default will pick them up automatically with no extra configuration.

Queue off (sync, for simple setups or local dev)

All channel calls run synchronously in the same process. No worker needed. Suitable when you have no queue infrastructure, or for local development where you want to see alerts fire immediately without running a worker.

Note: even with ALERTSTREAM_QUEUE=false, each channel still fails silently in isolation, so one broken webhook will never crash the application.

Snapshots (opt-in)

Exception messages in Slack, Teams, Discord, or email are often truncated or hard to read. Snapshots solve this by persisting every exception to your database and including a secure, hash-based URL in every channel message. Click through to see the full stacktrace, context, and metadata in a clean web view.

Enabling snapshots

When enabled, AlertStream will:

• Load its migration - creates the alertstream_snapshots table
• Register routes - a GET /alertstream/snapshots/{hash} endpoint to view snapshots
• Register the prune command - alertstream:prune-snapshots
• Include a "View Full Stacktrace" link in every channel message automatically

When disabled (the default), none of the above happens. No migrations are loaded, nothing is written to the database, no routes exist.

Running the migration

Configuration

In config/alertstream.php you can also set route_middleware to protect the snapshots viewer (default: ['web']):

Security

Snapshot URLs use a 64-character SHA-256 hash, making them unguessable and non-sequential. If you need additional protection, add 'auth' or a custom middleware to route_middleware.

Pruning old snapshots

Snapshots are automatically eligible for pruning after 30 days (configurable via ALERTSTREAM_SNAPSHOTS_RETENTION), but you must schedule the pruning command yourself since Laravel packages cannot register scheduled tasks on behalf of the host application.

⚠️ Required: add one of the following to your scheduler, otherwise old snapshots will accumulate indefinitely.

Option 1 - Laravel's built-in model pruning (recommended if you already use it):

The Snapshot model uses MassPrunable, so Laravel discovers and prunes it automatically alongside any other prunable models in your app.

Option 2 - Dedicated AlertStream command:

Or run it manually:

Deleting individual snapshots

Each snapshot page includes a Delete button. Clicking it removes the snapshot immediately, which is useful when a snapshot contains sensitive information and you don't want to wait for automatic pruning.

Customising the snapshot view

This publishes the view to resources/views/vendor/alertstream/snapshots/show.blade.php where you can customise the layout, styling, and content.

Manual Usage

AlertStream provides two distinct ways to send messages:

report() - exception alerts

Use report() when something goes wrong and someone should know about it. The message is written to your configured Laravel log channels and dispatched to every active notification channel (Slack, Teams, Discord, Mail, or any custom channel). Snapshots, throttling, and deduplication all apply.

log() - structured logging at any level

For operational visibility, diagnostics, and auditing, use log(). It writes to your configured Laravel log channels only and does not trigger notifications, create snapshots, or go through throttling.

The $level parameter accepts any log level that Laravel supports (the standard PSR-3 levels):

Examples:

A debug() convenience method is also available as a shorthand:

When should I use report() vs log()? Use report() when you have a caught exception and want the team notified via Slack/Teams/Discord/Mail. Use log() for everything else. It gives you structured, levelled logging through AlertStream's configured channels without triggering external notifications.

Dependency injection

Artisan test command

The --type flag accepts any log level string and defaults to alert (which triggers report()). Any other value is passed directly to log() at that level.

Throttling

Prevent alert storms when the same exception fires hundreds of times in a short window. Enable throttling to limit how many alerts per exception (same class + file + line) are sent per minute.

When the limit is hit, additional occurrences are silently dropped until the window resets. Snapshots (if enabled) still record every occurrence via dedup, but only the channel notifications are throttled.

Severity Mapping

AlertStream auto-detects severity based on exception type (PDOException -> critical, HttpResponseException -> warning, etc.). Override or extend this via severity_map in config:

The map is checked via instanceof, so parent classes cover their subclasses.

Context Enrichers

Add custom data to every alert without modifying AlertStream internals. Each enricher is an invokable class:

Register enrichers in config:

Enrichers run in order. If one throws, it is silently skipped and reporting continues with the remaining enrichers.

Snapshot Deduplication

When a snapshot already exists for the same exception (same class + file + line) within the configured window, AlertStream increments the existing snapshot's occurrence counter instead of creating a duplicate row.

Set to 0 to disable deduplication and create a new row for every exception.

The snapshot index view displays the occurrence count as a badge (e.g. "12x") and the detail view shows "Last seen" alongside the original timestamp.

Notification Channel

Use AlertStream as a native Laravel notification channel and compose alerts with the same API you already use for mail, SMS, database, etc.

Health Check Endpoint

A JSON endpoint is registered at GET /{route_prefix}/health to check AlertStream's runtime configuration. Useful for uptime monitors and deployment verification.

Response:

Configuration Reference

Core

Queue

Channels

Throttling

Severity & Enrichment

Snapshots

Package Structure

Local Development

Test the package locally in another project using path repositories (changes are reflected instantly via symlink):

Development

The pre-commit hook runs php-cs-fixer automatically on every commit (installed via composer install).

License

MIT - see LICENSE.

Changelog

See CHANGELOG.md.