Alerting Laravel Package

Getting Started

Reality check before you start. This package has zero stars, zero dependents, and a single release (Nov 2025). Treat it as an internal-grade dependency: usable, but you are the QA team. Budget time to read the source (vendor/micro-module/alerting/src) before wiring it into production, and wrap it behind your own thin service class so you can swap it out if maintenance stalls.

Minimal steps

1. Install and pin the exact version — do not use a floating constraint on a package with one release:

   composer require micro-module/alerting:^1.0
   

2. Publish whatever config/service provider assets ship with it:

   php artisan vendor:publish --provider="MicroModule\\Alerting\\AlertingServiceProvider"
   

   If the tag-based publish (--tag=alerting-config) works, prefer it — it avoids dumping unrelated assets.
3. Inspect config/alerting.php. This is your first stop: it will tell you the channel/driver list, default recipients, thresholds, and whether the package expects queueing. Read it top to bottom before touching env vars.
4. Set the minimum env vars (typical shape — confirm names against the config file, they are the #1 source of "nothing happened"):

   ALERTING_ENABLED=true
   ALERTING_CHANNEL=log        # start with log/mail, not Slack
   ALERTING_QUEUE=false
   

5. Fire a smoke-test alert from php artisan tinker using the facade or the injected alert service. Confirm it lands in storage/logs/laravel.log before configuring any real transport.

First use case: route application exceptions (or failed queue jobs) to the log channel in local/staging, then flip to mail/Slack in production. That gives you a working loop with zero external credentials and proves the package is actually booting — the most common failure with low-traffic micro-packages is a service provider that registers but never resolves.

Implementation Patterns

Wrap it, don't sprinkle it. Create one adapter so your codebase has a single seam:

final class Alerts
{
    public function __construct(private AlertManagerContract $alerter) {}

    public function critical(string $message, array $context = []): void
    {
        $this->alerter->send(level: 'critical', message: $message, context: $context);
    }
}

Bind it in a small service provider and inject Alerts everywhere. When the package goes stale, you rewrite one file.

Pattern: exception handler hook. The highest-value integration is bootstrap/app.php / app/Exceptions/Handler.php — alert on reportable exceptions, but gate by environment and throttle:

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->reportable(function (Throwable $e) {
        if (app()->isProduction() && $this->shouldAlert($e)) {
            app(Alerts::class)->critical($e->getMessage(), ['exception' => get_class($e)]);
        }
    });
})

Pattern: queue-failure alerting. Listen for JobFailed / QueueFailed events and alert with the job class name and queue. This is where alerting packages earn their keep, because failed jobs are silent by default.

Pattern: module-scoped alerts. Given the micro-module namespace, the package likely expects each module to register its own alert context or recipients. Check for a module registration method (e.g. a config merge or a ModuleAlerting trait) and register per-module recipients rather than one global to address — otherwise a billing-module alert pages the whole team.

Pattern: thresholds over per-event alerts. For anything metric-driven (error rate, queue depth), aggregate first and alert on the threshold. Fire-and-forget per-event alerts on a Laravel app will produce a Slack channel nobody reads within a week.

Pattern: staged rollout. Local = log, staging = mail to a team list, production = Slack/PagerDuty. Keep all three in config keyed by environment so the code path is identical everywhere and only the transport differs.

Integration tip: if the package supports queued delivery, enable it in production — but only after your queue worker is proven. An alerting package that dispatches to a queue that is itself down is a false sense of safety. Consider a synchronous fallback for critical level.

Gotchas and Tips

No community safety net. Zero dependents means no Stack Overflow answers, no blog posts, no one else's bug reports. When something breaks, vendor/micro-module/alerting/src is your only documentation. Diff the vendor directory after every composer update and consider committing a lockfile pin plus a short internal note explaining why the dependency exists.

Silent failure is the default failure mode. Alerting packages typically swallow transport errors so they never break the request that triggered them — which means a misconfigured webhook looks exactly like "no alerts happened." Always ship a boot-time or artisan health check (php artisan alerting:test if provided, otherwise your own smoke command) and log a warning when a send fails.

Config cache. After editing config/alerting.php, run php artisan config:clear. On a cached-config production deploy, env var changes do nothing until the cache is rebuilt — a classic post-deploy "alerts stopped" incident.

Rate limits and duplicate storms. A loop of 500 exceptions can emit 500 alerts. Add deduplication (hash of message + class) or throttling in your Alerts wrapper rather than relying on the package. If it exposes a throttle/dedupe config key, verify it actually works by hammering the smoke test — don't assume.

Queue + serialization. If alerts are queued, any context array you pass must be serializable. Passing an Exception object or an Eloquent model with lazy relations will blow up in the worker, and the failure will be swallowed. Convert to scalars ($e->getMessage(), $e->getCode(), class name, request ID) before handing it over.

Recursion hazard. If your alert transport is mail or Slack and the mail/HTTP layer itself throws, and you're alerting from the exception handler, you can loop. Guard with a static "already alerting" flag or restrict alerting to non-HTTP/console transports inside the handler.

Extension points to look for. Most packages in this genre expose a driver/contract interface (AlertChannel, Notifier) or an event fired before/after send. If it does, implement a custom channel (e.g. your own Teams webhook or internal incident API) instead of forking. If it doesn't expose a contract, that's a signal to keep the wrapper thin and be ready to replace it.

Test in isolation. Fake the transport in your test suite — even if the package doesn't ship a fake() helper, bind a no-op implementation of your Alerts interface in TestCase. Never let CI attempt real webhook calls; the flakiness will train your team to ignore red builds.

Version pinning is non-negotiable. With one release and no maintainer track record, ^1.0 is optimistic. Pin 1.0.* at most, and add the package to your quarterly dependency review list.