dragon-code/api-response
Build consistent Laravel API responses with a fluent, macro-friendly builder. Dragon Code's api-response helps you return success and error payloads, HTTP status codes, and resource collections in a uniform JSON shape, cutting boilerplate and keeping endpoints predictable.
What v10.0.0 changes — and what it does not. The release contains exactly two items: a bump of the internal dragon-code/support dependency to 6.0, and a docs update. No new features, no deprecations called out, no framework support statement, no Laravel integration, no test or CI changes described. Critically, the release notes do not mention Symfony 7, PHP 8.3/8.4, or a minimum-PHP bump — the three compatibility questions that mattered most in the prior assessment are still unanswered by the changelog. Two things do change in the assessment: the "archived / stale since 2022" characterisation must be revised (the maintainer is active and shipped a major version), and the risk profile shifts from dead dependency to low-velocity single-maintainer dependency with opaque major releases. The bottom line does not change.
Architecture fit. Unchanged and still the first thing a TPM must flag: dragon-code/api-response is a Symfony bundle. Integration surface is a bundle class in config/bundles.php, DI-container configuration, and a facade over symfony/http-foundation. Laravel shares HttpFoundation transitively, so the response-building layer is plausibly portable; the registration and configuration layer is not. v10.0.0 does nothing to narrow this gap — a Laravel-usable surface remains the envelope classes only, not the artifact as shipped.
Integration feasibility. Low-to-moderate, and now with one additional unknown. The dragon-code/support 6.0 bump is the whole substance of this major release, which means the semver-major signal is inherited from a dependency we do not control and whose changelog is not reproduced here. That dependency is where the PHP floor and the Symfony constraint most likely moved. Practical consequence: the Composer resolution check is now more load-bearing, not less — a v10 install may pull a higher minimum PHP or a tighter HttpFoundation range than v9.1.0, which could turn a previously-resolvable install into a hard stop. The integration work itself (service provider, singleton binding, config/api-response.php, facade alias) is unchanged at roughly 1–2 days — but see risk before spending it.
Technical risk. Re-ranked after v10.0.0:
andrey-helldar) — a bus factor of one, and no evidence of a second contributor reviewing the bump. This is better than abandoned and materially worse than healthy.9.1.0 → 10.0.0 with no migration guide, no upgrade notes, no breaking-change description beyond "bump support to 6.0." For a TPM, a major bump whose changelog cannot be mapped to behavioural change is a review cost, not merely a version number. We cannot tell from the release whether the envelope wire format changed — and the wire format is the only part of this package a Laravel team would use.ValidationException, 204, streams/files, pagination) and are not addressed by this release.Key questions to answer in a one-day spike (revised; items 1 and 6 are new or elevated):
dragon-code/support 6.0 pull Symfony packages we do not already have, or tighten the symfony/http-foundation constraint?EventDispatcher/KernelEvents?Key questions to answer in a one-day spike. (Items 1 and 6 above are new or elevated by this release; the remainder carry over unchanged.)
Stack fit. Assume Laravel 10+ and PHP 8.2+. Fit remains conditional: the envelope builder fits, the bundle does not. v10.0.0 does not change this, and the major-version bump slightly strengthens the case for not taking a runtime dependency — we would be adopting a brand-new major of a package with one release in three years and one line of documentation for the upgrade.
{ data, meta, errors } envelope in ~150–250 lines via JsonResource/ResourceCollection, a respond() helper, and a Handler::render override. Zero dependency risk, full framework-version support.Recommendation: Option B, unchanged. Option A remains the fallback only if the spike shows the package's contract is richer than expected (HAL/JSON:API links, custom status mapping, localised error messages) and clients already depend on that exact shape. v10.0.0 does not add any such capability, so it does not move this recommendation.
Migration path. Unchanged: (1) document the current wire format per endpoint; (2) define the target envelope as a spec, independent of implementation; (3) introduce the formatter behind a per-endpoint-group feature flag; (4) run old and new in parallel on staging with contract tests covering success, validation error, 404, 500, pagination, and empty collection; (5) cut over per endpoint, not per service.
Compatibility. Three axes, one of them now sharper: the symfony/http-foundation and PHP-floor constraints (v10.0.0 may have raised these — re-verify, do not assume v9 findings hold); PHP 8.3/8.4 deprecations; and response semantics — Laravel's exception handler runs outside any middleware-level formatter, so success and error paths diverge unless unified deliberately.
Sequencing. Spike (1 day, now including the v9→v10 diff) → decision (fork v10 vs fork v9 vs reimplement) → formatter + exception-handler integration (2–3 days) → contract tests (1–2 days) → staged rollout. ~1 sprint for a single service. If the spike reveals a Composer conflict — more likely against v10 than v9 — that is a hard stop; do not force resolution with --ignore-platform-reqs or a replace block in production.
Maintenance. Under Option A or B the code becomes ours, which is still the right outcome: a low-velocity dependency is maintenance you inherit without the practical ability to get upstream fixes prioritised. Budget ~1–2 days/year. One caveat added by this release: a major version with a two-line changelog tells you the upgrade path will be under-documented, so if we ever tracked upstream we would be reverse-engineering each release from a diff. That is a reason to fork at a known-good tag and stop tracking, not a reason to composer require.
Support. Effectively none, but no longer zero. The maintainer is demonstrably alive and shipping, so opening an issue is a real — if slow — escalation path, and a PR is plausible. Do not build a support model on that: one maintainer, no stated response SLA, 0 dependents meaning no Stack Overflow corpus. For a response-formatting layer this is tolerable; it must be a documented acceptance, not an accident.
Scaling. Unchanged and a non-issue computationally — O(1) per response relative to payload, one array copy before json_encode. The real scaling consideration is contractual: the envelope is an external API contract, so changing meta or error keys is a breaking change requiring versioning. Decide it once, document it in OpenAPI, resist endpoint-level drift. Confirm streaming/download endpoints bypass the formatter.
Failure modes to design against. Unchanged by this release: unhandled exceptions escaping the envelope (fix in Handler::render, not middleware); 422 validation errors in Laravel's {message, errors} shape; pagination meta drift; 204/empty responses emitting {"data": null}; 401/403 rendered before the formatter is in scope; and silent shared-component downgrade — verify with composer why symfony/http-foundation post-install.
Ramp-up. Trivial for implementers — a facade call and a documented envelope; a new hire is productive in under an hour. The risk sits with reviewers and API consumers: someone must own the envelope spec and enforce it in code review. Assign that ownership explicitly at adoption time; with no meaningful upstream project to point at, the spec lives only in our repo.
Bottom line for the decision record (revised): do not adopt the package as a runtime dependency. Revise the rationale — the upstream is not archived, it is a single-maintainer, low-velocity, Symfony-only package that ships undocumented major versions. The pattern remains sound and worth standardising on; the artifact remains framework-mismatched and ecosystem-unvalidated, and v10.0.0 adds upgrade opacity without adding capability. Reimplement the envelope internally behind a facade, or fork the classes with attribution at a pinned tag. The deliverable is an internal, owned, tested abstraction — not a composer require line. Before finalising the decision record, re-verify the repository's archival status, since the existence of this release contradicts the prior assessment's "archived" characterisation and that distinction affects the fork-vs-upstream calculus.
How can I help you explore Laravel packages today?