From fa1929e6315a1f4d974c1e12e2691626b2ac6fd4 Mon Sep 17 00:00:00 2001
From: Maxcastel <maxence.nord@gmail.com>
Date: Mon, 30 Mar 2026 15:53:25 +0200
Subject: [PATCH 1/2] feat: allow Parameter attributes on properties

---
 core/filters.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/core/filters.md b/core/filters.md
index 499022ddad1..b603cde6368 100644
--- a/core/filters.md
+++ b/core/filters.md
@@ -199,6 +199,35 @@ This configuration allows clients to filter events by date ranges using queries
 - `/events?date[startDate][after]=2023-01-01`
 - `/events?date[endDate][before]=2023-12-31`
 
+### Declaring Parameters on Properties
+
+You can also declare parameters directly on entity properties using `#[QueryParameter]` or
+`#[HeaderParameter]` attributes. This keeps your parameter definition close to the property it
+affects:
+
+```php
+<?php
+// api/src/Entity/Book.php
+namespace App\Entity;
+
+use ApiPlatform\Doctrine\Orm\Filter\PartialSearchFilter;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\HeaderParameter;
+use ApiPlatform\Metadata\QueryParameter;
+
+#[ApiResource]
+class Book
+{
+    #[QueryParameter(key: 'search', filter: new PartialSearchFilter())]
+    private string $title = '';
+
+    #[HeaderParameter(key: 'API-Key', description: 'API authentication key')]
+    public string $apiKey = '';
+}
+```
+
+Parameters declared on properties are automatically applied to all operations on the resource.
+
 ### Filtering a Single Property
 
 Most of the time, a parameter maps directly to a property on your resource. For example, a

From 920466452067cb0275587ad72dca3b407d8aa94d Mon Sep 17 00:00:00 2001
From: Maxcastel <maxence.nord@gmail.com>
Date: Tue, 31 Mar 2026 16:46:35 +0200
Subject: [PATCH 2/2] feat: allow restricting operations for parameter
 attributes on properties

---
 core/filters.md | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/core/filters.md b/core/filters.md
index b603cde6368..612a1231943 100644
--- a/core/filters.md
+++ b/core/filters.md
@@ -212,21 +212,36 @@ namespace App\Entity;
 
 use ApiPlatform\Doctrine\Orm\Filter\PartialSearchFilter;
 use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\GetCollection;
 use ApiPlatform\Metadata\HeaderParameter;
+use ApiPlatform\Metadata\Patch;
 use ApiPlatform\Metadata\QueryParameter;
 
-#[ApiResource]
+#[ApiResource(
+    operations: [
+        new GetCollection(),
+        new Get(),
+    ],
+)]
 class Book
 {
+    // Applies to all operations
     #[QueryParameter(key: 'search', filter: new PartialSearchFilter())]
     private string $title = '';
 
-    #[HeaderParameter(key: 'API-Key', description: 'API authentication key')]
-    public string $apiKey = '';
+    // Applies only to GetCollection
+    #[QueryParameter(key: 'name', filter: new PartialSearchFilter(), operations: [new GetCollection()])]
+    public string $name = '';
+
+    // Applies only to GetCollection (Patch is not in the list of operations)
+    #[HeaderParameter(key: 'X-Authorization', operations: [new GetCollection(), new Patch()])]
+    public string $authToken = '';
 }
 ```
 
-Parameters declared on properties are automatically applied to all operations on the resource.
+Parameters declared on properties are automatically applied to all operations on the resource. You
+can restrict a parameter to specific operations using the `operations` argument.
 
 ### Filtering a Single Property