Rest Doc Bundle Laravel Package

Product Decisions This Supports

• API contract hygiene / developer-facing documentation: The headline change is that generated API docs for collection endpoints now advertise order exactly as the API consumes it — comma-separated keys, each optionally suffixed :asc/:desc, and where #[ApiSortable] is declared, an explicit allow-list of keys with an example (title:desc). This is a direct upgrade to the self-serve quality of your public or partner API: consumers see valid sort keys and syntax in the spec instead of guessing.
• Deprecation management, not removal: direction continues to work at the RestBundle layer but is no longer documented. That is a textbook "soft deprecate, document the forward path" decision — it lets you keep existing integrations alive while steering new consumers to order=field:direction. Treat this as a scheduled migration item on the API deprecation calendar rather than an emergency.
• Breaking change triage / upgrade scoping: Two mechanical impacts. (1) New hard floor on gollumsf/rest-bundle: ^4.1. (2) CollectionHandler::__construct() now takes a MetadataSortManagerInterface; the service is autowired, so the default path is a no-op, but any team that decorates, replaces, or subclasses CollectionHandler must update. This is a "check your service overrides" upgrade, not a rewrite.
• Build vs. buy: Sort-parameter metadata, doc generation, and the deprecation path are being maintained upstream. Every release like this is evidence for staying on the buy side — you are outsourcing spec/code drift, which is exactly the class of work internal teams under-invest in.
• Roadmap input for API surface: If you want sortable-key allow-lists surfaced in docs for your own endpoints, the #[ApiSortable] attribute on entity and action is the mechanism. Without any declared sortables, order degrades to a free string in the docs — so there is a concrete roadmap task: annotate your high-traffic collection endpoints to get the richer contract.
• Quality signal for maintenance budgeting: Tested across Symfony 6.4 → 8.1 and PHP 8.2/8.4, 360 tests, 100% coverage. That breadth is a reasonable proxy for low maintenance risk and lets you plan the Symfony 8 upgrade with less fear of this dependency.

When to Consider This Package

Consider adopting (or keeping) it when:

• You expose collection endpoints through Symfony's RestBundle and generate API documentation as part of your developer experience — the value here is keeping generated docs truthful about sorting.
• You already depend on gollumsf/rest-bundle and are at ^4.1 or can get there; the upgrade is small and autowiring absorbs the DI change.
• You want an explicit, attribute-driven allow-list of sortable fields rather than accepting arbitrary order strings — useful both for documentation and for constraining expensive/unindexed sorts.
• You want the deprecation of direction handled upstream on your behalf, with a documented migration path for consumers.

Look elsewhere / defer when:

• You are not on RestBundle, or you hand-maintain your OpenAPI spec from a different source of truth — the sortable-metadata plumbing will not reach your docs.
• You have a hard pin below gollumsf/rest-bundle ^4.1 and cannot move this cycle; this release is then a blocker, not an improvement.
• You have custom subclasses or decorators of CollectionHandler and no capacity to update the constructor wiring — small, but sequence it deliberately.
• Your API consumers depend on direction being documented (e.g. generated SDKs keyed off that parameter). The parameter still functions, but the spec will stop advertising it; verify your SDK generation and contract tests before shipping.
• You need sorting semantics beyond key + asc/desc (multi-field custom comparators, cursor-based ordering) — this is documentation and metadata plumbing, not a sorting engine.

How to Pitch It (Stakeholders)

To executives: This is a low-risk maintenance release with one user-visible improvement: our generated API documentation now tells integrators exactly how to sort results, instead of describing a free-form parameter or an older direction convention. That reduces integration support load and spec drift. Cost is a routine dependency bump plus a short audit of any service overrides. No customer-facing behaviour is removed in this release; direction still works but is deprecated, so there is a defined migration window before we need to communicate anything to partners.

To engineering: Two action items. First, bump gollumsf/rest-bundle to ^4.1 — that is now a hard requirement. Second, grep for CollectionHandler replacements or extensions; the constructor now requires a MetadataSortManagerInterface, and autowiring covers the standard case only. Then adopt #[ApiSortable] on entity and action for our main collection endpoints so order is documented with a real allow-list and an example rather than as a free string. Migrate any docs/tests/SDK generation that assert on direction to order=field:direction. Confidence is high: 100% coverage across 360 tests on Symfony 6.4–8.1 and PHP 8.2/8.4, which also de-risks our Symfony 8 path.