Api Resource Bundle Laravel Package

Getting Started

Start by generating or inspecting the <Entity>Filters catalogue for an existing entity, then open the generated filter class and locate the QueryParameter arguments. In v2.2.0 every generated filter parameter now includes description: ''; system parameters status and realm are exempt.

First steps:

1. Run the package generator for a small entity.
2. Inspect the generated <Entity>Filters class and the corresponding DTO.
3. Find the application architecture test that rejects empty descriptions.
4. Fill in the generated description: values from the front-end roadmap before exposing the endpoint.

First use case: scaffold filters for a new API resource, fill the French descriptions, and let the architecture test confirm that every non-system filter is documented before merge.

Implementation Patterns

• Treat generated filter descriptions as part of the scaffold, not optional metadata. Generate the filter, then immediately complete each QueryParameter(description: '...').
• Mirror the DTO convention from 2.1.0: DTOs use #[ApiProperty(description: '')], and filters now use the same empty-description placeholder on QueryParameter. Keep both layers aligned when documenting an entity.
• Leave status and realm alone. These are application-level system parameters and are explicitly exempt from the description requirement.
• Use the architecture test as a definition-of-done gate: a new filter is not exposed until its description is filled and the test passes.
• Fill descriptions in French, matching the front-end roadmap wording, so API docs and UI labels stay consistent.
• For regeneration workflows, generate first, then complete descriptions in the same branch. Review diffs carefully because regeneration can overwrite manual edits depending on stub/config behaviour.
• In CI, run the architecture test alongside the normal test suite. This catches newly generated filters that were committed with the placeholder description: ''.

Gotchas and Tips

• The generated description: '' is intentionally incomplete. The application architecture test will fail until you fill it. This is expected behaviour, not a generator bug.
• Do not add placeholder descriptions just to satisfy the test. The test checks for empty strings, not whether the description is accurate or useful.
• Be careful when regenerating filters after entity changes: manual descriptions may be overwritten. Commit generated output separately from description edits where possible, or customise the package stubs if supported.
• status and realm are exempt because they are system parameters from the application. Do not treat their missing descriptions as an oversight.
• The architecture test lives application-side, not in the package. Ensure it is present and running in CI; otherwise the new generated placeholders can slip through.
• If descriptions are maintained in French, coordinate with the front-end roadmap before filling them. Empty descriptions are easy to detect; wrong or stale descriptions are not.
• Check published stubs/configuration first if you need to change the generated description: default or add project-specific wording. That is the cleanest extension point before editing generated files directly.