Skip to content

Commit 61e86ce

Browse files
mremimremi
committed
feat(filter): add new Doctrine filter BackedEnumFilter for filtering an entity using PHP backed enum, resolves #6506 
1 parent 03357fb commit 61e86ce

File tree

9 files changed

+471
-1
lines changed

9 files changed

+471
-1
lines changed

‎src/Doctrine/Common/Filter/BackedEnumFilterTrait.php

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the API Platform project.
5+
*
6+
* (c) Kévin Dunglas <[email protected]>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
declare(strict_types=1);
13+
14+
namespace ApiPlatform\Doctrine\Common\Filter;
15+
16+
use ApiPlatform\Doctrine\Common\PropertyHelperTrait;
17+
use ApiPlatform\Metadata\Exception\InvalidArgumentException;
18+
use Psr\Log\LoggerInterface;
19+
20+
/**
21+
* Trait for filtering the collection by backed enum values.
22+
*
23+
* Filters collection on equality of backed enum properties.
24+
*
25+
* For each property passed, if the resource does not have such property or if
26+
* the value is not one of cases the property is ignored.
27+
*
28+
* @author Rémi Marseille <[email protected]>
29+
*/
30+
trait BackedEnumFilterTrait
31+
{
32+
use PropertyHelperTrait;
33+
34+
/**
35+
* @var array<string, string>
36+
*/
37+
private array $enumTypes;
38+
39+
/**
40+
* {@inheritdoc}
41+
*/
42+
public function getDescription(string $resourceClass): array
43+
{
44+
$description = [];
45+
46+
$properties = $this->getProperties();
47+
if (null === $properties) {
48+
$properties = array_fill_keys($this->getClassMetadata($resourceClass)->getFieldNames(), null);
49+
}
50+
51+
foreach ($properties as $property => $unused) {
52+
if (!$this->isPropertyMapped($property, $resourceClass) || !$this->isBackedEnumField($property, $resourceClass)) {
53+
continue;
54+
}
55+
$propertyName = $this->normalizePropertyName($property);
56+
$description[$propertyName] = [
57+
'property' => $propertyName,
58+
'type' => 'string',
59+
'required' => false,
60+
'schema' => [
61+
'type' => 'string',
62+
'enum' => array_map(fn (\BackedEnum $case) => $case->value, $this->enumTypes[$property]::cases()),
63+
],
64+
];
65+
}
66+
67+
return $description;
68+
}
69+
70+
abstract protected function getProperties(): ?array;
71+
72+
abstract protected function getLogger(): LoggerInterface;
73+
74+
abstract protected function normalizePropertyName(string $property): string;
75+
76+
/**
77+
* Determines whether the given property refers to a backed enum field.
78+
*/
79+
abstract protected function isBackedEnumField(string $property, string $resourceClass): bool;
80+
81+
private function normalizeValue($value, string $property): mixed
82+
{
83+
if (false !== array_search($value, array_map(fn (\BackedEnum $case) => $case->value, $this->enumTypes[$property]::cases()), true)) {
84+
return $value;
85+
}
86+
87+
$this->getLogger()->notice('Invalid filter ignored', [
88+
'exception' => new InvalidArgumentException(sprintf('Invalid backed enum value for "%s" property, expected one of ( "%s" )',
89+
$property,
90+
implode('" | "', array_map(fn (\BackedEnum $case) => $case->value, $this->enumTypes[$property]::cases())))
91+
),
92+
]);
93+
94+
return null;
95+
}
96+
}

‎src/Doctrine/Orm/Filter/BackedEnumFilter.php

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the API Platform project.
5+
*
6+
* (c) Kévin Dunglas <[email protected]>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
declare(strict_types=1);
13+
14+
namespace ApiPlatform\Doctrine\Orm\Filter;
15+
16+
use ApiPlatform\Doctrine\Common\Filter\BackedEnumFilterTrait;
17+
use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
18+
use ApiPlatform\Metadata\Operation;
19+
use Doctrine\DBAL\Types\Types;
20+
use Doctrine\ORM\Mapping\ClassMetadata;
21+
use Doctrine\ORM\Mapping\FieldMapping;
22+
use Doctrine\ORM\Query\Expr\Join;
23+
use Doctrine\ORM\QueryBuilder;
24+
25+
/**
26+
* The backed enum filter allows you to search on backed enum fields and values.
27+
*
28+
* Note: it is possible to filter on properties and relations too.
29+
*
30+
* Syntax: `?property=foo`.
31+
*
32+
* <div data-code-selector>
33+
*
34+
* ```php
35+
* <?php
36+
* // api/src/Entity/Book.php
37+
* use ApiPlatform\Metadata\ApiFilter;
38+
* use ApiPlatform\Metadata\ApiResource;
39+
* use ApiPlatform\Doctrine\Orm\Filter\BackedEnumFilter;
40+
*
41+
* #[ApiResource]
42+
* #[ApiFilter(BackedEnumFilter::class, properties: ['status'])]
43+
* class Book
44+
* {
45+
* // ...
46+
* }
47+
* ```
48+
*
49+
* ```yaml
50+
* # config/services.yaml
51+
* services:
52+
* book.backed_enum_filter:
53+
* parent: 'api_platform.doctrine.orm.backed_enum_filter'
54+
* arguments: [ { status: ~ } ]
55+
* tags: [ 'api_platform.filter' ]
56+
* # The following are mandatory only if a _defaults section is defined with inverted values.
57+
* # You may want to isolate filters in a dedicated file to avoid adding the following lines (by adding them in the defaults section)
58+
* autowire: false
59+
* autoconfigure: false
60+
* public: false
61+
*
62+
* # api/config/api_platform/resources.yaml
63+
* resources:
64+
* App\Entity\Book:
65+
* - operations:
66+
* ApiPlatform\Metadata\GetCollection:
67+
* filters: ['book.backed_enum_filter']
68+
* ```
69+
*
70+
* ```xml
71+
* <?xml version="1.0" encoding="UTF-8" ?>
72+
* <!-- api/config/services.xml -->
73+
* <?xml version="1.0" encoding="UTF-8" ?>
74+
* <container
75+
* xmlns="http://symfony.com/schema/dic/services"
76+
* xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
77+
* xsi:schemaLocation="http://symfony.com/schema/dic/services
78+
* https://symfony.com/schema/dic/services/services-1.0.xsd">
79+
* <services>
80+
* <service id="book.backed_enum_filter" parent="api_platform.doctrine.orm.backed_enum_filter">
81+
* <argument type="collection">
82+
* <argument key="status"/>
83+
* </argument>
84+
* <tag name="api_platform.filter"/>
85+
* </service>
86+
* </services>
87+
* </container>
88+
* <!-- api/config/api_platform/resources.xml -->
89+
* <resources
90+
* xmlns="https://api-platform.com/schema/metadata/resources-3.0"
91+
* xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
92+
* xsi:schemaLocation="https://api-platform.com/schema/metadata/resources-3.0
93+
* https://api-platform.com/schema/metadata/resources-3.0.xsd">
94+
* <resource class="App\Entity\Book">
95+
* <operations>
96+
* <operation class="ApiPlatform\Metadata\GetCollection">
97+
* <filters>
98+
* <filter>book.backed_enum_filter</filter>
99+
* </filters>
100+
* </operation>
101+
* </operations>
102+
* </resource>
103+
* </resources>
104+
* ```
105+
*
106+
* </div>
107+
*
108+
* Given that the collection endpoint is `/books`, you can filter books with the following query: `/books?status=published`.
109+
*
110+
* @author Rémi Marseille <[email protected]>
111+
*/
112+
final class BackedEnumFilter extends AbstractFilter
113+
{
114+
use BackedEnumFilterTrait;
115+
116+
/**
117+
* {@inheritdoc}
118+
*/
119+
protected function filterProperty(string $property, mixed $value, QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, ?Operation $operation = null, array $context = []): void
120+
{
121+
if (
122+
!$this->isPropertyEnabled($property, $resourceClass)
123+
|| !$this->isPropertyMapped($property, $resourceClass)
124+
|| !$this->isBackedEnumField($property, $resourceClass)
125+
) {
126+
return;
127+
}
128+
129+
$value = $this->normalizeValue($value, $property);
130+
if (null === $value) {
131+
return;
132+
}
133+
134+
$alias = $queryBuilder->getRootAliases()[0];
135+
$field = $property;
136+
137+
if ($this->isPropertyNested($property, $resourceClass)) {
138+
[$alias, $field] = $this->addJoinsForNestedProperty($property, $alias, $queryBuilder, $queryNameGenerator, $resourceClass, Join::INNER_JOIN);
139+
}
140+
141+
$valueParameter = $queryNameGenerator->generateParameterName($field);
142+
143+
$queryBuilder
144+
->andWhere(\sprintf('%s.%s = :%s', $alias, $field, $valueParameter))
145+
->setParameter($valueParameter, $value);
146+
}
147+
148+
/**
149+
* {@inheritdoc}
150+
*/
151+
protected function isBackedEnumField(string $property, string $resourceClass): bool
152+
{
153+
$propertyParts = $this->splitPropertyParts($property, $resourceClass);
154+
$metadata = $this->getNestedMetadata($resourceClass, $propertyParts['associations']);
155+
156+
if (!$metadata instanceof ClassMetadata) {
157+
return false;
158+
}
159+
160+
$fieldMapping = $metadata->fieldMappings[$propertyParts['field']];
161+
162+
// Doctrine ORM 2.x returns an array and Doctrine ORM 3.x returns a FieldMapping object
163+
if ($fieldMapping instanceof FieldMapping) {
164+
$fieldMapping = (array) $fieldMapping;
165+
}
166+
167+
if (!$enumType = $fieldMapping['enumType']) {
168+
return false;
169+
}
170+
171+
if (!($enumType::cases()[0] ?? null) instanceof \BackedEnum) {
172+
return false;
173+
}
174+
175+
$this->enumTypes[$property] = $enumType;
176+
177+
return true;
178+
}
179+
}

‎src/Doctrine/Orm/Tests/Filter/BackedEnumFilterTest.php

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the API Platform project.
5+
*
6+
* (c) Kévin Dunglas <[email protected]>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
declare(strict_types=1);
13+
14+
namespace ApiPlatform\Doctrine\Orm\Tests\Filter;
15+
16+
use ApiPlatform\Doctrine\Orm\Filter\BackedEnumFilter;
17+
use ApiPlatform\Doctrine\Orm\Tests\DoctrineOrmFilterTestCase;
18+
use ApiPlatform\Doctrine\Orm\Tests\Fixtures\Entity\Dummy;
19+
20+
/**
21+
* @author Rémi Marseille <[email protected]>
22+
*/
23+
class BackedEnumFilterTest extends DoctrineOrmFilterTestCase
24+
{
25+
use BackedEnumFilterTestTrait;
26+
27+
protected string $filterClass = BackedEnumFilter::class;
28+
29+
public static function provideApplyTestData(): array
30+
{
31+
return array_merge_recursive(
32+
self::provideApplyTestArguments(),
33+
[
34+
'valid case' => [
35+
sprintf('SELECT o FROM %s o WHERE o.dummyBackedEnum = :dummyBackedEnum_p1', Dummy::class),
36+
],
37+
'invalid case' => [
38+
sprintf('SELECT o FROM %s o', Dummy::class),
39+
],
40+
'valid case for nested property' => [
41+
sprintf('SELECT o FROM %s o INNER JOIN o.relatedDummy relatedDummy_a1 WHERE relatedDummy_a1.dummyBackedEnum = :dummyBackedEnum_p1', Dummy::class),
42+
],
43+
'invalid case for nested property' => [
44+
sprintf('SELECT o FROM %s o', Dummy::class),
45+
],
46+
]
47+
);
48+
}
49+
}

0 commit comments

Comments
 (0)