class SearchContext (View source)

Manages searching of properties on one or more DataObject types, based on a given set of input parameters.

SearchContext is intentionally decoupled from any controller-logic, it just receives a set of search parameters and an object class it acts on.

The default output of a SearchContext is either a SQLSelect object for further refinement, or a SS_List that can be used to display search results, e.g. in a TableListField instance.

In case you need multiple contexts, consider namespacing your request parameters by using FieldList->namespace() on the $fields constructor parameter.

Each DataObject subclass can have multiple search contexts for different cases, e.g. for a limited frontend search and a fully featured backend search. By default, you can use DataObject->getDefaultSearchContext() which is automatically scaffolded. It uses DataObject::$searchable_fields to determine which fields to include.

Traits

A class that can be instantiated or replaced via DI

Properties

protected string $modelClass

DataObject subclass to which search parameters relate to.

protected FieldList $fields

FormFields mapping to DataObject::$db properties which are supposed to be searchable.

protected SearchFilter[] $filters

Array of SearchFilter subclasses.

protected array $searchParams

Key/value pairs of search fields to search terms

public deprecated string $connective

The logical connective used to join WHERE clauses. Must be "AND".

Methods

public static 
create(mixed ...$args)

An implementation of the factory method, allows you to create an instance of a class

public static 
singleton(string $class = null)

Creates a class instance by the "singleton" design pattern.

public
__construct(string $modelClass, FieldList $fields = null, array $filters = null)

A key value pair of values that should be searched for.

public
getSearchFields()

Returns scaffolded search fields for UI.

protected
applyBaseTableFields()

No description

public
getQuery(array $searchParams, array|bool|string $sort = false, array|bool|string $limit = false, DataList $existingQuery = null)

Returns a SQL object representing the search context for the given list of query parameters.

public
getResults(array $searchParams, array|bool|string $sort = false, array|bool|string $limit = false)

Returns a result set from the given search parameters.

public
bool
clearEmptySearchFields(mixed $value)

Callback map function to filter fields with empty values from being included in the search expression.

public
getFilter(string $name)

Accessor for the filter attached to a named field.

public
getFilters()

Get the map of filters in the current search context.

public
setFilters(array $filters)

Overwrite the current search context filter map.

public
addFilter(SearchFilter $filter)

Adds a instance of SearchFilter.

public
removeFilterByName(string $name)

Removes a filter by name.

public
getFields()

Get the list of searchable fields in the current search context.

public
setFields(FieldList $fields)

Apply a list of searchable fields to the current search context.

public
addField(FormField $field)

Adds a new FormField instance.

public
removeFieldByName(string $fieldName)

Removes an existing formfield instance by its name.

public
$this
setSearchParams(array|HTTPRequest $searchParams)

Set search param values

public
array
getSearchParams()

No description

public
getSummary()

Gets a list of what fields were searched and the values provided for each field. Returns an ArrayList of ArrayData, suitable for rendering on a template.

Details

static Injectable create(mixed ...$args)

An implementation of the factory method, allows you to create an instance of a class

This method will defer class substitution to the Injector API, which can be customised via the Config API to declare substitution classes.

This can be called in one of two ways - either calling via the class directly, or calling on Object and passing the class name as the first parameter. The following are equivalent: $list = DataList::create(SiteTree::class); $list = SiteTree::get();

Parameters

mixed ...$args

Return Value

Injectable

static Injectable singleton(string $class = null)

Creates a class instance by the "singleton" design pattern.

It will always return the same instance for this class, which can be used for performance reasons and as a simple way to access instance methods which don't rely on instance data (e.g. the custom SilverStripe static handling).

Parameters

string $class

Optional classname to create, if the called class should not be used

Return Value

Injectable

The singleton instance

__construct(string $modelClass, FieldList $fields = null, array $filters = null)

A key value pair of values that should be searched for.

The keys should match the field names specified in self::$fields. Usually these values come from a submitted searchform in the form of a $_REQUEST object. CAUTION: All values should be treated as insecure client input.

Parameters

string $modelClass

The base DataObject class that search properties related to. Also used to generate a set of result objects based on this class.

FieldList $fields

Optional. FormFields mapping to DataObject::$db properties which are to be searched. Derived from modelclass using DataObject::scaffoldSearchFields() if left blank.

array $filters

Optional. Derived from modelclass if left blank

FieldList getSearchFields()

Returns scaffolded search fields for UI.

Return Value

FieldList

protected applyBaseTableFields()

No description

move to SQLSelect fix hack

DataList getQuery(array $searchParams, array|bool|string $sort = false, array|bool|string $limit = false, DataList $existingQuery = null)

Returns a SQL object representing the search context for the given list of query parameters.

Parameters

array $searchParams

Map of search criteria, mostly taken from $_REQUEST. If a filter is applied to a relationship in dot notation, the parameter name should have the dots replaced with double underscores, for example "Comments__Name" instead of the filter name "Comments.Name".

array|bool|string $sort

Database column to sort on. Falls back to DataObject::$default_sort if not provided.

array|bool|string $limit
DataList $existingQuery

Return Value

DataList

Exceptions

Exception

DataList getResults(array $searchParams, array|bool|string $sort = false, array|bool|string $limit = false)

Returns a result set from the given search parameters.

rearrange start and limit params to reflect DataObject

Parameters

array $searchParams
array|bool|string $sort
array|bool|string $limit

Return Value

DataList

Exceptions

Exception

bool clearEmptySearchFields(mixed $value)

Callback map function to filter fields with empty values from being included in the search expression.

Parameters

mixed $value

Return Value

bool

SearchFilter getFilter(string $name)

Accessor for the filter attached to a named field.

Parameters

string $name

Return Value

SearchFilter

SearchFilter[] getFilters()

Get the map of filters in the current search context.

Return Value

SearchFilter[]

setFilters(array $filters)

Overwrite the current search context filter map.

Parameters

array $filters

addFilter(SearchFilter $filter)

Adds a instance of SearchFilter.

Parameters

SearchFilter $filter

removeFilterByName(string $name)

Removes a filter by name.

Parameters

string $name

FieldList getFields()

Get the list of searchable fields in the current search context.

Return Value

FieldList

setFields(FieldList $fields)

Apply a list of searchable fields to the current search context.

Parameters

FieldList $fields

addField(FormField $field)

Adds a new FormField instance.

Parameters

FormField $field

removeFieldByName(string $fieldName)

Removes an existing formfield instance by its name.

Parameters

string $fieldName

$this setSearchParams(array|HTTPRequest $searchParams)

Set search param values

Parameters

array|HTTPRequest $searchParams

Return Value

$this

array getSearchParams()

No description

Return Value

array

ArrayList getSummary()

Gets a list of what fields were searched and the values provided for each field. Returns an ArrayList of ArrayData, suitable for rendering on a template.

Return Value

ArrayList