Problem Details Symfony Bundle Laravel Package

Technical Evaluation

Assessment basis: This is a Symfony bundle, not a Laravel package, and it is evaluated here against a Laravel/PHP estate. That framing determines almost everything below. The bundle (1 star, 0 dependents, last release 2025-02-11, MIT) exists to wire the framework-agnostic phauthentic/problem-details library into Symfony's kernel exception handling. The underlying concept — RFC 9457 (which obsoletes the RFC 7807 named in the description) problem documents with type, title, status, detail, instance — is genuinely valuable for any HTTP API. The bundle is not the deliverable we would consume.

Architecture fit

• Vendor mismatch is the headline risk. Laravel has no Symfony bundle kernel, no DI compiler passes, no services.yaml autoconfiguration. The bundle's core value — an exception listener registered into Symfony's kernel.exception event — has no automatic equivalent. Adoption in Laravel means either (a) using the framework-agnostic base library directly and writing our own renderer, or (b) forking the listener logic. Neither is "install and go."
• The base library is the reusable asset: it is a value-object/serializer concern and should be a leaf dependency. Confirm it does not drag in symfony/http-kernel, symfony/dependency-injection, or a second PSR-7/PSR-17 stack, because that is how a small error-formatting package becomes a framework-adjacent liability.
• Check whether the design hooks into the exception handler globally (a listener on every exception) versus opt-in per-exception-type mapping. Global interception in Laravel is withExceptions() in bootstrap/app.php, which is coarse and easy to over-apply — a single bad mapping can reshape every 500 the app returns.
• Confirm it does not attempt to own content negotiation or the response factory. If it does, we are replacing Laravel's Response/JsonResponse semantics for one code path, which produces inconsistency rather than standardization.

Integration feasibility

• What actually ports: the problem-document model, the type registry (type URI → status/title mapping), and the serializer. These are small, testable, and framework-neutral.
• What does not port: bundle configuration, service tags, the exception listener registration, and any Symfony-specific normalizer wiring.
• Version constraints on the base library (PHP floor, PSR interfaces, symfony/serializer if used for normalizers) versus our matrix. A symfony/serializer dependency in a Laravel app is a real footprint decision — Laravel ships its own JSON encoding path, and running two serialization stacks for error responses is a smell.
• Presence of a test suite and static analysis in the base library. With 1 star and 0 dependents there is no crowd-sourced validation, so CI signals are the only quality proxy we get.
• Spec drift: the description says RFC 7807 while the package name and repo say RFC 9457. They are compatible but not identical. Verify the emitted Content-Type is application/problem+json, not application/json — clients and API gateways key off that.

Technical risk

• Adoption risk is near-total. 1 star, 0 dependents, a single maintainer, and a release cadence we cannot infer from one tag. Treat this as "read the source, adopt the pattern," not "take a dependency."
• Maintenance cliff. A Symfony bundle's lifecycle tracks Symfony majors; our lifecycle tracks Laravel majors, which track different Symfony component versions. We would own a compatibility gap the maintainer has no incentive to close.
• Information disclosure. RFC 9457's instance field and verbose detail strings are the classic way internal hostnames, file paths, and stack fragments leak into client-facing errors. Any adoption must specify redaction rules before the first production deploy.
• Contract lock-in. Once API clients parse application/problem+json with a specific type URI vocabulary, changing that vocabulary is a breaking API change for consumers. The package choice is reversible; the published error contract is much less so.
• Low intrinsic runtime risk. This is a stateless formatting concern. No queues, no scheduled tasks, no schema, no Octane hazards — provided the base library stays a pure value-object layer. That is a genuine point in its favour.

Key questions

1. Can we consume the base phauthentic/problem-details library alone, with no Symfony bundle, and what is its dependency footprint?
2. Does the library hard-depend on symfony/serializer or any PSR-7 implementation, and can that be avoided?
3. Who maintains the base library and the bundle, and are they the same person? What is the release cadence over the last 24 months?
4. Is there a stable, documented type URI registry, or is type free-form per exception class? Free-form means we own the vocabulary from day one.
5. What is the test and static-analysis posture of the base library, given there is no downstream usage to catch regressions?
6. Does anything in the design assume Symfony's exception hierarchy or HttpExceptionInterface semantics that Laravel's HttpException does not mirror?

Integration Approach

Stack fit

• Recommended path: do not adopt the bundle. Use the base library (or its ~200 lines of model code) behind a Laravel-native exception renderer registered via withExceptions() in bootstrap/app.php, applied to API routes only.
• Reject outright if the base library pulls a second serializer into the runtime path. Laravel's JsonResponse plus a small ProblemDetails value object is sufficient and has zero dependency surface.
• If the estate also runs Symfony services, the bundle is a reasonable fit there — but that is a separate decision with separate ownership, and it should not be justified by Laravel needs.
• For Laravel-only estates, evaluate a Laravel-native RFC 9457 renderer first. The value is in the contract, not the package.

Migration path

• Publish the type URI vocabulary and status mapping into our own config/repo, not into package defaults. The vocabulary is the durable artifact; the library is replaceable.
• If replacing ad-hoc JSON error payloads, sequence as: define the target contract → implement renderer behind a feature flag for one API surface → validate client parsing → widen scope → remove legacy shapes. Do not big-bang the error contract across all endpoints; every consumer that pattern-matches on message breaks at once.
• Keep the problem-document construction behind a thin internal interface (ProblemFactory or equivalent) so the underlying implementation can be swapped without touching call sites. This is cheap here and is the entire mitigant for the adoption risk.

Compatibility

• Pin exact (0.x or whatever the current tag resolves to) if the base library is consumed directly; with no dependents there is no community signal that a patch bump is safe.
• Add Content-Type: application/problem+json assertions to contract tests, plus schema tests on required fields. These survive any library swap.
• Run composer why-not against the current lockfile before the spike — a symfony/serializer or PSR-7 collision is the most likely failure and it fails early and cheaply.

Sequencing

1. Spike (1 day): read the base library source, confirm it is dependency-light, prototype the Laravel renderer against three representative exceptions (validation, auth, unhandled).
2. Contract review: agree the type URI vocabulary, status mapping, and redaction rules with the API consumer owners. This is the real decision, not the package.
3. Adapter + contract tests: internal interface, one implementation, tests asserting RFC 9457 shape and media type.
4. Single API surface rollout behind a flag; confirm client parsing and gateway passthrough.
5. Widen, then record the pin rationale in the dependency register.

Operational Impact

Maintenance

• Recurring cost is dominated by our renderer, not the package. Budget ongoing ownership of the type vocabulary and redaction rules; those are application concerns that no package can carry for us.
• If the bundle is used anywhere (Symfony services), track it against Symfony majors and expect to be the ones filing the compatibility issue.
• Register the base library as a low-criticality dependency with an explicit note that it is a leaf value-object layer and is trivially forkable.

Support

• Assume self-support. 1 star and 0 dependents means issue triage latency is unobserved and unobservable at adoption time. Do not put a production error-path contract behind a maintainer's responsiveness.
• The support surface is the renderer and the vocabulary. Keep it to one file plus config so any backend engineer can reason about it without a handover.
• Document the redaction rules explicitly. The most likely production incident here is not a package failure — it is a detail field leaking a path or an internal ID.

Scaling

• Negligible runtime scaling impact: no I/O, no persistence, no external calls. This is one of the few genuinely safe request-path additions.
• Watch log volume, not throughput: standardized errors make it tempting to attach full context to every response, and verbose problem documents inflate both response size and log ingestion cost at 10x traffic.
• Verify behaviour under a reverse proxy / API gateway — some strip or rewrite Content-Type on 4xx/5xx, which silently breaks client discrimination between problem documents and generic errors.

Failure modes

• Vendor divergence: the Symfony bundle gains features the Laravel renderer cannot use, and our fork drifts. Mitigation: consume only the base library; never fork the bundle.
• Spec/implementation mismatch: application/json instead of application/problem+json, or missing type on unhandled exceptions. Mitigation: contract tests, not manual review.
• Information disclosure: instance/detail carrying internal identifiers or stack traces. Mitigation: explicit redaction policy plus a test asserting unhandled exceptions return a generic detail.
• Contract break for clients: vocabulary change on an internal refactor. Mitigation: treat type URIs as public API and review them under the same change control as endpoints.
• Abandonment: low blast radius here because the library is small and stateless — the exit is a rewrite of a few hundred lines, not a data migration.

Ramp-up

• Engineering: ~half a day for the spike if the base library is dependency-clean; ~1–2 days for the renderer, contract tests, and redaction handling. Reading the Symfony bundle is useful as a reference implementation even if we do not install it.
• Operations: minimal. No new infrastructure, credentials, queues, or scheduled tasks. One runbook line covering the Content-Type and redaction expectations is sufficient.
• PM/TPM: one dependency-register entry, one line in the API contract documentation, and a decision record stating that we adopted the RFC 9457 pattern rather than the Symfony bundle — otherwise a future engineer will "helpfully" install it.

Recommendation: Proceed on the pattern, decline the bundle. The RFC 9457 contract is worth standardizing across our APIs; this specific package is not the vehicle for it in a Laravel estate, given the vendor mismatch, 1 star, 0 dependents, and no observable support history. Fund a one-day spike on the framework-agnostic core library, approve only if it stays dependency-light, and treat the type vocabulary and redaction rules as the actual deliverable with an internal owner.