docs: 4.4 release gaps (HTTP QUERY, ItemDenormalizer, legacy filters) (#2341)

Author: soyuka

admin/handling-relations.md

@@ -313,22 +313,25 @@ class Review
 // api/src/Entity/Book.php
 namespace App\Entity;
 
-use ApiPlatform\Metadata\ApiFilter;
+use ApiPlatform\Doctrine\Orm\Filter\PartialSearchFilter;
 use ApiPlatform\Metadata\ApiResource;
-use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
+use ApiPlatform\Metadata\QueryParameter;
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\Common\Collections\Collection;
 use Doctrine\ORM\Mapping as ORM;
 
 #[ORM\Entity]
-#[ApiResource]
+#[ApiResource(
+    parameters: [
+        'title' => new QueryParameter(filter: new PartialSearchFilter()),
+    ]
+)]
 class Book
 {
     #[ORM\Id, ORM\Column, ORM\GeneratedValue]
     public ?int $id = null;
 
     #[ORM\Column]
-    #[ApiFilter(SearchFilter::class, strategy: 'ipartial')]
     public string $title;
 
     #[ORM\OneToMany(targetEntity: Review::class, mappedBy: 'book')]
@@ -341,8 +344,8 @@ class Book
 }
 ```
 
-Notice the "partial search" [filter](../core/filters.md) on the `title` property of the `Book`
-resource class.
+Notice the [`PartialSearchFilter`](../core/filters.md#list-of-available-filters) on the `title`
+property of the `Book` resource class.
 
 Now, let's configure API Platform Admin to enable autocompletion for the book selector. We will
 leverage the [`<ReferenceInput>`](https://marmelab.com/react-admin/ReferenceInput.html) and

admin/performance.md

@@ -4,43 +4,45 @@ To make the admin faster and greener, you can make some changes to your API.
 
 ## Retrieve All Relations in One Request
 
-By default, if your relations are not embedded and if you decide to display some fields belonging to
-relations in your resource list, the admin will fetch the relations one by one.
+Some of your relations are not embedded. You display some of their fields in your resource list. By
+default, the admin fetches these relations one by one.
 
 In this case, it can be improved by doing only one request for all the related resources instead.
 
-To do so, you need to make sure the [search filter](../core/doctrine-filters.md#search-filter) is
+To do so, you need to make sure the [`ExactFilter`](../core/doctrine-filters.md#exact-filter) is
 enabled for the identifier of the related resource.
 
-For instance, if you have a `book` resource having a relation to `author` resources and you display
-the author names on your book list, you can make sure the authors are retrieved in one go by
-writing:
+For instance, say you have a `book` resource with a relation to `author` resources, and you display
+the author names on your book list. Retrieve the authors in one go by writing:
 
 ```php
 <?php
 // api/src/Entity/Author.php
 namespace App\Entity;
 
-use ApiPlatform\Metadata\ApiFilter;
-use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
+use ApiPlatform\Doctrine\Orm\Filter\ExactFilter;
 use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\QueryParameter;
 use Doctrine\ORM\Mapping as ORM;
 
 #[ORM\Entity]
-#[ApiResource]
+#[ApiResource(
+    parameters: [
+        'id' => new QueryParameter(filter: new ExactFilter()),
+    ]
+)]
 class Author
 {
     #[ORM\Id, ORM\Column, ORM\GeneratedValue]
-    #[ApiFilter(SearchFilter::class, strategy: "exact")]
     public ?int $id = null;
 
     #[ORM\Column]
     public string $name;
 }
 ```
 
-Instead of issuing a separate request for each author, the admin will now fetch all the authors in
-one go, with a request similar to the following:
+The admin now fetches all the authors in one go, instead of issuing a separate request for each
+author. The request looks similar to the following:
 
 ```txt
 https://localhost/authors?

admin/schema.md

@@ -1,20 +1,20 @@
 # Customizing the Schema
 
 Both [`HydraAdmin`](./components.md#hydraadmin) and [`OpenApiAdmin`](./components.md#openapiadmin)
-leverage introspection of the API schema to discover its capabilities, like **filtering** and
+use introspection of the API schema to discover its capabilities, like **filtering** and
 **sorting**.
 
-They also detect wether the API has real-time capabilities using [Mercure](./real-time-mercure.md),
-and automatically enable it if it does.
+They also detect whether the API has real-time capabilities through
+[Mercure](./real-time-mercure.md). When it does, Admin enables real-time updates automatically.
 
-Lastly, API Platform Admin has native support for the popular
-[Schema.org](./schema.md#about-schemaorg) vocabulary, which enables it to automatically use the
-field type matching your data, or display a related resource's name instead of its IRI.
+API Platform Admin also has native support for the popular [Schema.org](./schema.md#about-schemaorg)
+vocabulary. This support lets it automatically use the field type matching your data, or display a
+related resource's name instead of its IRI.
 
 ## Adding Filtering Capabilities
 
-You can add the [`ApiFilter` attribute](../core/filters.md#apifilter-attribute) to an API Platform
-resource to configure a filter on a property.
+You can use the [`QueryParameter` attribute](../core/filters.md#declaring-parameters) on an API
+Platform resource to configure a filter on a property.
 
 For instance, here is how configure filtering on the `id`, `title` and `author` properties of a
 `Book` resource:
@@ -24,18 +24,20 @@ For instance, here is how configure filtering on the `id`, `title` and `author`
 // api/src/Entity/Book.php
 namespace App\Entity;
 
-use ApiPlatform\Metadata\ApiFilter;
+use ApiPlatform\Doctrine\Orm\Filter\ExactFilter;
+use ApiPlatform\Doctrine\Orm\Filter\PartialSearchFilter;
 use ApiPlatform\Metadata\ApiResource;
-use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
+use ApiPlatform\Metadata\QueryParameter;
 use Doctrine\ORM\Mapping as ORM;
 
-#[ApiResource]
+#[ApiResource(
+    parameters: [
+        'id' => new QueryParameter(filter: new ExactFilter()),
+        'title' => new QueryParameter(filter: new PartialSearchFilter()),
+        'author' => new QueryParameter(filter: new PartialSearchFilter()),
+    ]
+)]
 #[ORM\Entity]
-#[ApiFilter(SearchFilter::class, properties: [
-    'id' => 'exact',
-    'title' => 'ipartial',
-    'author' => 'ipartial'
-])]
 class Book
 {
     // ...
@@ -47,12 +49,12 @@ filter on the selected properties.
 
 ![Filtering on the title property](./images/admin-filter.png)
 
-**Tip:** Learn more about the [`ApiFilter` attribute](../core/filters.md#apifilter-attribute) in the
-core documentation.
+**Tip:** Learn more about the [available filters](../core/filters.md#list-of-available-filters) in
+the core documentation.
 
 ## Adding Sorting Capabilities
 
-You can also use the [`ApiFilter` attribute](../core/filters.md#apifilter-attribute) on an API
+You can also use the [`QueryParameter` attribute](../core/filters.md#declaring-parameters) on an API
 Plaform resource to configure sorting.
 
 For instance, here is how to configure sorting on the `id`, `isbn`, `title`, `author` and
@@ -63,20 +65,24 @@ For instance, here is how to configure sorting on the `id`, `isbn`, `title`, `au
 // api/src/Entity/Book.php
 namespace App\Entity;
 
-use ApiPlatform\Metadata\ApiFilter;
+use ApiPlatform\Doctrine\Orm\Filter\SortFilter;
 use ApiPlatform\Metadata\ApiResource;
-use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
+use ApiPlatform\Metadata\QueryParameter;
 use Doctrine\ORM\Mapping as ORM;
 
-#[ApiResource]
+#[ApiResource(
+    parameters: [
+        'order' => new QueryParameter(filter: new SortFilter(), property: 'id'),
+        'orderIsbn' => new QueryParameter(filter: new SortFilter(), property: 'isbn'),
+        'orderTitle' => new QueryParameter(filter: new SortFilter(), property: 'title'),
+        'orderAuthor' => new QueryParameter(filter: new SortFilter(), property: 'author'),
+        'orderPublicationDate' => new QueryParameter(
+            filter: new SortFilter(),
+            property: 'publicationDate'
+        ),
+    ]
+)]
 #[ORM\Entity]
-#[ApiFilter(OrderFilter::class, properties: [
-    'id' => 'ASC',
-    'isbn' => 'ASC',
-    'title' => 'ASC',
-    'author' => 'ASC',
-    'publicationDate' => 'DESC'
-])]
 class Book
 {
     // ...
@@ -88,7 +94,7 @@ selected columns sortable.
 
 ![Sorting by the title property](./images/admin-sort.png)
 
-**Tip:** Learn more about the [`ApiFilter` attribute](../core/filters.md#apifilter-attribute) in the
+**Tip:** Learn more about the [`SortFilter`](../core/filters.md#list-of-available-filters) in the
 core documentation.
 
 ## Enabling Real-Time Updates
@@ -122,19 +128,19 @@ API Platform Admin has native support for the popular [Schema.org](https://schem
 > Schema.org is a collaborative, community activity with a mission to create, maintain, and promote
 > schemas for structured data on the Internet, on web pages, in email messages, and beyond.
 
-To leverage this capability, your API must use the JSON-LD format and the appropriate Schema.org
-types. The following examples will use [API Platform Core](../core/) to create such API, but keep in
-mind that this feature will work with any JSON-LD API using the Schema.org vocabulary, regardless of
-the used web framework or programming language.
+To use this capability, your API must use the JSON-LD format and the appropriate Schema.org types.
+The following examples use [API Platform Core](../core/) to create such an API. This feature works
+with any JSON-LD API that uses the Schema.org vocabulary, regardless of the web framework or
+programming language.
 
 ## Displaying Related Resource's Name Instead of its IRI
 
 By default, IRIs of related objects are displayed in lists and forms. However, it is often more
 user-friendly to display a string representation of the resource (such as its name) instead of its
 ID.
 
-To configure which property should be shown to represent your entity, map the property containing
-the name of the object with the `https://schema.org/name` type:
+To configure which property represents your entity, map the property that holds the name of the
+object with the `https://schema.org/name` type:
 
 ```php
 // api/src/Entity/Person.php

core/graphql.md

@@ -1201,14 +1201,20 @@ instead of the dot (`.`) syntax, e.g.:
 // api/src/Entity/Offer.php
 namespace App\Entity;
 
-use ApiPlatform\Metadata\ApiFilter;
+use ApiPlatform\Doctrine\Orm\Filter\ExactFilter;
+use ApiPlatform\Doctrine\Orm\Filter\SortFilter;
 use ApiPlatform\Metadata\ApiResource;
-use ApiPlatform\Doctrine\Orm\Filter\OrderFilter;
-use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
+use ApiPlatform\Metadata\QueryParameter;
 
-#[ApiResource]
-#[ApiFilter(OrderFilter::class, properties: ['product.releaseDate'])]
-#[ApiFilter(SearchFilter::class, properties: ['product.color' => 'exact'])]
+#[ApiResource(
+    parameters: [
+        'product_releaseDate' => new QueryParameter(
+            filter: new SortFilter(),
+            property: 'product.releaseDate'
+        ),
+        'product_color' => new QueryParameter(filter: new ExactFilter(), property: 'product.color'),
+    ]
+)]
 class Offer
 {
     // ...
@@ -1238,7 +1244,7 @@ Or order your results like:
 
 ```graphql
 {
-    offers(order: [{ product_releaseDate: "DESC" }]) {
+    offers(product_releaseDate: "DESC") {
         edges {
             node {
                 id
@@ -2482,12 +2488,15 @@ For instance, your resource can have properties in camelCase:
 // api/src/Entity/Book.php
 namespace App\Entity;
 
+use ApiPlatform\Doctrine\Orm\Filter\PartialSearchFilter;
 use ApiPlatform\Metadata\ApiResource;
-use ApiPlatform\Metadata\ApiFilter;
-use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
+use ApiPlatform\Metadata\QueryParameter;
 
-#[ApiResource]
-#[ApiFilter(SearchFilter::class, properties: ['publicationDate' => 'partial'])]
+#[ApiResource(
+    parameters: [
+        'publicationDate' => new QueryParameter(filter: new PartialSearchFilter()),
+    ]
+)]
 class Book
 {
     // ...
@@ -2498,7 +2507,7 @@ class Book
 }
 ```
 
-By default, with the search filter, the query to retrieve a collection will be:
+By default, with the partial search filter, the query to retrieve a collection will be:
 
 ```graphql
 {
@@ -2531,19 +2540,28 @@ But if you use the `CamelCaseToSnakeCaseNameConverter`, it will be:
 If you use snake_case, you can wonder how to make the difference between an underscore and the
 separator of the nested fields in the filter names, by default an underscore too.
 
+API Platform builds the GraphQL argument name from the parameter key. It replaces the dot in that
+key with the nesting separator.
+
 For instance if you have this resource:
 
 ```php
 <?php
 // api/src/Entity/Book.php
 namespace App\Entity;
 
+use ApiPlatform\Doctrine\Orm\Filter\ExactFilter;
 use ApiPlatform\Metadata\ApiResource;
-use ApiPlatform\Metadata\ApiFilter;
-use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
+use ApiPlatform\Metadata\QueryParameter;
 
-#[ApiResource]
-#[ApiFilter(SearchFilter::class, properties: ['relatedBooks.title' => 'exact'])]
+#[ApiResource(
+    parameters: [
+        'related_books.title' => new QueryParameter(
+            filter: new ExactFilter(),
+            property: 'relatedBooks.title'
+        ),
+    ]
+)]
 class Book
 {
     // ...
@@ -2557,7 +2575,7 @@ class Book
 }
 ```
 
-You would need to use the search filter like this:
+You would then query the filter like this:
 
 ```graphql
 {