From a36bef3db1a17e9da7deb96e1f2ffb8cc6ee428a Mon Sep 17 00:00:00 2001
From: soyuka <soyuka@users.noreply.github.com>
Date: Fri, 11 Sep 2026 23:23:12 +0200
Subject: [PATCH 1/3] docs(core): document HTTP QUERY operation

---
 core/operations.md | 120 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 120 insertions(+)

diff --git a/core/operations.md b/core/operations.md
index 6239007ca39..0f6ba92114f 100644
--- a/core/operations.md
+++ b/core/operations.md
@@ -48,6 +48,126 @@ Item operations:
 | `PATCH`  | no        | Apply a partial modification to an element | yes                   |
 | `DELETE` | no        | Delete an element                          | yes                   |
 
+## The HTTP QUERY Operation
+
+[HTTP QUERY](https://www.rfc-editor.org/rfc/rfc10008.html) is a safe, idempotent collection
+operation whose criteria are sent in the request body instead of the URI. It is useful when a
+collection query is too large or too structured for a URL. API Platform does not enable it by
+default; add a `Query` operation explicitly.
+
+Unlike `GET`, a `QUERY` request must include a `Content-Type` header, including when its body is
+empty. API Platform supports `application/json` and `application/x-www-form-urlencoded` request
+bodies for this operation.
+
+The following operation uses a parameter-driven filter. Although it is declared with
+`QueryParameter`, the `name` criterion is sent in the `QUERY` request body, not as
+`?name=...` in the URL:
+
+```php
+<?php
+// api/src/Entity/Book.php
+namespace App\Entity;
+
+use ApiPlatform\Doctrine\Orm\Filter\PartialSearchFilter;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\GetCollection;
+use ApiPlatform\Metadata\Query;
+use ApiPlatform\Metadata\QueryParameter;
+
+#[ApiResource(operations: [
+    new GetCollection(),
+    new Query(parameters: [
+        'name' => new QueryParameter(
+            filter: new PartialSearchFilter(),
+            property: 'name',
+        ),
+    ]),
+])]
+class Book
+{
+    // ...
+}
+```
+
+Call the `QUERY` operation with the same collection URI:
+
+```console
+curl -X QUERY https://example.com/books \
+    -H 'Accept: application/ld+json' \
+    -H 'Content-Type: application/json' \
+    --data '{"name":"Dune"}'
+```
+
+The parsed values are processed by the same [parameter and filter system](filters.md) as URL query
+parameters. This lets existing `QueryParameter` filters describe and apply body criteria without a
+custom provider.
+
+### Criteria DTOs
+
+For a structured query, set an `input` class on the operation and put `QueryParameter` attributes
+on its properties. API Platform uses that class as the request-body schema and discovers its
+parameters to apply their filters:
+
+```php
+<?php
+// api/src/Dto/BookCriteria.php
+namespace App\Dto;
+
+use ApiPlatform\Doctrine\Orm\Filter\PartialSearchFilter;
+use ApiPlatform\Metadata\QueryParameter;
+
+final class BookCriteria
+{
+    #[QueryParameter(filter: new PartialSearchFilter())]
+    public ?string $name = null;
+}
+```
+
+```php
+<?php
+// api/src/Entity/Book.php
+namespace App\Entity;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Query;
+use App\Dto\BookCriteria;
+
+#[ApiResource(operations: [new Query(input: BookCriteria::class)])]
+class Book
+{
+    // ...
+}
+```
+
+The input class is not deserialized and passed to a state provider by default. With the default
+`Query` settings, it documents the body and declares the filter criteria; providers continue to
+use the usual provider arguments and request context.
+
+When the query itself is a command-like operation and a processor needs a typed criteria object,
+disable the read stage and explicitly enable deserialization and writing. The processor then
+receives the deserialized `BookCriteria` object as its `$data` argument:
+
+```php
+new Query(
+    input: BookCriteria::class,
+    read: false,
+    deserialize: true,
+    write: true,
+    processor: BookCriteriaProcessor::class,
+)
+```
+
+This is the processor path: a processor is only called for a safe operation when `write` is set to
+`true`. See [State Processors](state-processors.md) for implementing the processor.
+
+### OpenAPI
+
+When exporting an OpenAPI 3.2 document, API Platform represents the operation in the Path Item
+Object's `query` field. Its request body lists `application/json` and
+`application/x-www-form-urlencoded`; parameter-driven criteria are represented as body properties.
+For an `input` criteria class, the request body references that class's input schema. Path and
+header parameters remain OpenAPI parameters.
+
 > [!NOTE] The `PATCH` method must be enabled explicitly in the configuration, refer to the
 > [Content Negotiation](content-negotiation.md) section for more information.
 

From df49398e29b19f85038f044f68fed683bbd162dc Mon Sep 17 00:00:00 2001
From: soyuka <soyuka@users.noreply.github.com>
Date: Sat, 12 Sep 2026 07:27:31 +0200
Subject: [PATCH 2/3] docs(core): add QUERY processor example

---
 core/operations.md | 69 ++++++++++++++++++++++++++++++++++++----------
 1 file changed, 55 insertions(+), 14 deletions(-)

diff --git a/core/operations.md b/core/operations.md
index 0f6ba92114f..c5c6edadede 100644
--- a/core/operations.md
+++ b/core/operations.md
@@ -60,8 +60,8 @@ empty. API Platform supports `application/json` and `application/x-www-form-urle
 bodies for this operation.
 
 The following operation uses a parameter-driven filter. Although it is declared with
-`QueryParameter`, the `name` criterion is sent in the `QUERY` request body, not as
-`?name=...` in the URL:
+`QueryParameter`, the `name` criterion is sent in the `QUERY` request body, not as `?name=...` in
+the URL:
 
 ```php
 <?php
@@ -104,9 +104,9 @@ custom provider.
 
 ### Criteria DTOs
 
-For a structured query, set an `input` class on the operation and put `QueryParameter` attributes
-on its properties. API Platform uses that class as the request-body schema and discovers its
-parameters to apply their filters:
+For a structured query, set an `input` class on the operation and put `QueryParameter` attributes on
+its properties. API Platform uses that class as the request-body schema and discovers its parameters
+to apply their filters:
 
 ```php
 <?php
@@ -140,21 +140,62 @@ class Book
 ```
 
 The input class is not deserialized and passed to a state provider by default. With the default
-`Query` settings, it documents the body and declares the filter criteria; providers continue to
-use the usual provider arguments and request context.
+`Query` settings, it documents the body and declares the filter criteria; providers continue to use
+the usual provider arguments and request context.
 
 When the query itself is a command-like operation and a processor needs a typed criteria object,
 disable the read stage and explicitly enable deserialization and writing. The processor then
 receives the deserialized `BookCriteria` object as its `$data` argument:
 
 ```php
-new Query(
-    input: BookCriteria::class,
-    read: false,
-    deserialize: true,
-    write: true,
-    processor: BookCriteriaProcessor::class,
-)
+<?php
+// api/src/Entity/Book.php
+namespace App\Entity;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Query;
+use App\Dto\BookCriteria;
+use App\State\BookCriteriaProcessor;
+
+#[ApiResource(operations: [
+    new Query(
+        input: BookCriteria::class,
+        read: false,
+        deserialize: true,
+        write: true,
+        processor: BookCriteriaProcessor::class,
+    ),
+])]
+class Book
+{
+    // ...
+}
+```
+
+```php
+<?php
+// api/src/State/BookCriteriaProcessor.php
+namespace App\State;
+
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\State\ProcessorInterface;
+use App\Dto\BookCriteria;
+use App\Entity\Book;
+
+/** @implements ProcessorInterface<BookCriteria, iterable<Book>> */
+final readonly class BookCriteriaProcessor implements ProcessorInterface
+{
+    public function __construct(private BookSearch $bookSearch) {}
+
+    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): iterable
+    {
+        if (!$data instanceof BookCriteria) {
+            throw new \LogicException('Expected BookCriteria.');
+        }
+
+        return $this->bookSearch->search($data);
+    }
+}
 ```
 
 This is the processor path: a processor is only called for a safe operation when `write` is set to

From ad479e94bcd18ff1c35554b7cd0db9db5bbac8a3 Mon Sep 17 00:00:00 2001
From: Antoine Bluchet <soyuka@users.noreply.github.com>
Date: Sat, 12 Sep 2026 07:33:53 +0200
Subject: [PATCH 3/3] Apply suggestion from @soyuka

---
 core/operations.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/core/operations.md b/core/operations.md
index c5c6edadede..780114e47f4 100644
--- a/core/operations.md
+++ b/core/operations.md
@@ -190,7 +190,7 @@ final readonly class BookCriteriaProcessor implements ProcessorInterface
     public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): iterable
     {
         if (!$data instanceof BookCriteria) {
-            throw new \LogicException('Expected BookCriteria.');
+            throw new \RutimeException('Expected BookCriteria.');
         }
 
         return $this->bookSearch->search($data);