Skip to content

Commit 9627e6b

Browse files
fix(dotrine/filters): typo and missing part for ODM
1 parent 1ce6135 commit 9627e6b

File tree

1 file changed

+39
-15
lines changed

1 file changed

+39
-15
lines changed

core/doctrine-filters.md

Lines changed: 39 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,7 @@ services all begin with `api_platform.doctrine_mongodb.odm`.
183183
To add some search filters, choose over this new list:
184184
- [IriFilter](#iri-filter) (filter on IRIs)
185185
- [ExactFilter](#exact-filter) (filter with exact value)
186-
- [PartialSearchFilter](#partial-search-filter) (filter using a `LIKE %value%``)
186+
- [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)
188188
- [OrFilter](#or-filter) (apply a filter using `orWhere` instead of `andWhere` )
189189

@@ -1456,7 +1456,7 @@ class MyCustomFilter implements FilterInterface
14561456
}
14571457
}
14581458
```
1459-
#### Implementing a Custom Filter
1459+
#### Implementing a Custom ORM Filter
14601460

14611461
Let's create a concrete filter that allows fetching entities based on the month of a date field (e.g., `createdAt`).
14621462

@@ -1497,8 +1497,8 @@ class MonthFilter implements FilterInterface
14971497
}
14981498
```
14991499

1500-
Now that the filter is created, it must be associated with an API resource. We use the `#[QueryParameter]` attribute on
1501-
a `GetCollection` operation for this. For other syntax please refer to the [documentation](#introduction).
1500+
Now that the filter is created, it must be associated with an API resource. We use the `QueryParameter` object on
1501+
a `#[GetCollection]` operation attribute for this. For other syntax please refer to [this documentation](#introduction).
15021502

15031503
```php
15041504
<?php
@@ -1524,8 +1524,11 @@ class Invoice
15241524
}
15251525
```
15261526

1527-
And that's it! ✅ Your filter is operational. A request like `GET /invoices?createdAtMonth=7` will now correctly return
1528-
the invoices from July!
1527+
And that's it! ✅
1528+
1529+
Your filter is operational.
1530+
1531+
A request like `GET /invoices?createdAtMonth=7` will now correctly return the invoices from July!
15291532

15301533
#### Adding Custom Filter ORM Validation And A Better Typing
15311534

@@ -1964,10 +1967,8 @@ class MonthFilter implements FilterInterface
19641967
}
19651968
```
19661969

1967-
Now that the filter is created, it must be associated with an API resource. We use the `#[QueryParameter]` attribute on
1968-
a `GetCollection` operation for this. For other synthax please refer to
1969-
1970-
[//]: # (TODO: add link to synthax)
1970+
Now that the filter is created, it must be associated with an API resource. We use the `QueryParameter` object on
1971+
a `#[GetCollection]` operation attribute for this. For other synthax please refer to [this documentation](#introduction).
19711972

19721973
```php
19731974
<?php
@@ -1993,7 +1994,11 @@ class Invoice
19931994
}
19941995
```
19951996

1996-
And that's it! ✅ Your filter is operational. A request like `GET /invoices?createdAtMonth=7` will now correctly return
1997+
And that's it! ✅
1998+
1999+
Your filter is operational.
2000+
2001+
A request like `GET /invoices?createdAtMonth=7` will now correctly return
19972002
the invoices from July!
19982003

19992004
#### Adding Custom Filter ODM Validation And A Better Typing
@@ -2003,6 +2008,18 @@ To validate inputs and ensure the correct type, we can implement the `JsonSchema
20032008

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

2011+
> [!NOTE]
2012+
> Even with our internal systems, some additional **manual validation** is needed to ensure greater accuracy. However,
2013+
> we already take care of a lot of these validations for you.
2014+
>
2015+
> You can see how this works directly in our code components:
2016+
>
2017+
> * The `ParameterValidatorProvider` for **Symfony** can be found [here](https://github.com/api-platform/core/blob/c9692b509d5b641104addbadb349b9bcab83e251/src/Symfony/Validator/State/ParameterValidatorProvider.php).
2018+
> * The `ParameterValidatorProvider` for **Laravel** is located [here](https://github.com/api-platform/core/blob/c9692b509d5b641104addbadb349b9bcab83e251/src/Laravel/State/ParameterValidatorProvider.php).
2019+
>
2020+
> Additionally, we filter out empty values within our `ParameterExtension` classes. For instance, the **Doctrine ODM**
2021+
> `ParameterExtension` [handles this filtering here](https://github.com/api-platform/core/blob/c9692b509d5b641104addbadb349b9bcab83e251/src/Doctrine/Odm/Extension/ParameterExtension.php#L50-L52).
2022+
20062023
```php
20072024
<?php
20082025
@@ -2029,10 +2046,17 @@ final class MonthFilter implements FilterInterface, JsonSchemaFilterInterface
20292046
}
20302047
```
20312048

2032-
With this code, under the hood, API Platform has added a [Symfony Range constraint](https://symfony.com/doc/current/reference/constraints/Range.html)
2033-
that only accepts values between `1` and `12` (inclusive), which is what we want. In addition, we map the value to an integer,
2034-
which allows us to reject other types and directly return an integer in our filter when we retrieve the value with
2035-
`$monthValue = $parameter->getValue();`.
2049+
With this code, under the hood, API Platform automatically adds a [Symfony Range constraint](https://symfony.com/doc/current/reference/constraints/Range.html).
2050+
This ensures the parameter only accepts values between `1` and `12` (inclusive), which is exactly what we need.
2051+
2052+
This approach offers two key benefits:
2053+
2054+
- Automatic Validation: It rejects other data types and invalid values, so you get an integer directly.
2055+
- Simplified Logic: You can retrieve the value with `$monthValue = $parameter->getValue();` knowing it's already a
2056+
- validated integer.
2057+
2058+
This means you **don't have to add custom validation to your filter class, entity, or model**. The validation is handled
2059+
for you, making your code cleaner and more efficient.
20362060

20372061
### Documenting the ODM Filter (OpenAPI)
20382062

0 commit comments

Comments
 (0)