Skip to content

Commit 1e78bb2

Browse files
committed
docs(filters): enhance validation
Add notes on automatic validation benefits and reference `ParameterValidatorProvider` for Symfony and Laravel. Clarify the usage of `ParameterExtension` for handling empty values in Doctrine ORM.
1 parent 9e83ed0 commit 1e78bb2

File tree

1 file changed

+24
-5
lines changed

1 file changed

+24
-5
lines changed

core/doctrine-filters.md

Lines changed: 24 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -181,7 +181,7 @@ services all begin with `api_platform.doctrine_mongodb.odm`.
181181
### Built-in new Search Filters (API Platform >= 4.2)
182182

183183
To add some search filters, choose over this new list:
184-
- [IriFilter](#iri-filter) (filter on IRIs)
184+
- [IriFilter](#iri-filter) (filter on IRIs)
185185
- [ExactFilter](#exact-filter) (filter with exact value)
186186
- [PartialSearchFilter](#partial-search-filter) (filter using a `LIKE %value%``)
187187
- [FreeTextQueryFilter](#free-text-query-filter) (allows you to apply multiple filters to multiple properties of a resource at the same time, using a single parameter in the URL)
@@ -1534,6 +1534,18 @@ To validate inputs and ensure the correct type, we can implement the `JsonSchema
15341534

15351535
This allows delegating validation to API Platform, respecting the [SOLID Principles](https://en.wikipedia.org/wiki/SOLID).
15361536

1537+
> [!NOTE]
1538+
> Even with our internal systems, some additional **manual validation** is needed to ensure greater accuracy. However,
1539+
> we already take care of a lot of these validations for you.
1540+
>
1541+
> You can see how this works directly in our code components:
1542+
>
1543+
> * The `ParameterValidatorProvider` for **Symfony** can be found [here](https://github.com/api-platform/core/blob/c9692b509d5b641104addbadb349b9bcab83e251/src/Symfony/Validator/State/ParameterValidatorProvider.php).
1544+
> * The `ParameterValidatorProvider` for **Laravel** is located [here](https://github.com/api-platform/core/blob/c9692b509d5b641104addbadb349b9bcab83e251/src/Laravel/State/ParameterValidatorProvider.php).
1545+
>
1546+
> Additionally, we filter out empty values within our `ParameterExtension` classes. For instance, the **Doctrine ORM**
1547+
> `ParameterExtension` [handles this filtering here](https://github.com/api-platform/core/blob/c9692b509d5b641104addbadb349b9bcab83e251/src/Doctrine/Orm/Extension/ParameterExtension.php#L51C13-L53C14).
1548+
15371549
```php
15381550
<?php
15391551
@@ -1560,10 +1572,17 @@ final class MonthFilter implements FilterInterface, JsonSchemaFilterInterface
15601572
}
15611573
```
15621574

1563-
With this code, under the hood, API Platform has added a [Symfony Range constraint](https://symfony.com/doc/current/reference/constraints/Range.html)
1564-
that only accepts values between `1` and `12` (inclusive), which is what we want. In addition, we map the value to an integer,
1565-
which allows us to reject other types and directly return an integer in our filter when we retrieve the value with
1566-
`$monthValue = $parameter->getValue();`.
1575+
With this code, under the hood, API Platform automatically adds a [Symfony Range constraint](https://symfony.com/doc/current/reference/constraints/Range.html).
1576+
This ensures the parameter only accepts values between `1` and `12` (inclusive), which is exactly what we need.
1577+
1578+
This approach offers two key benefits:
1579+
1580+
- Automatic Validation: It rejects other data types and invalid values, so you get an integer directly.
1581+
- Simplified Logic: You can retrieve the value with `$monthValue = $parameter->getValue();` knowing it's already a
1582+
- validated integer.
1583+
1584+
This means you **don't have to add custom validation to your filter class, entity, or model**. The validation is handled
1585+
for you, making your code cleaner and more efficient.
15671586

15681587
### Documenting the ORM Filter (OpenAPI)
15691588

0 commit comments

Comments
 (0)