Problem Details Symfony Bundle Laravel Package

Getting Started

First, the framework mismatch. This is a Symfony bundle, not a Laravel package. It plugs into Symfony\Component\HttpKernel events (kernel.exception) and registers via config/bundles.php. Laravel does not ship symfony/framework-bundle, does not use bundle auto-registration, and has its own exception pipeline (App\Exceptions\Handler / Illuminate\Foundation\Exceptions\Handler). You cannot composer require this and get Problem Details responses in a Laravel app — the listener will never fire. If your day-to-day is Laravel, treat this package as a reference implementation for the RFC 9457 payload shape, not as a dependency.

If you are on Symfony (or a Laravel/Symfony hybrid that boots the framework bundle), the minimal path is:

1. composer require phauthentic/problem-details-symfony-bundle
2. Register the bundle in config/bundles.php (Flex may auto-register if a recipe exists — verify, since this package is at 1 star and likely has no recipe).
3. Publish/reference the config: config/packages/phauthentic_problem_details.yaml.
4. Map one exception class to a problem type and a status code.

Where to look first: the package's DependencyInjection/ extension and the exception listener — confirm exactly which kernel.exception listener it registers and at what priority relative to Symfony's own ErrorListener/ExceptionListener. Also check the ProblemDetails library it depends on (phauthentic/problem-details), which owns the actual payload schema; the bundle is mostly wiring.

First real use case: throw a domain exception (e.g. OrderNotFoundException) from a controller, hit the route with Accept: application/json, and confirm the response has Content-Type: application/problem+json and a body with type, title, status, detail, instance. That single round-trip tells you whether the listener is registered, the mapping resolved, and serialization is correct.

Implementation Patterns

Config-driven exception mapping. The primary pattern is declarative: each exception class → {type, title, status} in YAML. Keep a single config/packages/*.yaml file per bounded context so the mapping doesn't become a 400-line monolith. Use RFC-defined type URIs (e.g. https://datatracker.ietf.org/doc/html/rfc9110#section-15.5.5) where a standard exists, and reserve URN-style custom types (urn:myapp:problem:out-of-stock) for domain-specific cases.

Custom ProblemDetails implementations. For domain-specific fields (e.g. available_quantity, sku) that don't fit the five standard members, extend the base class and add a custom normalizer. RFC 9457 explicitly permits extension members, so this is the sanctioned way to add context without abandoning the standard.

Exception hierarchy strategy. Rather than mapping every exception class individually, define a base HttpProblemException implementing an interface the bundle can resolve (e.g. exposing getType(), getStatus(), getTitle()). Then map the interface once and let exceptions carry their own metadata. This scales far better than YAML sprawl and keeps the response definition next to the code that throws it.

Controller vs. listener boundary. Use the listener for cross-cutting error shapes (validation, 404, conflicts). For a single endpoint where the problem document is the success contract (e.g. a 409 workflow response), construct the ProblemDetails object directly and return it — don't throw a synthetic exception just to trigger the listener.

Testing pattern. Because the bundle is tiny and low-maturity, pin behaviour with a contract test: a single functional test asserting Content-Type: application/problem+json and the exact JSON shape for one mapped and one unmapped exception. That test is your tripwire when the package is upgraded or replaced.

Laravel-adjacent pattern, if you're porting the idea. You can reproduce ~90% of this in App\Exceptions\Handler::render() or via a ProblemDetailsException interface implemented by your exceptions, with a small renderer that builds the payload. That is the pragmatic route for Laravel apps and removes the dependency entirely.

Gotchas and Tips

Debug mode swallows the format. In Symfony's dev/debug environment, the exception handler shows the HTML profiler page instead of a problem document. Verify behaviour with APP_ENV=prod or by inspecting the raw Response object in a test — do not trust the browser during the spike.

Listener priority is load-bearing. If your own kernel.exception listener (or a third-party one) runs at a lower priority number, it may consume, re-wrap, or overwrite the response. Inspect with debug:event kernel.exception and confirm the bundle's listener priority is what you expect.

Information disclosure. The default detail for a mapped exception must not be the exception message unless you control it — raw messages leak SQL, file paths, and PII. Prefer a static detail string for production mappings and log the real exception separately. This is the single most common production incident with error-shape libraries.

RFC 7807 vs RFC 9457. The package name says RFC 9457, the description says RFC 7807. They're compatible for the five core members, but RFC 9457 clarifies type optionality and adds application/problem+json as the required media type. Confirm the actual Content-Type the library emits — clients that parse strictly will break on application/json.

Version pinning and maturity. At 1 star, 0 dependents, a single release (2025-02-11), and no changelog, treat this as pre-1.0 risk in a 1.0.0 wrapper. Pin the exact version in composer.json, publish the config into your repo (don't inherit package defaults), and write the contract test above before you rely on it. Expect to be self-supporting.

Serializable exceptions only. Exceptions that carry non-serializable properties (resources, connections, closures) will fail during normalization if a custom normalizer naively dumps the object. Normalize explicitly — never (array) $exception.

PHP and Symfony constraints. Check composer why-not against your Symfony minor before install. A bundle at this maturity is unlikely to be tested against every LTS; if your project runs Symfony 7.2 and the bundle requires ^6.4|^7.0, you're on untested ground.

Extension points are the escape hatch. The bundle advertises custom ProblemDetails implementations and normalizers — that is your path to adding project-specific fields without forking. Use them; a fork of a 1-star package is a maintenance dead end.

Framework portability note. If the goal is a standardised error shape across Laravel and Symfony services in the same org (a plausible reason to look at this), the spec is portable but this bundle is not. Adopt the RFC 9457 payload contract internally, implement it natively per framework, and keep this package as a Symfony-only implementation detail.