Skip to content

Document admin_api_multistore feature flag prerequisite in CONTEXT.md #205

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jolelievre merged 2 commits into from
May 20, 2026
Merged

Document admin_api_multistore feature flag prerequisite in CONTEXT.md #205

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1d92974
Document admin_api_multistore feature flag prerequisite
jolelievre May 20, 2026
4ab4382
Document DateTimeImmutable as a second allowed property type
jolelievre May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 22 additions & 8 deletions CONTEXT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@ OAuth2 scope naming: `{entity_snake_case}_{action}`.
| Localized fields — no `localized` prefix | `$names` | `$localizedNames` |
| All public properties strictly typed | `public int $contactId` | `public $contactId` |
| Decimals — use `DecimalNumber`, never `float` | `public DecimalNumber $price` | `public float $price` |
| Dates — `DateTimeImmutable` is allowed | `public DateTimeImmutable $dateAdd` | `public string $dateAdd` |

Array fields representing complex structures must include
`#[ApiProperty(openapiContext: ['type' => 'array', 'items' => [...]])]`
Expand Down Expand Up @@ -161,13 +162,22 @@ the current usage pattern.

## Multi-shop

> **Experimental — feature flag required.** Admin API support for
> multistore is gated behind the `admin_api_multistore` feature flag
> (Advanced Parameters → New & Experimental Features). The conventions
> below describe how endpoints must be written so they behave correctly
> in multistore, but they only take effect at runtime once the flag is
> enabled. Without the flag, multistore context parameters are ignored
> and the API falls back to single-shop behavior.

When PrestaShop's multistore feature is **disabled**, the API
automatically uses the default shop — no extra parameters are needed.

When multistore is **enabled**, every API request **must** include a shop
context parameter (otherwise the API returns 400). The
`ShopContextListener` in the Core reads these parameters from the
request and builds a `ShopConstraint` that CQRS commands/queries use:
When multistore is **enabled** (and the `admin_api_multistore` feature
flag is on), every API request **must** include a shop context
parameter (otherwise the API returns 400). The `ShopContextListener` in
the Core reads these parameters from the request and builds a
`ShopConstraint` that CQRS commands/queries use:

| Request parameter | Context built | Use case |
|---|---|---|
Expand Down Expand Up @@ -247,10 +257,14 @@ See `Product.php`, `Combination.php`, `CombinationList.php`, and
`#[LocalizedValue]`, `ApiResourceMapping`, `CQRSQueryMapping`, and
`CQRSCommandMapping` instead. CI enforces this.
- Don't expose Value Objects as DTO properties. Public properties must
be scalar (`int`, `string`, `bool`) or `array`. The single allowed
exception is `PrestaShop\Decimal\DecimalNumber`, which **must** be
used instead of `float` for any decimal / monetary value — never
`float`. This is checked by the CI.
be scalar (`int`, `string`, `bool`) or `array`. Two exceptions are
allowed:
- `PrestaShop\Decimal\DecimalNumber` — which **must** be used instead
of `float` for any decimal / monetary value (never `float`).
- `DateTimeImmutable` — allowed for date / datetime properties.

This is enforced by the `ApiResourcePropertyTypeRule` PHPStan rule in
CI.
- Don't return raw command results. If the endpoint should return data,
define proper DTO properties and wire a `CQRSQuery`.
- Don't declare an operation without a scope.
Expand Down
Loading