Rest Doc Bundle Laravel Package

Technical Evaluation

Architecture fit. This release is a Symfony/RestBundle-oriented change, not a Laravel-native one. The package depends on gollumsf/rest-bundle and MetadataSortManagerInterface, and documents sorting via #[ApiSortable] attributes on entities and actions. For a Laravel codebase, that means bringing in Symfony’s attribute/metadata layer or adapting the package’s metadata discovery to Laravel conventions. Fit is therefore conditional: strong inside a Symfony service, weak inside a pure Laravel service unless the team already uses Symfony components or an API-platform style metadata layer.

Integration feasibility. The functional change is narrow and well-bounded: order is now documented against declared sortable keys, with comma-separated keys and optional :asc/:desc suffixes. The only constructor change is CollectionHandler::__construct(MetadataSortManagerInterface), which is autowired. In a standard Symfony service container this should be invisible. In a Laravel service provider, it requires explicit binding and alias registration for MetadataSortManagerInterface, which is extra integration work but not architecturally difficult.

Technical risk. Main risks are: (1) a consumer-facing contract change in generated API documentation — direction disappears from docs and order gains a constrained value set; any generated SDK, contract test, or client integration relying on the old documented parameter shape can break; (2) the direction parameter is deprecated but still functional, creating a dual-path period where docs and runtime behavior diverge; (3) the dependency floor is raised to gollumsf/rest-bundle: ^4.1, which may conflict with applications pinned below that; (4) custom service definitions or decorators around CollectionHandler must inject the new metadata manager explicitly; (5) the test matrix covers Symfony 6.4–8.1 and PHP 8.2/8.4, but the absence of PHP 8.3 and Symfony 7.x edge combinations should be checked against the target environment. The reported 360 tests and 100% coverage reduce but do not eliminate these risks.

Key questions. Which of our services are actually Symfony versus Laravel, and does this package belong in both? Do we generate OpenAPI specs or client SDKs from the annotations — and if so, what downstream artifacts change when direction is removed from docs? Do we replace or decorate CollectionHandler anywhere? Are any applications pinned to gollumsf/rest-bundle <4.1? Is #[ApiSortable] already adopted, or will the order documentation fall back to a free-form string because no sortable keys are declared? What is the deprecation timeline for direction in the upstream bundle?

Integration Approach

Stack fit. Best fit is a Symfony application using RestBundle and attribute-based metadata. For a Laravel application, treat this as a cross-framework integration: confirm that the Laravel container can resolve MetadataSortManagerInterface and that the entity/action metadata discovery mechanism is reachable. If the package is only consumed for its documentation-generation behavior, isolate it to the API documentation pipeline rather than the request path.

Migration path. Three audiences need separate handling. Application code: usually no change because CollectionHandler is autowired; verify by running the container compile and the existing test suite. Customizations: any service definition, decorator, or subclass of CollectionHandler must pass MetadataSortManagerInterface. API consumers: update documentation and generated clients from direction=asc to order=field:asc, and check that any client sending direction still behaves as expected during the deprecation window. Dependency management: bump gollumsf/rest-bundle to ^4.1 and resolve conflicts before merging.

Compatibility. Confirm the runtime Symfony and PHP versions are inside the tested matrix: Symfony 6.4–8.1, PHP 8.2 and 8.4. PHP 8.3 is not explicitly listed, so validate separately if it is in use. The direction parameter remains backward-compatible at runtime but not in generated documentation, so contract tests that assert on the OpenAPI schema will fail and should be updated deliberately rather than suppressed.

Sequencing. First, upgrade the gollumsf/rest-bundle constraint and run the container/test suite to catch constructor wiring issues. Second, add #[ApiSortable] attributes to entities and actions where sorting is intended, so order documents real allowed keys instead of a free-form string. Third, regenerate API documentation and diff it; review the direction removal and order enum changes as an intentional contract change. Fourth, update generated clients and consumer-facing docs. Fifth, track direction usage in logs or gateway metrics to confirm no active clients remain before the upstream removal.

Operational Impact

Maintenance. Low ongoing maintenance for standard setups because the service is autowired and the release is primarily documentation and metadata behavior. The main maintenance burden is the deprecation of direction: during the transition, teams must maintain awareness that docs and runtime differ. Keep the bundle constraint current and avoid drifting below ^4.1.

Support. Support load will concentrate on two areas: API consumers noticing changed documentation or generated clients, and developers who have overridden or decorated CollectionHandler and hit constructor errors. Prepare a short internal note mapping direction=asc to order=field:asc and clarifying that direction still works but is deprecated.

Scaling. No meaningful runtime scaling impact; the change affects metadata resolution and documentation generation, not request throughput. If #[ApiSortable] metadata is resolved per request, confirm it is cached by the framework’s metadata cache in production, consistent with existing annotation/attribute handling.

Failure modes. Container compilation failure when MetadataSortManagerInterface cannot be resolved in a non-Symfony container. Hard failure when the gollumsf/rest-bundle constraint conflicts with another package. Silent behavioral drift when direction continues to work at runtime but disappears from docs, causing clients to be built against an incomplete contract. Incorrect or missing #[ApiSortable] declarations causing order to remain documented as free-form, defeating the purpose of the release.

Ramp-up. Small for teams already on Symfony with RestBundle: the constructor change is transparent and the documentation change is mostly mechanical. Larger for Laravel teams or teams without attribute metadata: expect effort to wire the metadata manager, verify attribute discovery, and update documentation tooling and generated clients. Budget most of the ramp-up for the API contract review and consumer communication, not for code changes.