Exceptions Bundle Laravel Package

Getting Started

Validate the package identity before you install anything. The repository is phisys/exceptions-bundle — a Symfony bundle for dosfarma/exceptions integration. The description.md provided here describes a "Laravel-native" package with publishable config and migrations; that text does not match the repository name, the dependency (dosfarma/exceptions), or an exceptions-bundle naming convention. Treat the Laravel framing as inaccurate until you have read the actual composer.json and src/. If you are on Laravel, this is probably not the package you were told it is.

Assuming you are on Symfony:

1. Install: composer require phisys/exceptions-bundle (it will pull dosfarma/exceptions as a transitive dependency — check the constraint it resolves to, since both are old).
2. Register the bundle: with Symfony Flex it lands in config/bundles.php automatically; otherwise add Phisys\ExceptionsBundle\PhisysExceptionsBundle::class => ['all' => true].
3. Read three files first, in this order: src/PhisysExceptionsBundle.php (what it actually registers), src/DependencyInjection/*Extension.php + Configuration.php (what is configurable — assume the surface is small), and the dosfarma/exceptions base classes in vendor/dosfarma/exceptions/src. There is no meaningful README, so the source is the documentation.
4. Import the bundle config into config/packages/ if the extension exposes a tree. If Configuration.php has no nodes, there is nothing to configure — the bundle is wiring only, and your behavior lives in the dosfarma classes.
5. First use case: throw a typed exception from a controller or service and confirm the resulting HTTP response. This validates the whole value proposition in one request: exception class → status code → rendered body. If that does not work out of the box, stop and reassess before building on it.

Implementation Patterns

Wrap vendor exceptions behind your own base class. Define App\Exception\AppException extends Dosfarma\...\BaseException (or whatever the vendor root is) and throw only your classes from application code. This is the single cheapest exit strategy: when the bundle goes stale — and at 0 stars, one release in 2021, it will — you swap the parent class in one file instead of grepping hundreds of throw statements.

Drive rendering through a kernel.exception listener, not scattered try/catch. The idiomatic Symfony shape is one listener that inspects the thrown exception, maps it to a status code and a response body, and delegates to content negotiation. If the bundle already registers such a listener, decorate or extend it; if it does not, write your own and treat the bundle purely as a source of exception types.

Keep the mapping table in config, not in conditionals. A flat array of ExceptionClass => ['status' => 422, 'code' => 'VALIDATION_FAILED'] in config/packages/ is testable, greppable, and reviewable in a diff. Hardcoded instanceof chains in a listener rot fast.

Use the framework-agnostic base classes for CLI and queue consumers. One of the few genuinely useful properties of dosfarma/exceptions being a separate package is that typed exceptions carry meaning outside the HTTP kernel — a console command or Messenger handler can throw the same NotFound and let its own boundary decide how to surface it, rather than importing Symfony HTTP concerns into domain code.

Attach context at throw time, not at catch time. If the base classes support a context payload, populate it with correlation IDs, resource IDs, and the operation name where the error originates. By the time the listener sees it, the relevant locals are gone and you are reconstructing the story from stack traces.

Separate API and HTML rendering at the listener. For JSON endpoints return a stable envelope (error.code, error.message, error.context); for HTML let Symfony's error controller take over unless you have a real reason to override. Mixing the two in one code path produces JSON leaking into browser tabs.

Write one integration test that exercises the full path — throw each mapped exception through a test client (static::createClient() + a route that throws) and assert status + body shape. This is the upgrade canary: when a Symfony major forces a fork or replacement, this test tells you exactly what broke.

Gotchas and Tips

• The documented and actual package are different things. The Laravel description in this assessment bundle is not credible for this repository. Confirm the framework and the dependency graph from composer.json before you write a line of integration code or a proposal.
• Last release 2021-04-28, 0 stars. That predates Symfony 6 and PHP 8.1. Expect the composer.json constraints to block Symfony 6/7 and PHP 8.2+ resolution. You can often loosen a constraint in your root composer.json and let it resolve, but only after reading the source to confirm it does not use APIs removed since — and only if you are prepared to own it.
• There is effectively no upstream. No issue triage, no security process, no compatibility releases. The bundle's surface is small, which is the only thing that makes this defensible: plan to vendor it or fork it as a routine act, not an emergency. Record that as a known carrying cost.
• Config caching bites on config-driven changes. In prod, bin/console cache:clear (or a deploy that warms cache) is required before mapping changes take effect. Debugging "my new status code isn't applied" in a container that skipped cache warmup is a classic wasted hour.
• Listener priority matters. Symfony's ErrorListener and the exception event have ordering; if your listener does not fire, check getSubscribedEvents priority and whether a kernel.exception listener registered earlier called setResponse() and stopped propagation. bin/console debug:event-dispatcher kernel.exception shows the actual ordering.
• Do not leak internal messages in production. Whatever maps exceptions to bodies must distinguish "safe to show the user" from "log only." A typed exception carrying a database error string will render it to the client unless you explicitly whitelist user-facing messages.
• Decorate, don't fork, for the first extension. If you need different rendering, use services.yaml service decoration on the bundle's handler rather than editing vendor/. Forking is the signal you have outgrown the package, not a first-line customization technique — at that point bring a build-vs-buy recommendation rather than quietly absorbing maintenance.
• Sanity-check the PHP version floor. Old bundles frequently use annotations, createMock signatures, or @expectedException patterns that break under PHPUnit 10+/PHP 8.3. If the test suite in vendor/ is dead, your integration test becomes the only safety net.
• If you are on Laravel, do not try to make this fit. The service provider, kernel, and exception-handler contracts are different; a Symfony bundle is not portable to Laravel without a shim you would then own. Use a Laravel-native exception package (or just Laravel's Handler + a small base class) instead.