Filters

Filters reduce Collections to a subset of matching Models. Filters are expressed using Filter objects and in the absence of repository support work by iterating over the items in a list and building a list of records to remove from the collection. If it supports it, the repository can use the filter directly to customise its query to avoid expensive iteration.

Most filters operate on a single model record and apply a simple expression, like equals, more than, less than, contains etc. Some filters however are more complex. The Group filter for example contains a collection of other filters ANDed or ORed together. The Not filter inverts the selection of any other filter given to it.

Basic Filtering

The basic set of filters perform the essentials of everyday filtering. Most take the column name to filter on and a set of arguments to configure the filter.

Filter occurs in two main places: when you call that static find() function on a model class or if you call filter on an existing collection instance.

Successive calls to filter on a collection combine the filters (like an AND expression in SQL).

// First method:
$contacts = Contact::find($filter);

// Second method:
$contacts = Contact::all();
$contacts->filter($filter);

Equals

Selects models where the value in $columnName matches the value $equals exactly

new Equals($columnName, $equals)

Example

Select all models with a first name of Tom:

$contacts->filter(new Equals( "FirstName", "Tom" ));

StartsWith

Selects models where the value in $columnName starts with the value $startsWith. By default the search is case insensitive. For a case sensitive search you should pass true to $caseInsensitive.

new StartsWith($columnName, $startsWith, $caseInsensitive = false)

Example

Select all models with a first name starting with Tom:

$contacts->filter(new StartsWith( "FirstName", "Tom" ));    // Finds Tom, Tommy, Tombola

EndsWith

Selects models where the value in $columnName ends with the value $endsWith. By default the search is case insensitive. For a case sensitive search you should pass true to $caseInsensitive.

new EndsWith($columnName, $endsWith, $caseInsensitive = false)

Example

Select all models with a first name ending with 'a':

$contacts->filter(new StartsWith( "FirstName", "a" ));    // Finds Angela, Rebecca, SuzannA

Contains

Selects models where the value in $columnName contains the value $contains. By default the search is case insensitive. For a case sensitive search you should pass true to $caseInsensitive.

new Contains($columnName, $contains, $caseInsensitive = false)

Example

Select all models with a first name containing with 'bar':

$contacts->filter(new Contains( "FirstName", "bar" ));    // Finds Barbara, Allobar, Turbary

GreaterThan

Selects models where the value in $columnName is greater than value $greaterThan exclusive. To make it inclusive (greater than or equals) pass true to $inclusive.

new GreaterThan($columnName, $greaterThan, $inclusive = false)

Example

Select all donation models where the amount is greater or equal to 500:

$donations->filter(new GreaterThan( "Amount", 500, true ));

LessThan

Selects models where the value in $columnName is less than value $greaterThan exclusive. To make it inclusive (less than or equals) pass true to $inclusive.

new LessThan($columnName, $lessThan, $inclusive = false)

Example

Select all donation models where the amount is less than or equal to 500:

$donations->filter(new LessThan( "Amount", 500, true ));

Between

Selects models where the value in $columnName is between $min and $max inclusive.

new Between($columnName, $min, $max)

Example

Select all donation models where the amount is between 10 and 1000:

$donations->filter(new Between( "Amount", 10, 1000));

OneOf

Selects models where the value in $columnName is found a fixed list of possible values, $oneOf.

new OneOf($columnName, $oneOf)

Example

Select all donation models where the amount is 10, 100 or 1000:

$donations->filter(new OneOf( "Amount", [10, 100, 1000]));