|
| 1 | +# Parameters and Filters |
| 2 | + |
| 3 | +API Platform is great for Rapid Application Development and provides lots of functionalities out of the box such as collection filtering with Eloquent. Most of the filtering is done using query parameters, which are automatically documented and validated. If needed you can use [state providers](core/state-providers) or a [Links Handler] to provide data. |
| 4 | + |
| 5 | +## Parameters |
| 6 | + |
| 7 | +A filter is usually used via a `ApiPlatform\Metadata\QueryParameter` and is also available through `ApiPlatform\Metadata\HeaderParameter`. For example, let's declare an `EqualsFilter` on our `Book` to be able to query an exact match using `/books?name=Animal Farm. A Fairy Story`: |
| 8 | + |
| 9 | +```php |
| 10 | +// app/Models/Book.php |
| 11 | + |
| 12 | +use ApiPlatform\Laravel\Eloquent\Filter\EqualsFilter; |
| 13 | +use ApiPlatform\Metadata\ApiResource; |
| 14 | +use ApiPlatform\Metadata\QueryParameter; |
| 15 | + |
| 16 | +#[ApiResource] |
| 17 | +#[QueryParameter(key: 'name', filter: EqualsFilter::class)] |
| 18 | +class Book extends Model |
| 19 | +{ |
| 20 | +} |
| 21 | +``` |
| 22 | + |
| 23 | +The `key` option specifies the query parameter and the `filter` applies the given value to a where clause: |
| 24 | + |
| 25 | +```php |
| 26 | +namespace ApiPlatform\Laravel\Eloquent\Filter; |
| 27 | + |
| 28 | +use ApiPlatform\Metadata\Parameter; |
| 29 | +use Illuminate\Database\Eloquent\Builder; |
| 30 | +use Illuminate\Database\Eloquent\Model; |
| 31 | + |
| 32 | +final class EqualsFilter implements FilterInterface |
| 33 | +{ |
| 34 | + /** |
| 35 | + * @param Builder<Model> $builder |
| 36 | + * @param array<string, mixed> $context |
| 37 | + */ |
| 38 | + public function apply(Builder $builder, mixed $values, Parameter $parameter, array $context = []): Builder |
| 39 | + { |
| 40 | + return $builder->where($parameter->getProperty(), $values); |
| 41 | + } |
| 42 | +} |
| 43 | +``` |
| 44 | + |
| 45 | +You can create your own filters by implementing the `ApiPlatform\Laravel\Eloquent\Filter\FilterInterface`. API Platform provides several eloquent filters for a RAD approach. |
| 46 | + |
| 47 | +### Parameter Validation |
| 48 | + |
| 49 | +You can add [validation rules](https://laravel.com/docs/validation) to parameters within the `constraints` attribute: |
| 50 | + |
| 51 | +```php |
| 52 | +// app/Models/Book.php |
| 53 | + |
| 54 | +use ApiPlatform\Laravel\Eloquent\Filter\PartialSearchFilter; |
| 55 | +use ApiPlatform\Metadata\ApiResource; |
| 56 | +use ApiPlatform\Metadata\QueryParameter; |
| 57 | + |
| 58 | +#[ApiResource] |
| 59 | +#[QueryParameter(key: 'name', filter: PartialSearchFilter::class, constraints: 'min:2')] |
| 60 | +class Book extends Model |
| 61 | +{ |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +<!-- TODO: The `security` option also allows policy but we need to test this --> |
| 66 | + |
| 67 | +### The `:property` Placeholder |
| 68 | + |
| 69 | +When programming APIs you may need to apply a filter on many properties at once. For example, we're allowing to sort on every property of our ApiResource with a partial search filter: |
| 70 | + |
| 71 | +```php |
| 72 | +// app/Models/Book.php |
| 73 | + |
| 74 | +use ApiPlatform\Laravel\Eloquent\Filter\PartialSearchFilter; |
| 75 | +use ApiPlatform\Laravel\Eloquent\Filter\OrderFilter; |
| 76 | +use ApiPlatform\Metadata\ApiResource; |
| 77 | +use ApiPlatform\Metadata\QueryParameter; |
| 78 | + |
| 79 | +#[ApiResource] |
| 80 | +#[QueryParameter(key: 'sort[:property]', filter: OrderFilter::class)] |
| 81 | +#[QueryParameter(key: ':property', filter: PartialSearchFilter::class)] |
| 82 | +class Book extends Model |
| 83 | +{ |
| 84 | +} |
| 85 | +``` |
| 86 | + |
| 87 | +The documentation will output a query parameter per property that applies the `PartialSearchFilter` and also gives the ability to sort by name and id using: `/books?name=search&order[id]=asc&order[name]=desc`. |
| 88 | + |
| 89 | +## Filters |
| 90 | + |
| 91 | +### Text |
| 92 | + |
| 93 | +As shown above the following search filters are available: |
| 94 | + |
| 95 | +- `ApiPlatform\Laravel\Eloquent\Filter\PartialSearchFilter` queries `LIKE %term%` |
| 96 | +- `ApiPlatform\Laravel\Eloquent\Filter\EqualsFilter` queries `= term` |
| 97 | +- `ApiPlatform\Laravel\Eloquent\Filter\StartSearchFilter` queries `LIKE term%` |
| 98 | +- `ApiPlatform\Laravel\Eloquent\Filter\EndSearchFilter` queries `LIKE %term` |
| 99 | + |
| 100 | +### Date |
| 101 | + |
| 102 | +The `DateFilter` allows to filter dates with an operator (`eq`, `lt`, `gt`, `lte`, `gte`): |
| 103 | + |
| 104 | +```php |
| 105 | +// app/Models/Book.php |
| 106 | + |
| 107 | +use ApiPlatform\Laravel\Eloquent\Filter\DateFilter; |
| 108 | + |
| 109 | +#[ApiResource] |
| 110 | +#[QueryParameter(key: 'publicationDate', filter: DateFilter::class, filterContext: ['include_nulls' => true])] |
| 111 | +class Book extends Model |
| 112 | +{ |
| 113 | + use HasUlids; |
| 114 | + |
| 115 | + public function author(): BelongsTo |
| 116 | + { |
| 117 | + return $this->belongsTo(Author::class); |
| 118 | + } |
| 119 | +} |
| 120 | +``` |
| 121 | + |
| 122 | +Our default strategy is to exclude null values, just remove the `filterContext` if you want to exclude nulls. |
| 123 | + |
| 124 | +### Or |
| 125 | + |
| 126 | +The `OrFilter` allows to filter using an `OR WHERE` clause: |
| 127 | + |
| 128 | +```php |
| 129 | +// app/Models/Book.php |
| 130 | + |
| 131 | +use ApiPlatform\Laravel\Eloquent\Filter\DateFilter; |
| 132 | + |
| 133 | +#[ApiResource] |
| 134 | +#[QueryParameter( |
| 135 | + key: 'q', |
| 136 | + filter: new OrFilter(new EqualsFilter()), |
| 137 | + property: 'isbn' |
| 138 | +)] |
| 139 | +class Book extends Model |
| 140 | +{ |
| 141 | + use HasUlids; |
| 142 | + |
| 143 | + public function author(): BelongsTo |
| 144 | + { |
| 145 | + return $this->belongsTo(Author::class); |
| 146 | + } |
| 147 | +} |
| 148 | +``` |
| 149 | + |
| 150 | +This allows to query multiple `isbn` values with a `q` query parameter: `/books?q[]=9781784043735&q[]=9780369406361`. |
| 151 | + |
| 152 | +<!-- ### Number |
| 153 | +
|
| 154 | +TODO --> |
| 155 | + |
| 156 | +### PropertyFilter |
| 157 | + |
| 158 | +Note: We strongly recommend using [Vulcain](https://vulcain.rocks) instead of this filter. Vulcain is faster, allows a better hit rate, and is supported out of the box in the API Platform distribution. |
| 159 | + |
| 160 | +The property filter adds the possibility to select the properties to serialize (sparse fieldsets). |
| 161 | + |
| 162 | +```php |
| 163 | +// app/Models/Book.php |
| 164 | + |
| 165 | +use ApiPlatform\Laravel\Eloquent\Filter\DateFilter; |
| 166 | +use ApiPlatform\Serializer\Filter\PropertyFilter; |
| 167 | + |
| 168 | +#[ApiResource] |
| 169 | +#[QueryParameter(key: 'properties', filter: PropertyFilter::class)] |
| 170 | +class Book extends Model |
| 171 | +{ |
| 172 | + use HasUlids; |
| 173 | + |
| 174 | + public function author(): BelongsTo |
| 175 | + { |
| 176 | + return $this->belongsTo(Author::class); |
| 177 | + } |
| 178 | +} |
| 179 | +``` |
| 180 | + |
| 181 | +A few `filterContext` options are available to configure the filter: |
| 182 | + |
| 183 | +* `override_default_properties` allows to override the default serialization properties (default `false`) Using `true` is dangerous, use carefully this can expose unwanted data! |
| 184 | +* `whitelist` properties whitelist to avoid uncontrolled data exposure (default `null` to allow all properties) |
| 185 | + |
| 186 | +Given that the collection endpoint is `/books`, you can filter the serialization properties with the following query: `/books?properties[]=title&properties[]=author`. |
0 commit comments