From 90b2e320bafd2099d1bb7016288675b1f0539ea5 Mon Sep 17 00:00:00 2001 From: tleon Date: Wed, 25 Mar 2026 16:41:32 +0100 Subject: [PATCH] Add PaginatedList documentation and claude skill --- .claude/document-custom-operation/SKILL.md | 68 +++++++++++++++++++ admin-api/resource_server/api-resources.md | 79 ++++++++++++++++++++++ 2 files changed, 147 insertions(+) create mode 100644 .claude/document-custom-operation/SKILL.md diff --git a/.claude/document-custom-operation/SKILL.md b/.claude/document-custom-operation/SKILL.md new file mode 100644 index 0000000000..9515602e66 --- /dev/null +++ b/.claude/document-custom-operation/SKILL.md @@ -0,0 +1,68 @@ +Generate developer documentation for a PrestaShop Admin API custom operation class. + +**Arguments:** `$0` = operation name, `$1` = PrestaShop core path + +Example invocation arguments: `toggle-exchange-rate-automatization-command /home/tleone/Dev/prestashop-develop` + +## Task + +You are writing documentation for the PrestaShop devdocs site (https://devdocs.prestashop-project.org/9/admin-api/resource_server/api-resources/). The target page is `admin-api/resource_server/api-resources.md` in this repository. Your output will be a new section to add to that file for operation `$0`. + +## Steps + +### 1. Read the operation class + +The PrestaShop core source is at `$1`. Find operation `$0` in `src/PrestaShopBundle/ApiPlatform/Metadata/`. Read it fully to understand: +- What it extends and what interfaces it implements +- Its constructor parameters (especially the custom ones beyond standard API Platform params) +- How it stores extra properties and what defaults it sets +- What provider/processor it enforces + +### 2. Find real-world usages + +Search for usages of the operation in `modules/ps_apiresources/src/` and `src/PrestaShopBundle/ApiPlatform/Resources/` inside the core repo. Pick 1–2 representative examples that cover the most important parameters. + +### 3. Study the existing documentation format + +Read `admin-api/resource_server/api-resources.md` in this repository to understand the current format and where the new section should be inserted (after the last existing CQRS operation section, before `## PaginatedList`). + +Each custom operation follows this structure: + +``` +### OperationName + +| HTTP Method | Action | +|---|---| +| METHOD | one-line description | + +Brief paragraph explaining what the operation does and when to use it over alternatives. + +```php +// full realistic example based on actual usages +``` + +Behavioral notes about provider/processor, response shape, caveats. + +#### Custom parameters + +| Parameter | Type | Required | Default | Description | +|---|---|---|---|---| +| `paramName` | `string` | Yes | — | What it does | +``` + +### 4. Generate the documentation section + +Write a documentation section for the operation following the format above. The section must include: + +- **Header**: `### OperationName` +- **HTTP method table** +- **Description paragraph**: what problem it solves, when to use it over alternatives +- **PHP code example**: realistic, based on actual usages found in step 2, showing the most important parameters with full namespace/use declarations and class body +- **Behavioral notes**: how the provider/processor works, what the response looks like, any important caveats +- **Custom parameters table**: only list parameters that are unique to this operation (not standard API Platform params). Columns: Parameter, Type, Required, Default, Description + +Keep the tone consistent with the existing devdoc pages: technical and direct, no marketing language. + +### 5. Insert into the file + +Insert the generated section into `admin-api/resource_server/api-resources.md` at the correct location. Then confirm the insertion was successful. diff --git a/admin-api/resource_server/api-resources.md b/admin-api/resource_server/api-resources.md index 94289fe74d..e5871d8615 100644 --- a/admin-api/resource_server/api-resources.md +++ b/admin-api/resource_server/api-resources.md @@ -285,6 +285,85 @@ class ApiClient } ``` +### CQRSPaginate + +| HTTP Method | Action | +|-------------|-----------------------------| +| GET | Read a paginated collection | + +`CQRSPaginate` is the CQRS-based equivalent of `PaginatedList` for endpoints backed by a CQRS query instead of a `GridDataFactory`. Use it when you have a CQRS query that handles pagination internally and returns a result object containing both an items list and a total count. Use `PaginatedList` instead when you need to reuse an existing grid data factory. + +```php + '[languageId]', + '[_context][shopConstraint]' => '[shopConstraint]', + ], + ApiResourceMapping: [ + '[combinationName]' => '[name]', + '[attributesInformation]' => '[attributes]', + '[impactOnPrice]' => '[impactOnPriceTaxExcluded]', + ], + filtersClass: ProductCombinationFilters::class, + filtersMapping: [ + '[_context][shopId]' => '[shopId]', + ], + itemsField: 'combinations', + countField: 'totalCombinationsCount', + ), + ], + exceptionToStatus: [ + ProductNotFoundException::class => Response::HTTP_NOT_FOUND, + ], +)] +class CombinationList +{ + public int $productId; + public int $combinationId; + public string $name; + public bool $default; + public string $reference; + public array $attributes; +} +``` + +The provider (`QueryListProvider`) builds a `Filters` object from the request query parameters (`offset`, `limit`, `orderBy`, `sortOrder`, `filters`), executes the CQRS query, and returns a `PaginationElements` object with pagination metadata alongside the items. The default page size is 50 items. + +The CQRS query receives pagination parameters plus URI variables and context parameters automatically. The normalized query result must expose the items array and total count as top-level fields, identified by `itemsField` and `countField`. + +#### Custom parameters + +| Parameter | Type | Required | Default | Description | +|---|---|---|---|---| +| `CQRSQuery` | `string` | Yes | — | Fully qualified class name of the CQRS query to execute. The query must handle pagination internally. | +| `scopes` | `string[]` | No | `[]` | OAuth scopes required to access the endpoint. | +| `CQRSQueryMapping` | `array` | No | `null` | Field mapping applied when denormalizing the query object and normalizing the query result. See [Custom Mapping](#custom-mapping). | +| `ApiResourceMapping` | `array` | No | `null` | Field mapping applied when denormalizing each item from the query result into the API resource DTO. See [Custom Mapping](#custom-mapping). | +| `filtersClass` | `string` | No | `Filters::class` | Fully qualified class name of the `Filters` subclass to use. Specify a custom class to enforce default ordering or filtering constraints. | +| `filtersMapping` | `array` | No | `null` | Maps API field names to the internal names used by the `Filters` class. Applied to `filters` and `orderBy` query parameters. See [Custom Mapping](#custom-mapping). | +| `itemsField` | `string` | No | `'items'` | Name of the field in the normalized CQRS query result that holds the list of items. | +| `countField` | `string` | No | `'count'` | Name of the field in the normalized CQRS query result that holds the total item count. | + ## PaginatedList For listing operations we provided a custom operation based on the core grid system based on two settings: