diff --git a/core/default-order.md b/core/default-order.md index f6670acc71b..d3487e1dd7c 100644 --- a/core/default-order.md +++ b/core/default-order.md @@ -114,8 +114,7 @@ App\ApiResource\Book: -Another possibility is to apply the default order for a specific collection operation, which will -override the global default order configuration. +Another possibility is to apply the default order for a specific collection operation. @@ -163,3 +162,56 @@ App\ApiResource\Book: ``` + +## Global Default Order and Operation Order Precedence + +`api_platform.defaults.order` (set under the `defaults:` key in `api_platform.yaml`) applies an +order to every operation. It is not a fallback that yields to operation-level configuration — it is +a cross-cutting invariant that is always applied. + +When an operation also defines its own `order`, the two arrays are **merged**: the global default +keys come first, followed by the operation-level keys. This means the global default takes priority +in the SQL `ORDER BY` clause, and the operation-level keys act as tie-breakers. + +For example, given this configuration: + +```yaml +# config/packages/api_platform.yaml +api_platform: + defaults: + order: + createdAt: DESC +``` + +And this resource: + +```php + 'ASC']), +])] +class Book +{ + public \DateTimeImmutable $createdAt; + public string $title; +} +``` + +The effective order for the `GetCollection` operation is +`['createdAt' => 'DESC', 'title' => 'ASC']`, producing `ORDER BY createdAt DESC, title ASC`. The +global default is prepended to the operation-level order, not replaced by it. + +This behavior is intentional. `api_platform.defaults.order` is designed for invariants such as +"always order by `createdAt DESC`" that must hold across all collections regardless of which +operation is called. + +**If you want an operation to use a specific order with no global keys prepended**, do not set +`api_platform.defaults.order`. Instead, set the `order` explicitly on each operation or resource +where you need it. For more control over ordering logic, implement a custom +[Doctrine ORM extension](extensions.md) that replaces the built-in `OrderExtension`.