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] 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