Rest Doc Bundle Laravel Package

Getting Started

• Require the package (and ensure gollumsf/rest-bundle:^4.1 is installed — older versions may not expose the metadata the doc generator needs).
• Start with the #[ApiSortable] attribute. Declare it on the entity properties/fields you want clients to be able to sort by, e.g. title and author on a Product entity.
• Generate your API docs and inspect the order parameter. If sortable keys are declared, the docs will list them:

  order  string
         Comma separated sort keys, each optionally suffixed by ":asc" or ":desc".
         Allowed keys: title, author.
         example: title:desc
  

• First real use case: annotate one resource, regenerate docs, and confirm the order parameter now advertises concrete sort keys instead of a free-form string. Then exercise GET /resource?order=title:desc to verify runtime behaviour matches the docs.

Implementation Patterns

• Entity-level defaults, action-level overrides. Put #[ApiSortable] on the entity for keys that are always sortable, and add it to controller actions to restrict or extend the allowlist per endpoint. This keeps the generated docs aligned with what each endpoint actually supports.
• Document exactly what RestBundle parses. Use the documented syntax order=title:desc,author:asc everywhere — examples, tests, and client SDKs. The generated example (title:desc) is a good template.
• Migrate direction callers. Replace any direction=desc usage in clients, test fixtures, and API examples with order=field:desc. The runtime still accepts direction, but it is deprecated and no longer surfaced in docs.
• Custom collection handling. If you decorate or replace CollectionHandler, update the constructor to accept MetadataSortManagerInterface. Normal usage needs no change because the service is autowired.
• Per-endpoint allowlists. Use action-level attributes to prevent clients from sorting on expensive or non-indexed columns even when the entity exposes them.
• CI docs diff. Regenerate the OpenAPI/Swagger output in CI and diff it so sortable-key changes are reviewed like code.

Gotchas and Tips

• Silent free-string fallback. With no #[ApiSortable] declared, order is documented as a free string. This is easy to miss and gives clients no guidance; audit endpoints to ensure sortable keys are actually declared.
• direction is doc-invisible but still live. Clients relying on generated documentation will no longer discover direction. Treat it as deprecated in your own docs and plan removal before the next major.
• Constructor signature change. CollectionHandler::__construct() now takes MetadataSortManagerInterface. Subclasses, decorators, and manual service definitions must be updated; autowired setups are unaffected.
• Attribute placement matters. An attribute on the wrong class or method silently produces no keys. If order still shows as a free string, verify the attribute is on the entity/action the doc generator inspects, then clear caches.
• Version pin. Confirm gollumsf/rest-bundle:^4.1 is resolved; an older lockfile can leave docs without the new metadata.
• Platform coverage. Tested on Symfony 6.4–8.1 and PHP 8.2/8.4. Verify your own runtime matrix if you are outside those ranges.
• Example fidelity. The generated example uses title:desc; make sure your declared sort keys map to real fields/columns, otherwise clients will follow docs into runtime errors.