2019-11-18 05:58:33 +01:00
|
|
|
---
|
2014-10-27 04:40:02 +01:00
|
|
|
title: SearchFilter Modifiers
|
|
|
|
summary: Use suffixes on your ORM queries.
|
2019-11-18 05:58:33 +01:00
|
|
|
icon: search
|
|
|
|
---
|
2014-10-27 04:40:02 +01:00
|
|
|
|
|
|
|
# SearchFilter Modifiers
|
|
|
|
|
2019-12-22 08:47:57 +01:00
|
|
|
The `filter` and `exclude` operations specify exact matches by default. However, when filtering `DataList`s, there are a number of suffixes that
|
2014-10-27 04:40:02 +01:00
|
|
|
you can put on field names to change this behavior. These are represented as `SearchFilter` subclasses and include.
|
|
|
|
|
2020-09-26 00:02:21 +02:00
|
|
|
* [ExactMatchFilter](api:SilverStripe\ORM\Filters\ExactMatchFilter)
|
2017-07-03 03:22:12 +02:00
|
|
|
* [StartsWithFilter](api:SilverStripe\ORM\Filters\StartsWithFilter)
|
|
|
|
* [EndsWithFilter](api:SilverStripe\ORM\Filters\EndsWithFilter)
|
|
|
|
* [PartialMatchFilter](api:SilverStripe\ORM\Filters\PartialMatchFilter)
|
|
|
|
* [GreaterThanFilter](api:SilverStripe\ORM\Filters\GreaterThanFilter)
|
|
|
|
* [GreaterThanOrEqualFilter](api:SilverStripe\ORM\Filters\GreaterThanOrEqualFilter)
|
|
|
|
* [LessThanFilter](api:SilverStripe\ORM\Filters\LessThanFilter)
|
|
|
|
* [LessThanOrEqualFilter](api:SilverStripe\ORM\Filters\LessThanOrEqualFilter)
|
2014-10-27 04:40:02 +01:00
|
|
|
|
|
|
|
An example of a `SearchFilter` in use:
|
2017-08-03 05:35:09 +02:00
|
|
|
|
2017-10-27 04:38:27 +02:00
|
|
|
```php
|
|
|
|
// fetch any player that starts with a S
|
|
|
|
$players = Player::get()->filter([
|
|
|
|
'FirstName:StartsWith' => 'S',
|
|
|
|
'PlayerNumber:GreaterThan' => '10'
|
|
|
|
]);
|
|
|
|
|
|
|
|
// to fetch any player that's name contains the letter 'z'
|
|
|
|
$players = Player::get()->filterAny([
|
|
|
|
'FirstName:PartialMatch' => 'z',
|
|
|
|
'LastName:PartialMatch' => 'z'
|
|
|
|
]);
|
2017-08-03 02:51:32 +02:00
|
|
|
```
|
2014-10-27 04:40:02 +01:00
|
|
|
|
2017-07-03 03:22:12 +02:00
|
|
|
Developers can define their own [SearchFilter](api:SilverStripe\ORM\Filters\SearchFilter) if needing to extend the ORM filter and exclude behaviors.
|
2014-10-27 04:40:02 +01:00
|
|
|
|
|
|
|
These suffixes can also take modifiers themselves. The modifiers currently supported are `":not"`, `":nocase"` and
|
2014-10-28 04:45:46 +01:00
|
|
|
`":case"`. These negate the filter, make it case-insensitive and make it case-sensitive, respectively. The default
|
2014-10-27 04:40:02 +01:00
|
|
|
comparison uses the database's default. For MySQL and MSSQL, this is case-insensitive. For PostgreSQL, this is
|
|
|
|
case-sensitive.
|
|
|
|
|
2020-09-26 00:02:21 +02:00
|
|
|
```php
|
|
|
|
// Fetch players that their FirstName is 'Sam'
|
|
|
|
// Caution: This might be case in-sensitive if MySQL or MSSQL is used
|
|
|
|
$players = Player::get()->filter([
|
|
|
|
'FirstName:ExactMatch' => 'Sam'
|
|
|
|
]);
|
|
|
|
|
|
|
|
// Fetch players that their FirstName is 'Sam' (force case-sensitive)
|
|
|
|
$players = Player::get()->filter([
|
|
|
|
'FirstName:ExactMatch:case' => 'Sam'
|
|
|
|
]);
|
|
|
|
|
|
|
|
// Fetch players that their FirstName is 'Sam' (force NOT case-sensitive)
|
|
|
|
$players = Player::get()->filter([
|
|
|
|
'FirstName:ExactMatch:nocase' => 'Sam'
|
|
|
|
]);
|
|
|
|
```
|
|
|
|
|
|
|
|
By default the `:ExactMatch` filter is applied, hence why we can shorthand the above to:
|
|
|
|
```php
|
|
|
|
$players = Player::get()->filter('FirstName', 'Sam'); // Default DB engine behaviour
|
|
|
|
$players = Player::get()->filter('FirstName:case', 'Sam'); // case-sensitive
|
|
|
|
$players = Player::get()->filter('FirstName:nocase', 'Sam'); // NOT case-sensitive
|
|
|
|
```
|
|
|
|
|
2017-07-03 03:22:12 +02:00
|
|
|
Note that all search filters (e.g. `:PartialMatch`) refer to services registered with [Injector](api:SilverStripe\Core\Injector\Injector)
|
2016-08-29 07:00:27 +02:00
|
|
|
within the `DataListFilter.` prefixed namespace. New filters can be registered using the below yml
|
|
|
|
config:
|
|
|
|
|
|
|
|
|
2017-08-03 02:51:32 +02:00
|
|
|
```yaml
|
2017-10-27 04:38:27 +02:00
|
|
|
SilverStripe\Core\Injector\Injector:
|
|
|
|
DataListFilter.CustomMatch:
|
|
|
|
class: MyVendor\Search\CustomMatchFilter
|
2017-08-03 02:51:32 +02:00
|
|
|
```
|
2016-08-29 07:00:27 +02:00
|
|
|
|
2014-10-28 04:45:46 +01:00
|
|
|
The following is a query which will return everyone whose first name starts with "S", either lowercase or uppercase:
|
2014-10-27 04:40:02 +01:00
|
|
|
|
2017-08-03 02:51:32 +02:00
|
|
|
```php
|
2017-10-27 04:38:27 +02:00
|
|
|
$players = Player::get()->filter([
|
|
|
|
'FirstName:StartsWith:nocase' => 'S'
|
|
|
|
]);
|
|
|
|
|
|
|
|
// use :not to perform a converse operation to filter anything but a 'W'
|
|
|
|
$players = Player::get()->filter([
|
|
|
|
'FirstName:StartsWith:not' => 'W'
|
|
|
|
]);
|
2017-08-03 02:51:32 +02:00
|
|
|
```
|
2014-10-27 04:40:02 +01:00
|
|
|
|
2017-11-27 04:39:17 +01:00
|
|
|
## Related Lessons
|
|
|
|
* [Introduction to ModelAdmin](https://www.silverstripe.org/learn/lessons/v4/introduction-to-modeladmin-1)
|
|
|
|
* [Building a search form](https://www.silverstripe.org/learn/lessons/v4/building-a-search-form-1)
|
|
|
|
|
2014-10-27 04:40:02 +01:00
|
|
|
## API Documentation
|
|
|
|
|
2017-07-03 03:22:12 +02:00
|
|
|
* [SearchFilter](api:SilverStripe\ORM\Filters\SearchFilter)
|