docs(filters): promote QueryParameter usage over ApiFilter

The `ApiFilter` attribute is deprecated and scheduled for removal in API Platform 5.0. This commit updates the documentation to strongly recommend the modern `QueryParameter` syntax.

This new approach offers better flexibility and more explicit, per-operation filter configuration. The examples have been updated to reflect this best practice.

Author: vinceAmstoutz

core/doctrine-filters.md

@@ -3,7 +3,59 @@
 For further documentation on filters (including for Eloquent and Elasticsearch), please see the [Filters documentation](filters.md).
 
 > [!WARNING]
-> Prefer using QueryParameter instead of ApiFilter for more flexibility, this is subject to change in the next major version.
+> For maximum flexibility and to ensure future compatibility, it is strongly recommended to configure your filters via
+> the parameters attribute using `QueryParameter`. The legacy method using the `ApiFilter` attribute is **deprecated** and 
+> will be **removed** in version **5.0**.
+
+The modern way to declare filters is to associate them directly with an operation's parameters. This allows for more
+precise control over the exposed properties.
+
+Here is the recommended approach to apply a `PartialSearchFilter` only to the title and author properties of a Book resource.
+
+```php
+<?php
+// api/src/Resource/Book.php
+
+#[ApiResource(operations: [
+    new GetCollection(
+        parameters: [
+            // This WILL restrict to only title and author properties
+            'search[:property]' => new QueryParameter(
+                properties: ['title', 'author'], // Only these properties get parameters created
+                filter: new PartialSearchFilter()
+            )
+        ]
+    )
+])]
+class Book {
+    // ...
+}
+```
+> [!TIP]
+> This filter can be also defined directly on a specific operation like `#[GetCollection(...)])` for finer 
+> control, like the following code:
+
+```php
+<?php
+// api/src/Resource/Book.php
+#[GetCollection(
+    parameters: [
+        // This WILL restrict to only title and author properties
+        'search[:property]' => new QueryParameter(
+            properties: ['title', 'author'], // Only these properties get parameters created
+            filter: new PartialSearchFilter()
+        )
+    ]
+)]
+class Book {
+    // ...
+}
+```
+
+**Further Reading**
+
+- Consult the documentation on [Per-Parameter Filters (Recommended Method)](../core/filters.md#2-per-parameter-filters-recommended).
+- If you are working with a legacy codebase, you can refer to the [documentation for the old syntax (deprecated)](../core/filters.md#1-legacy-filters-searchfilter-etc---not-recommended).
 
 ## Basic Knowledge
 
@@ -112,7 +164,7 @@ class Offer
 }
 ```
 
-Learn more on how the [ApiFilter attribute](filters.md#apifilter-attribute) works.
+Learn more on how the [ApiFilter attribute](../core/filters.md#1-legacy-filters-searchfilter-etc---not-recommended) works.
 
 For the sake of consistency, we're using the attribute in the below documentation.
 

core/elasticsearch-filters.md

@@ -2,6 +2,60 @@
 
 For further documentation on filters (including for Eloquent and Doctrine), please see the [Filters documentation](filters.md).
 
+> [!WARNING]
+> For maximum flexibility and to ensure future compatibility, it is strongly recommended to configure your filters via
+> the parameters attribute using `QueryParameter`. The legacy method using the `ApiFilter` attribute is **deprecated** and
+> will be **removed** in version **5.0**.
+
+The modern way to declare filters is to associate them directly with an operation's parameters. This allows for more
+precise control over the exposed properties.
+
+Here is the recommended approach to apply a `MatchFilter` only to the title and author properties of a Book resource.
+
+```php
+<?php
+// api/src/Resource/Book.php
+#[ApiResource(operations: [
+    new GetCollection(
+        parameters: [
+            // This WILL restrict to only title and author properties
+            'search[:property]' => new QueryParameter(
+                properties: ['title', 'author'], // Only these properties get parameters created
+                filter: new MatchFilter()
+            )
+        ]
+    )
+])]
+class Book {
+    // ...
+}
+```
+> [!TIP]
+> This filter can be also defined directly on a specific operation like `#[GetCollection(...)])` for finer
+> control, like the following code:
+
+```php
+<?php
+// api/src/Resource/Book.php
+#[GetCollection(
+    parameters: [
+        // This WILL restrict to only title and author properties
+        'search[:property]' => new QueryParameter(
+            properties: ['title', 'author'], // Only these properties get parameters created
+            filter: new matchFilter()
+        )
+    ]
+)]
+class Book {
+    // ...
+}
+```
+
+**Further Reading**
+
+- Consult the documentation on [Per-Parameter Filters (Recommended Method)](../core/filters.md#2-per-parameter-filters-recommended).
+- If you are working with a legacy codebase, you can refer to the [documentation for the old syntax (deprecated)](../core/filters.md#1-legacy-filters-searchfilter-etc---not-recommended).
+
 ## Ordering Filter (Sorting)
 
 The order filter allows to [sort](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-sort.html)

core/filters.md

@@ -1,5 +1,10 @@
 # Parameters and Filters
 
+For documentation on the specific filter implementations available for your persistence layer, please refer to the following pages:
+
+- **[Doctrine Filters](../core/doctrine-filters.md)**
+- **[Elasticsearch Filters](../core/elasticsearch-filters.md)**
+
 API Platform provides a generic and powerful system to apply filters, sort criteria, and handle other request parameters. This system is primarily managed through **Parameter attributes** (`#[QueryParameter]` and `#[HeaderParameter]`), which allow for detailed and explicit configuration of how an API consumer can interact with a resource.
 
 These parameters can be linked to **Filters**, which are classes that contain the logic for applying criteria to your persistence backend (like Doctrine ORM or MongoDB ODM).
@@ -8,10 +13,10 @@ You can declare parameters on a resource class to apply them to all operations,
 
 <p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform/filters?cid=apip"><img src="../symfony/images/symfonycasts-player.png" alt="Filtering and Searching screencast"><br>Watch the Filtering & Searching screencast</a></p>
 
-For documentation on the specific filter implementations available for your persistence layer, please refer to the following pages:
-
-* [Doctrine Filters](../core/doctrine-filters.md)
-* [Elasticsearch Filters](../core/elasticsearch-filters.md)
+> [!WARNING]
+> For maximum flexibility and to ensure future compatibility, it is strongly recommended to configure your filters via
+> the parameters attribute using `QueryParameter`. The legacy method using the `ApiFilter` attribute is **deprecated** and
+> will be **removed** in version **5.0**.
 
 ## Declaring Parameters