From ca02e9320b86bda67ebeb97ea4e66ecad7932569 Mon Sep 17 00:00:00 2001
From: soyuka <soyuka@users.noreply.github.com>
Date: Fri, 5 Jun 2026 17:40:19 +0200
Subject: [PATCH] docs(config): clarify default-order vs operation-order
 precedence

`api_platform.defaults.order` prepends its keys to any operation-level
`order` (via `array_merge($globalDefault, $operationOrder)`) rather than
acting as a fallback that yields to the operation. Correct the inaccurate
"overrides" claim in the existing paragraph and add a new section that
explains the merge semantics, shows a concrete example with resulting
ORDER BY, and documents the escape hatch (omit the global default and set
order per-operation, or replace OrderExtension).

Refs api-platform/core#8156 (documents intentional behaviour).
---
 core/default-order.md | 56 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 54 insertions(+), 2 deletions(-)

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:
 
 </code-selector>
 
-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.
 
 <code-selector>
 
@@ -163,3 +162,56 @@ App\ApiResource\Book:
 ```
 
 </code-selector>
+
+## 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
+<?php
+// api/src/ApiResource/Book.php
+namespace App\ApiResource;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\GetCollection;
+
+#[ApiResource(operations: [
+    new GetCollection(order: ['title' => '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`.