docs(filters): create dedicated file for elasticsearch filters & reorganize

docs: apply review

fix: move title from h3 to h2

Co-authored-by: Kévin Dunglas <kevin@dunglas.fr>

fix: using and instead of &

Co-authored-by: Kévin Dunglas <kevin@dunglas.fr>

docs(filters): create dedicated file for elasticsearch filters & reorganize

docs(filters): create dedicated file for doctrine filters & links

Author: vinceAmstoutz

core/doctrine-filters.md

@@ -0,0 +1,267 @@
+# Doctrine Filters
+
+For further documentation on filters (including for Eloquent and Elasticsearch), please see the [Filters documentation](filters.md).
+
+## Using Doctrine ORM Filters
+
+Doctrine ORM features [a filter system](https://www.doctrine-project.org/projects/doctrine-orm/en/latest/reference/filters.html) that allows the developer to add SQL to the conditional clauses of queries, regardless of the place where the SQL is generated (e.g. from a DQL query, or by loading associated entities).
+These are applied to collections and items and therefore are incredibly useful.
+
+The following information, specific to Doctrine filters in Symfony, is based upon [a great article posted on Michaël Perrin's blog](https://www.michaelperrin.fr/blog/2014/12/doctrine-filters).
+
+Suppose we have a `User` entity and an `Order` entity related to the `User` one. A user should only see his orders and no one else's.
+
+```php
+<?php
+// api/src/Entity/User.php
+namespace App\Entity;
+
+use ApiPlatform\Metadata\ApiResource;
+
+#[ApiResource]
+class User
+{
+    // ...
+}
+```
+
+```php
+<?php
+// api/src/Entity/Order.php
+namespace App\Entity;
+
+use ApiPlatform\Metadata\ApiResource;
+use Doctrine\ORM\Mapping as ORM;
+
+#[ApiResource]
+class Order
+{
+    // ...
+
+    #[ORM\ManyToOne(User::class)]
+    #[ORM\JoinColumn(name: 'user_id', referencedColumnName: 'id')]
+    public User $user;
+
+    // ...
+}
+```
+
+The whole idea is that any query on the order table should add a `WHERE user_id = :user_id` condition.
+
+Start by creating a custom attribute to mark restricted entities:
+
+```php
+<?php
+// api/src/Attribute/UserAware.php
+
+namespace App\Attribute;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+final class UserAware
+{
+    public $userFieldName;
+}
+```
+
+Then, let's mark the `Order` entity as a "user aware" entity.
+
+```php
+<?php
+// api/src/Entity/Order.php
+namespace App\Entity;
+
+use App\Attribute\UserAware;
+
+#[UserAware(userFieldName: "user_id")]
+class Order {
+    // ...
+}
+```
+
+Now, create a Doctrine filter class:
+
+```php
+<?php
+// api/src/Filter/UserFilter.php
+
+namespace App\Filter;
+
+use App\Attribute\UserAware;
+use Doctrine\ORM\Mapping\ClassMetadata;
+use Doctrine\ORM\Query\Filter\SQLFilter;
+
+final class UserFilter extends SQLFilter
+{
+    public function addFilterConstraint(ClassMetadata $targetEntity, $targetTableAlias): string
+    {
+        // The Doctrine filter is called for any query on any entity
+        // Check if the current entity is "user aware" (marked with an attribute)
+        $userAware = $targetEntity->getReflectionClass()->getAttributes(UserAware::class)[0] ?? null;
+
+        $fieldName = $userAware?->getArguments()['userFieldName'] ?? null;
+        if ($fieldName === '' || is_null($fieldName)) {
+            return '';
+        }
+
+        try {
+            // Don't worry, getParameter automatically escapes parameters
+            $userId = $this->getParameter('id');
+        } catch (\InvalidArgumentException $e) {
+            // No user ID has been defined
+            return '';
+        }
+
+        if (empty($fieldName) || empty($userId)) {
+            return '';
+        }
+
+        return sprintf('%s.%s = %s', $targetTableAlias, $fieldName, $userId);
+    }
+}
+```
+
+Now, we must configure the Doctrine filter.
+
+```yaml
+# api/config/packages/api_platform.yaml
+doctrine:
+  orm:
+    filters:
+      user_filter:
+        class: App\Filter\UserFilter
+        enabled: true
+```
+
+Done: Doctrine will automatically filter all `UserAware`entities!
+
+## ApiFilter Attribute
+
+The attribute can be used on a `property` or on a `class`.
+
+If the attribute is given over a property, the filter will be configured on the property. For example, let's add a search filter on `name` and on the `prop` property of the `colors` relation:
+
+```php
+<?php
+// api/src/Entity/DummyCar.php
+namespace App\Entity;
+
+use ApiPlatform\Metadata\ApiFilter;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
+use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Collections\Collection;
+use Doctrine\ORM\Mapping as ORM;
+use App\Entity\DummyCarColor;
+
+#[ApiResource]
+class DummyCar
+{
+    #[ORM\Id, ORM\Column, ORM\GeneratedValue]
+    private ?int $id = null;
+
+    #[ORM\Column]
+    #[ApiFilter(SearchFilter::class, strategy: 'partial')]
+    public ?string $name = null;
+
+    #[ORM\OneToMany(mappedBy: "car", targetEntity: DummyCarColor::class)]
+    #[ApiFilter(SearchFilter::class, properties: ['colors.prop' => 'ipartial'])]
+    public Collection $colors;
+
+    public function __construct()
+    {
+        $this->colors = new ArrayCollection();
+    }
+
+    // ...
+}
+```
+
+On the first property, `name`, it's straightforward. The first attribute argument is the filter class, the second specifies options, here, the strategy:
+
+```php
+#[ApiFilter(SearchFilter::class, strategy: 'partial')]
+```
+
+In the second attribute, we specify `properties` to which the filter should apply. It's necessary here because we don't want to filter `colors` but the `prop` property of the `colors` association.
+Note that for each given property we specify the strategy:
+
+```php
+#[ApiFilter(SearchFilter::class, properties: ['colors.prop' => 'ipartial'])]
+```
+
+The `ApiFilter` attribute can be set on the class as well. If you don't specify any properties, it'll act on every property of the class.
+
+For example, let's define three data filters (`DateFilter`, `SearchFilter` and `BooleanFilter`) and two serialization filters (`PropertyFilter` and `GroupFilter`) on our `DummyCar` class:
+
+```php
+<?php
+// api/src/Entity/DummyCar.php
+namespace App\Entity;
+
+use ApiPlatform\Metadata\ApiFilter;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Doctrine\Orm\Filter\BooleanFilter;
+use ApiPlatform\Doctrine\Orm\Filter\DateFilter;
+use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
+use ApiPlatform\Serializer\Filter\GroupFilter;
+use ApiPlatform\Serializer\Filter\PropertyFilter;
+use Doctrine\ORM\Mapping as ORM;
+
+#[ApiResource]
+#[ApiFilter(BooleanFilter::class)]
+#[ApiFilter(DateFilter::class, strategy: DateFilter::EXCLUDE_NULL)]
+#[ApiFilter(SearchFilter::class, properties: ['colors.prop' => 'ipartial', 'name' => 'partial'])]
+#[ApiFilter(PropertyFilter::class, arguments: ['parameterName' => 'foobar'])]
+#[ApiFilter(GroupFilter::class, arguments: ['parameterName' => 'foobargroups'])]
+class DummyCar
+{
+    // ...
+}
+
+```
+
+### BooleanFilter
+
+The `BooleanFilter` is applied to every `Boolean` property of the class. Indeed, in each core filter, we check the Doctrine type. It's written only by using the filter class:
+
+```php
+#[ApiFilter(BooleanFilter::class)]
+```
+
+### DateFilter
+
+The `DateFilter` given here will be applied to every `Date` property of the `DummyCar` class with the `DateFilter::EXCLUDE_NULL` strategy:
+
+```php
+#[ApiFilter(DateFilter::class, strategy: DateFilter::EXCLUDE_NULL)]
+```
+
+### SearchFilter
+
+The `SearchFilter` here adds properties. The result is the exact same as the example with attributes on properties:
+
+```php
+#[ApiFilter(SearchFilter::class, properties: ['colors.prop' => 'ipartial', 'name' => 'partial'])]
+```
+
+### Filters properties, PropertyFilter &  GroupFilter
+
+Note that you can specify the `properties` argument on every filter.
+
+The next filters are not related to how the data is fetched but rather to how the serialization is done on those. We can give an `arguments` option ([see here for the available arguments](filters.md#serializer-filters)):
+
+```php
+#[ApiFilter(PropertyFilter::class, arguments: ['parameterName' => 'foobar'])]
+#[ApiFilter(GroupFilter::class, arguments: ['parameterName' => 'foobargroups'])]
+```
+
+## Creating Custom Doctrine MongoDB ODM Filters
+
+Doctrine MongoDB ODM filters have access to the context created from the HTTP request and to the [aggregation builder](https://www.doctrine-project.org/projects/doctrine-mongodb-odm/en/latest/reference/aggregation-builder.html)
+instance used to retrieve data from the database and to execute [complex operations on data](https://docs.mongodb.com/manual/aggregation/).
+They are only applied to collections. If you want to deal with the aggregation pipeline generated to retrieve items, [extensions](extensions.md) are the way to go.
+
+A Doctrine MongoDB ODM filter is basically a class implementing the `ApiPlatform\Doctrine\Odm\Filter\FilterInterface`.
+API Platform includes a convenient abstract class implementing this interface and providing utility methods: `ApiPlatform\Doctrine\Odm\Filter\AbstractFilter`.