Document multi-shop usage of the Admin API#2146
Merged
Merged
Conversation
Add a dedicated consumer-facing page covering the shop context request parameters (shopId, shopGroupId, shopIds, allShops), the shopIds response property, and the experimental admin_api_multistore feature flag prerequisite. Add a "Handle multi-shop association" subsection to the contributor guide describing the shopIds DTO property convention, query/command mapping direction, and the [_context] prefix used to pass shop context to CQRS commands and queries.
The ps_apiresources module ships an AI-oriented CONTEXT.md and a set of .claude/ skill files that document conventions and CI-enforced rules which were either undocumented or out of date in the devdocs. This commit closes the gap so the public contributor guide stays aligned with the source of truth contributors actually work from. contribute-to-core-api.md: - Document the DecimalNumber requirement for decimal/monetary fields and the DateTimeImmutable allowance for date/datetime fields; correct the "NO Value Objects" callout that previously listed float as allowed and update the rule reference to the ApiResourcePropertyTypeRule PHPStan rule. - Add a callout describing the standard PrestaShop core domain folder layout so contributors know where to find Command / Query / QueryResult / Exception classes. - Note the EntityId value-object quirk on CQRSCreate (Add commands that return an EntityId need a CQRSQuery to re-fetch the full object). - Add a "Finding the correct source field names" tip explaining that the QueryResult class is the ground truth for CQRSQueryMapping and the command constructor is the ground truth for CQRSCommandMapping. - Clarify when to share a single COMMAND_MAPPING constant vs split CREATE_/UPDATE_ versions. - Explain the two attributes required on bulk operation Ids properties. - Document the prohibition on mapping constraint violations to 400 (always 422), and remind contributors to map parent-entity NotFoundException to 404 on sub-resource endpoints. - Explain why #[DefaultLanguage] needs an explicit fieldName argument on ApiResource attributes (auto-detection only works in Form contexts). - Add a "Verifying DTO ↔ query field alignment" subsection in the List section: a 5-step check that catches orphan DTO fields and missing ApiResourceMapping renames before review. - Document the default test environment (forced debug-secured off, auto-installed fr-FR, language and API client resets) and the static fixture helpers available on ApiTestCase (addLanguageByLocale, addShopGroup, addShop, updateConfiguration, createApiClient). - Document the local code-quality scripts: composer header-stamp-fix, composer phpstan (and its env var requirements), composer rector. - Add the missing bulkDeleteItems and requestApi helpers to the integration test helper table. - Add a common-pitfalls checklist at the end of "Key Points to Remember" mirroring what the CI / pre-review bot flags. resource_server/api-resources.md: - Document CQRSGetCollection (previously only referenced in passing). - Add a custom-parameters table for PaginatedList, matching the style already used for CQRSPaginate.
mattgoud
approved these changes
May 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Backports the multi-shop conventions from the
ps_apiresourcesmodule'sCONTEXT.mdinto the public v9 Admin API documentation. The information was missing from devdocs even thoughshopIdsalready appeared in several code examples.The content is split across two audiences:
New consumer-facing page
admin-api/multi-shop.md(weight 150, betweenhow-to-useandcontribute-to-core-api). Covers:shopId,shopGroupId,shopIds,allShops— with query-string and request-body curl examples.shopIdsresponse property and how it differs from the request-level parameters.admin_api_multistorefeature flag (Advanced Parameters → New & Experimental Features).New subsection in
admin-api/contribute-to-core-api.md—#### Handle multi-shop association, placed right afterHandle localized values. Covers:$shopIdsarray DTO property convention.QUERY_MAPPING/COMMAND_MAPPINGdirection (read:associatedShopIds → shopIds, write: the reverse).[_context][shopId]/[_context][shopIds]/[_context][shopConstraint]mapping prefix for passing the request's shop context into CQRS commands and queries.A follow-up commit on this branch is expected to extend the content further.
Test plan
hugo serve) and verify the new page appears in the Admin API chapter menu between "How to use" and "Contribute to Core API".contribute-to-core-api.mdtomulti-shop.mdresolves.{{% notice warning %}}shortcode).