Laravel Exception Notifier Laravel Package

Getting Started

• Version gate: V5.0.0 supports Laravel 9 through 13 with a PHP floor of ^8.0 (each Laravel version enforces its own higher minimum, so don't read the package constraint as "PHP 8.0 is enough on Laravel 13"). Laravel 7/8 must stay on 2.2.0; Laravel 6 and below on 1.2.0.
• Install:

  composer require jeremykenedy/laravel-exception-notifier:"^5.0"
  php artisan exception-notifier:install
  

  The command scaffolds the missing pieces and prompts for an email layout (legacy or modern) and a theme (light, dark, or system). Defaults are the legacy layout and light theme — you get existing behaviour unless you opt in.
• What gets published: the config/exceptions.php configuration, a mailer class, the email view(s), and a Handler trait copied into your application. That trait is what actually hooks exception reporting into the framework's report() path — it is not auto-registered.
• First wiring steps:
  1. Open config/exceptions.php and set the recipient address(es), from address, subject, and mailer connection.
  2. Add the copied trait to App\Exceptions\Handler (Laravel 9/10). On Laravel 11+ there is no default Handler class — create one or wire the reporting path in bootstrap/app.php first, otherwise the trait never runs and nothing is sent.
  3. Set MAIL_MAILER=log locally and trigger a real exception (throw new \Exception('test') from a route or php artisan tinker) to confirm the mail renders. Tune the mailer only after you've seen a message.
• Where to look first: config/exceptions.php (all supported keys and content fields), the published mailer class (subject/recipient logic and where you add context), the published view (layout markup), then docs/installation.md, docs/upgrading.md, and docs/testing.md in the repo.
• Best first use case: production uncaught-exception alerting to an on-call address or team inbox — human-readable stack trace plus request context, delivered the moment it happens, as a complement to (not a replacement for) an aggregator like Sentry.

Implementation Patterns

• Trait-in-Handler is the happy path. Keep the trait's report() call thin and let configuration drive everything else. If you need custom routing logic (e.g. page the on-call only for 5xx in business hours), override in the mailer rather than editing the trait — the trait is a copied class you'll have to diff on every upgrade.
• Exclusion hygiene is the main tuning knob. Route expected noise — 404s, validation failures, AuthenticationException, 4xx HttpException, control-flow exceptions — into the don't-report list. V5 specifically fixed the copied trait's inherited-property conflict while preserving application exclusions, so re-check your exclusion list after upgrading; a copy that silently drops them is the classic failure mode.
• Environment split. Enable only where you want mail: MAIL_MAILER=log locally, a shared dev mailbox on staging, real recipients in production. For staging, point to at a team alias rather than individuals so test storms don't page anyone.
• Recipients. Prefer an array of addresses over a comma-separated string. V5 fixed the PHP 8.4/8.5 implicit-CSV-escape deprecation in recipient parsing, but an array sidesteps string parsing entirely and is easier to drive from env/config.
• Custom views. Point exceptions.emailExceptionView at your own Blade file and keep the data contract the package passes in. Note the consequence: a custom view is intentionally not touched by the update command, so upstream view fixes (like the mobile long-path overflow fix in the legacy layout) won't reach you automatically.
• Themes. Set emailExceptionTheme to light, dark, or system. system uses client-side prefers-color-scheme detection in the modern layout — great for dark-mode users, but you should still ship a readable light fallback for clients that ignore the media query.
• Switching layout deliberately:

  php artisan exception-notifier:update --layout=modern --theme=system --force
  php artisan view:clear
  

  --force is mandatory to overwrite an already-published view, and it will only proceed if the backup succeeds.
• Upgrade as a deploy step. Treat the update command as idempotent maintenance rather than a one-off:

  composer update
  php artisan exception-notifier:update --no-interaction
  php artisan config:clear   # or config:cache in your normal deploy flow
  php artisan view:clear
  

  Run it on staging first and git diff the published files — that's the only reliable way to see what changed under you.
• Storm control. Reporting is synchronous and no callbacks are registered for you. For apps where a dependency outage can throw thousands of exceptions per minute, wrap the mailer in a cache-based throttle (Cache::add("exc-notify:{$fingerprint}", ...)) keyed on exception class + file + line. This is the single highest-value addition on a high-traffic app.
• Companion, not competitor. Let this package answer "what broke, right now, in words a human can read in their inbox" and let an aggregator answer "how often, since when, trending". Wire both; don't try to make email do deduplication and grouping.
• Verification recipe: a fresh route that throws, an artisan command that throws, and a queued job that throws — confirm all three arrive, and confirm your exclusions still suppress a 404.

Gotchas and Tips

• Composer updates never touch published files. Config, mailers, and views are yours once published — composer update will not fix them. The V5 mailer fixes and the Handler trait's property-conflict fix must be applied by hand to already-published copies, or by re-publishing selectively after backing up. Budget for this on every upgrade.
• Missing emailExceptionTheme. Older published config predates the key, so theme selection silently does nothing. Add the key by hand rather than republishing over your customisations. Same story if you've cached config — rebuild after any change.
• --force discipline. The safety design is good (backup, preserve original on failed write, remove newly created files on failed install), but don't put --force in an automated pipeline. Overwriting a view is a code change; it deserves a diff and a commit.
• Synchronous delivery bites. The report runs in the request lifecycle, so a slow or hanging SMTP server delays your error response and can turn a 500 into a timeout. If mail delivery itself throws inside the reporting path, you risk masking the original exception. Wrap the send in a try/catch (or push onto a queue via your own Mailable) so notification failures never cascade.
• Silent failure on Laravel 11+. No default App\Exceptions\Handler means no trait, means no mail — and no error telling you so. Also verify your withExceptions configuration doesn't bypass the reporting path.
• Custom view means frozen view. If you set exceptions.emailExceptionView, the V5 modern layout and the mobile long-path fix are opt-in via a manual port. Copy the new markup into your custom file when convenient.
• view:clear after layout/theme switches. Compiled Blade views will happily serve the old layout until you clear them. Same for config:clear/config:cache after editing theme or recipients.
• Laravel 9 early releases. V5 restores support for the original build() mail API including 9.20. If you've customised the Mailable with envelope()/content() only, test on the exact 9.x you run — the transitional releases are where mail-shape mismatches surface.
• Theme rendering is client-dependent. Gmail's app and Outlook handle prefers-color-scheme inconsistently. Always check the dark variant at both mobile and desktop widths — the package's own Chromium suite covers layout/theme/width/contrast, which is a good checklist to mirror manually.
• Recipient string parsing. The CSV-escape deprecation fix matters only if you feed a comma-separated list. Array recipients avoid the whole class of problem.
• Sensitive data in email. A stack trace plus request context is exactly what makes the alert useful and exactly what makes it a data-leak risk (headers, cookies, user identifiers, form payloads). Review what the mailer includes before enabling in production and redact aggressively — mail is far easier to forward accidentally than a logging stack.
• Publish paths are registered at provider boot so configured application paths are respected — set custom publish/view paths before you publish, not after, or you'll get files in the default location.
• Version pin for old apps. Laravel 7/8 on 2.2.0 and ≤6 on 1.2.0 — if composer resolves something odd on an old app, check the framework constraint first, not PHP.
• Extension points to prefer: the published mailer class (subject, recipients, extra context, throttling) and the config file. Avoid editing the copied trait — it's the file most likely to conflict with upstream fixes, and it's the one that can silently break exclusion handling.