Skip to content

Commit 3a3841e

Browse files
meyerbaptistemeyerbaptiste
authored
Merge pull request #241 from meyerbaptiste/add_serializer_filters_doc
Add documentation for serializer filters
2 parents ac75a8f + e806378 commit 3a3841e

File tree

2 files changed

+165
-21
lines changed

2 files changed

+165
-21
lines changed

‎core/filters.md

Lines changed: 151 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,9 @@ By default, all filters are disabled. They must be enabled explicitly.
1010
When a filter is enabled, it is automatically documented as a `hydra:search` property in the collection response. It also
1111
automatically appears in the [NelmioApiDoc documentation](nelmio-api-doc.md) if it is available.
1212

13-
## Search Filter
13+
## Doctrine ORM Filters
14+
15+
### Search Filter
1416

1517
If Doctrine ORM support is enabled, adding filters is as easy as registering a filter service in your `app/config/services.yml`
1618
file and adding an attribute to your resource configuration.
@@ -82,7 +84,7 @@ Using a numeric ID is also supported: `http://localhost:8000/api/offers?product=
8284

8385
Previous URLs will return all offers for the product having the following IRI as JSON-LD identifier (`@id`): `http://localhost:8000/api/products/12`.
8486

85-
## Date Filter
87+
### Date Filter
8688

8789
The date filter allows to filter a collection by date intervals.
8890

@@ -121,7 +123,7 @@ class Offer
121123
}
122124
```
123125

124-
### Managing `null` Values
126+
#### Managing `null` Values
125127

126128
The date filter is able to deal with date properties having `null` values.
127129
Four behaviors are available at the property level of the filter:
@@ -148,7 +150,7 @@ services:
148150
If you use a service definition format other than YAML, you can use the `ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\DateFilter::EXCLUDE_NULL`
149151
constant directly.
150152

151-
## Boolean Filter
153+
### Boolean Filter
152154

153155
The boolean filter allows you to search on boolean fields and values.
154156

@@ -190,7 +192,7 @@ Given that the collection endpoint is `/offers`, you can filter offers by boolea
190192

191193
It will return all offers where `isAvailableGenericallyInMyCountry` equals `true`.
192194

193-
## Numeric Filter
195+
### Numeric Filter
194196

195197
The numeric filter allows you to search on numeric fields and values.
196198

@@ -231,7 +233,7 @@ Given that the collection endpoint is `/offers`, you can filter offers by boolea
231233
It will return all offers with `sold` equals 1
232234

233235

234-
## Range Filter
236+
### Range Filter
235237

236238
The range filter allows you to filter by a value Lower than, Greater than, Lower than or equal, Greater than or equal and between two values.
237239

@@ -273,7 +275,7 @@ It will return all offers with `price` between 12.99 and 15.99.
273275

274276
You can filters offers by joining two value for example: `/offers?price[gt]=12.99&price[lt]=19.99`.
275277

276-
## Order Filter
278+
### Order Filter
277279

278280
The order filter allows to order a collection against the given properties.
279281

@@ -325,7 +327,7 @@ services:
325327
tags: [ { name: 'api_platform.filter', id: 'offer.order' } ]
326328
```
327329

328-
### Comparing with Null Values
330+
#### Comparing with Null Values
329331

330332
When the property used for ordering can contain `null` values, you may want to specify how `null` values are treated in
331333
the comparison:
@@ -351,7 +353,7 @@ services:
351353
If you use a service definition format other than YAML, you can use the `ApiPlatform\Core\Bridge\Doctrine\Orm\Filter\OrderFilter::NULLS_SMALLEST`
352354
constant directly.
353355

354-
### Using a Custom Order Query Parameter Name
356+
#### Using a Custom Order Query Parameter Name
355357

356358
A conflict will occur if `order` is also the name of a property with the search filter enabled.
357359
Luckily, the query parameter name to use is configurable:
@@ -364,7 +366,7 @@ api_platform:
364366
order_parameter_name: '_order' # the URL query parameter to use is now "_order"
365367
```
366368

367-
## Filtering on Nested Properties
369+
### Filtering on Nested Properties
368370

369371
Sometimes, you need to be able to perform filtering based on some linked resources (on the other side of a relation). All
370372
built-in filters support nested properties using the dot (`.`) syntax, e.g.:
@@ -387,7 +389,7 @@ services:
387389
The above allows you to find offers by their respective product's color: `http://localhost:8000/api/offers?product.color=red`,
388390
or order offers by the product's release date: `http://localhost:8000/api/offers?order[product.releaseDate]=desc`
389391

390-
## Enabling a Filter for All Properties of a Resource
392+
### Enabling a Filter for All Properties of a Resource
391393

392394
As we have seen in previous examples, properties where filters can be applied must be explicitly declared. If you don't
393395
care about security and performance (e.g. an API with restricted access), it is also possible to enable built-in filters
@@ -417,6 +419,144 @@ It means that the filter will be **silently** ignored if the property:
417419
* is not enabled
418420
* has an invalid value
419421

422+
## Serializer Filters
423+
424+
### Group Filter
425+
426+
The group filter allows you to filter by serialization groups.
427+
428+
Syntax: `?groups[]=<group>`
429+
430+
You can add as many groups as you need.
431+
432+
Enable the filter:
433+
434+
```yaml
435+
# app/config/services.yml
436+
437+
services:
438+
book.group_filter:
439+
parent: 'api_platform.serializer.group_filter'
440+
arguments: # Default arguments values
441+
- 'groups' # The query parameter name
442+
- false # Allow to override the default serialization groups
443+
tags: [ { name: 'api_platform.filter', id: 'book.group' } ]
444+
```
445+
446+
```php
447+
<?php
448+
449+
// src/AppBundle/Entity/Book.php
450+
451+
namespace AppBundle\Entity;
452+
453+
use ApiPlatform\Core\Annotation\ApiResource;
454+
455+
/**
456+
* @ApiResource(attributes={"filters"={"book.group"}})
457+
*/
458+
class Book
459+
{
460+
// ...
461+
}
462+
```
463+
464+
Given that the collection endpoint is `/books`, you can filter by serialization groups with the following query: `/books?groups[]=read&groups[]=write`.
465+
466+
By default the query parameter name is `groups` but you can easily customize it to another by changing the first argument.
467+
For example, with `serialization_groups` as name:
468+
469+
```yaml
470+
# app/config/services.yml
471+
472+
services:
473+
book.group_filter:
474+
parent: 'api_platform.serializer.group_filter'
475+
arguments: [ 'serialization_groups' ]
476+
tags: [ { name: 'api_platform.filter', id: 'book.group' } ]
477+
```
478+
479+
You can also override the default serialization groups when you use the filter by changing the second argument to
480+
`true`:
481+
482+
```yaml
483+
# app/config/services.yml
484+
485+
services:
486+
book.group_filter:
487+
parent: 'api_platform.serializer.group_filter'
488+
arguments: [ 'groups', true ]
489+
tags: [ { name: 'api_platform.filter', id: 'book.group' } ]
490+
```
491+
492+
### Property filter
493+
494+
The property filter add the possibility to filter serialization properties.
495+
496+
Syntax: `?properties[]=<property>`
497+
498+
You can add as many properties as you need.
499+
500+
Enable the filter:
501+
502+
```yaml
503+
# app/config/services.yml
504+
505+
services:
506+
book.property_filter:
507+
parent: 'api_platform.serializer.property_filter'
508+
arguments: # Default arguments values
509+
- 'properties' # The query parameter name
510+
- false # Allow to override the default serialization properties
511+
tags: [ { name: 'api_platform.filter', id: 'book.property' } ]
512+
```
513+
514+
```php
515+
<?php
516+
517+
// src/AppBundle/Entity/Book.php
518+
519+
namespace AppBundle\Entity;
520+
521+
use ApiPlatform\Core\Annotation\ApiResource;
522+
523+
/**
524+
* @ApiResource(attributes={"filters"={"book.property"}})
525+
*/
526+
class Book
527+
{
528+
// ...
529+
}
530+
```
531+
532+
Given that the collection endpoint is `/books`, you can filter the serialization properties with the following query: `/books?properties[]=title&properties[]=author`.
533+
534+
By default the query parameter name is `properties` but you can easily customize it to another by changing the first argument.
535+
For example, with `serialization_properties` as name:
536+
537+
```yaml
538+
# app/config/services.yml
539+
540+
services:
541+
book.property_filter:
542+
parent: 'api_platform.serializer.property_filter'
543+
arguments: [ 'serialization_properties' ]
544+
tags: [ { name: 'api_platform.filter', id: 'book.property' } ]
545+
```
546+
547+
You can also override the default serialization properties when you use the filter by changing the second argument to
548+
`true`:
549+
550+
```yaml
551+
# app/config/services.yml
552+
553+
services:
554+
book.property_filter:
555+
parent: 'api_platform.serializer.property_filter'
556+
arguments: [ 'properties', true ]
557+
tags: [ { name: 'api_platform.filter', id: 'book.property' } ]
558+
```
559+
420560
## Creating Custom Filters
421561

422562
Custom filters can be written by implementing the `ApiPlatform\Core\Api\FilterInterface`

‎index.md

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -18,16 +18,20 @@
1818
2. [Configuring Operations](core/operations.md#configuring-operations)
1919
3. [Creating Custom Operations and Controllers](core/operations.md#creating-custom-operations-and-controllers)
2020
5. [Filters](core/filters.md)
21-
1. [Search Filter](core/filters.md#search-filter)
22-
2. [Date Filter](core/filters.md#date-filter)
23-
1. [Managing `null` Values](core/filters.md#managing-null-values)
24-
3. [Boolean Filter](core/filters.md#boolean-filter)
25-
4. [Numeric Filter](core/filters.md#numeric-filter)
26-
5. [Order filter](core/filters.md#order-filter)
27-
1. [Using a Custom Order Query Parameter Name](core/filters.md#using-a-custom-order-query-parameter-name)
28-
6. [Filtering on Nested Properties](core/filters.md#filtering-on-nested-properties)
29-
7. [Enabling a Filter for All Properties of a Resource](core/filters.md#enabling-a-filter-for-all-properties-of-a-resource)
30-
8. [Creating Custom Filters](core/filters.md#creating-custom-filters)
21+
1. [Doctrine ORM Filters](core/filters.md#doctrine-orm-filters)
22+
1. [Search Filter](core/filters.md#search-filter)
23+
2. [Date Filter](core/filters.md#date-filter)
24+
1. [Managing `null` Values](core/filters.md#managing-null-values)
25+
3. [Boolean Filter](core/filters.md#boolean-filter)
26+
4. [Numeric Filter](core/filters.md#numeric-filter)
27+
5. [Order filter](core/filters.md#order-filter)
28+
1. [Using a Custom Order Query Parameter Name](core/filters.md#using-a-custom-order-query-parameter-name)
29+
6. [Filtering on Nested Properties](core/filters.md#filtering-on-nested-properties)
30+
7. [Enabling a Filter for All Properties of a Resource](core/filters.md#enabling-a-filter-for-all-properties-of-a-resource)
31+
2. [Serializer Filters](core/filters.md#serializer-filters)
32+
1. [Group Filter](core/filters.md#group-filter)
33+
2. [Property Filter](core/filters.md#property-filter)
34+
3. [Creating Custom Filters](core/filters.md#creating-custom-filters)
3135
1. [Creating Custom Doctrine ORM Filters](core/filters.md#creating-custom-doctrine-orm-filters)
3236
2. [Overriding Extraction of Properties from the Request](core/filters.md#overriding-extraction-of-properties-from-the-request)
3337
6. [Serialization Groups and Relations](core/serialization-groups-and-relations.md)

0 commit comments

Comments
 (0)