Messenger Bundle Laravel Package

Getting Started

• Require the release with composer require <vendor>/<package>:^4.2 and immediately confirm the Symfony constraint resolved as expected:

  composer why symfony/http-kernel
  composer show <vendor>/<package> | grep -i symfony
  

  You should see Symfony 6.4+ (or 7.x on Laravel 11+).
• Look first at the package's service provider and its published config, then at the class responsible for unwrapping exceptions (search the source for getPrevious()). That one method governs almost every behaviour you will debug day-to-day.
• First use case: throw an exception from a route and from an artisan command, where the "real" error is wrapped, e.g.:

  throw new RuntimeException('Import failed', previous: new PDOException('SQLSTATE[HY000] ...'));
  

  Confirm the rendered/logged output shows the inner PDOException rather than the outer RuntimeException. Repeat in the console — this release exists precisely because Symfony 7 changed how wrapped exceptions are detected, so both surfaces need verifying.
• If you are on Laravel 11 (Symfony 7 components) and previously saw your wrapper class reported instead of the root cause, upgrading to 4.2.1 is the fix — no application code change required.

Implementation Patterns

• Let the package unwrap; don't duplicate it. Instead of writing instanceof ladders in App\Exceptions\Handler::report() / render(), throw domain exceptions that wrap the cause and let the unwrapper surface the root exception. Your handler then only needs to care about the final, meaningful type.
• Wrap deliberately, not accidentally. Wrapping is the right move for adding context ("order 1234 failed") while preserving the underlying cause. Unwrapping means the inner message is what users and logs see — so keep wrapper messages as pure context, never as the only place a critical detail lives.
• Custom exceptions + a marker interface. Give domain exceptions a stable contract (e.g. HasUserMessage, a render() method, or a report() override). Because unwrapping replaces the wrapper in the pipeline, any per-exception behaviour should live on the inner exception or be resolved via the unwrapped type.
• Consistent behaviour across HTTP and CLI. Use the same throw sites for both (actions and commands calling the same service), so the unwrapping rules apply once. This is the main day-to-day win: identical diagnostics in a request, a queued job, and artisan.
• Test both shapes. For each significant exception, assert the unwrapped form and the wrapped form renders/reports the intended class and message. Cover the queue worker too — failures there follow the same path but with different output formatting.
• Integration tip: register custom renderers/reporters after the package provider (or via config) so they receive the already-unwrapped exception. If you need the original wrapper, capture it in report() via $e->getPrevious() before delegating to the parent.

Gotchas and Tips

• Hard floor: Symfony 6.4+. On Laravel 10 pinned to Symfony 6.3 or lower, composer update will refuse to install 4.2.1. Options: upgrade to Laravel 11 (Symfony 7), bump the Symfony constraint, or pin the previous <4.2 release. Check composer why-not symfony/http-kernel 6.4 when resolution fails.
• Rendered output can change after this upgrade. Because Symfony 7 unwrapping is now fixed, you may start seeing the inner exception's class and message where you previously saw the wrapper — a fix that is still an observable behaviour change. Re-run any snapshot tests, assertSee assertions, or log-shape tests that encoded the old output.
• Alerting and log filters keyed on class names. If Sentry/Flare/Bugsnag grouping or your Handler::shouldReport() matches on the wrapper class, unwrapping changes what arrives. Re-check ignore lists and deduplication rules after deploying.
• Don't unwrap into nothing. Deep chains (framework wraps HTTP kernel exceptions in HttpException, which may wrap a domain exception) can walk further than you expect. Verify the unwrapper respects a sane depth limit and still reports something meaningful — a null/empty unwrap makes debugging worse, not better.
• Debugging recipe: dump the chain before blaming the package — while ($e) { dump(get_class($e)); $e = $e->getPrevious(); } — then compare against what the package reports. The mismatch point tells you whether the issue is your throw site, the package, or the FrameworkBundle version.
• Framework components must move together. symfony/http-kernel, symfony/http-foundation, and symfony/error-handler should be on the same minor. Mixed majors produce subtle unwrapping bugs that look like package regressions.
• After upgrading: composer dump-autoload, php artisan config:clear, php artisan optimize:clear, and restart queue workers (Horizon included) so the new code loads. Stale workers running the old unwrapper are the most common "the fix didn't work" report.
• Extension points: custom renderers, exception maps, and any userland unwrapping hook should be treated as idempotent — assume they may be handed an exception that is already fully unwrapped, and make the no-op path safe.