This PR documents the new ExistFilter behavior proposed in the pull request api-platform/core#2243. (#613)

Author: epourail

core/configuration.md

@@ -116,10 +116,13 @@ api_platform:
         api_keys: []
 
     collection:
+        # The name of the query parameter to filter nullable results (with the ExistsFilter).
+        exists_parameter_name: 'exists'
+
         # The default order of results.
         order: 'ASC'
 
-        # The name of the query parameter to order results.
+        # The name of the query parameter to order results (with the OrderFilter).
         order_parameter_name: 'order'
 
         pagination:

core/filters.md

@@ -369,7 +369,9 @@ You can filter offers by joining two values, for example: `/offers?price[gt]=12.
 
 The exists filter allows you to select items based on nullable field value.
 
-Syntax: `?property[exists]=<true|false|1|0>`
+Syntax: `?exists[property]=<true|false|1|0>`
+
+Previous syntax (deprecated): `?property[exists]=<true|false|1|0>`
 
 Enable the filter:
 
@@ -393,10 +395,22 @@ class Offer
 }
 ```
 
-Given that the collection endpoint is `/offers`, you can filter offers on nullable field with the following query: `/offers?transportFees[exists]=true`.
+Given that the collection endpoint is `/offers`, you can filter offers on nullable field with the following query: `/offers?exists[transportFees]=true`.
 
 It will return all offers where `transportFees` is not `null`.
 
+#### Using a Custom Exists Query Parameter Name
+
+A conflict will occur if `exists` is also the name of a property with the search filter enabled.
+Luckily, the query parameter name to use is configurable:
+
+```yaml
+# api/config/packages/api_platform.yaml
+api_platform:
+    collection:
+        exists_parameter_name: 'not_null' # the URL query parameter to use is now "not_null"
+```
+
 ### Order Filter (Sorting)
 
 The order filter allows to sort a collection against the given properties.