Filter

Reference for the Filter module: read filter values from the query string, and build the forms and links that set them. Filter values live under a single filter query parameter, so a page can carry several named filters at once.

This page is a pure reference. For how the framework fits together, see the Guide.

Classes

Filter - read named filter values from the query string, and build filtered links and buttons.
FilterUi - render a filter form and its dropdown, text and integer inputs.

Filter

Read named filter values from the query string. Each value is looked up under $_GET['filter'][$filterName], so many filters share one query parameter. The class also builds URLs and buttons that carry a set of filters.

Functions

ButtonUi Get GetID GetIDOptional GetIDWithoutFilter GetInteger GetIntegerOptional GetOptional Link

ButtonUi

Filter::ButtonUi(string $url, string $label, int $count, array $filters): void

Render a button linking to a URL with the given filters attached and a count shown in the label as "Label (count)".

Name	Type	Description
`$url`	`string`	The base URL for the button.
`$label`	`string`	The button label text.
`$count`	`int`	The count shown in the label.
`$filters`	`array`	A map of filter name to value added to the URL.

Returns void

Get

Filter::Get(string $filterName, string $defaultValue = ''): string

Read a named filter value as a string, or the default when it is not present.

Name	Type	Description
`$filterName`	`string`	The filter name to read.
`$defaultValue`	`string`	The value returned when the filter is not present.

Returns string The filter value, or the default.

GetID

Filter::GetID(string $filterName, int $defaultValue = 0): int

Read a named filter value as an id, coercing it through To::ID, or the coerced default when it is not present.

Name	Type	Description
`$filterName`	`string`	The filter name to read.
`$defaultValue`	`int`	The id used when the filter is not present.

Returns int The filter value as an id.

GetIDOptional

Filter::GetIDOptional(string $filterName): ?int

Read a named filter value as an id, or null when it is not present or does not resolve to a positive id.

Name	Type	Description
`$filterName`	`string`	The filter name to read.

Returns ?int The id, or null.

GetIDWithoutFilter

Filter::GetIDWithoutFilter(string $parameter, string $defaultValue = '')

Read a top-level query parameter directly, outside the filter grouping, or the default when it is not present.

Name	Type	Description
`$parameter`	`string`	The top-level query parameter name to read.
`$defaultValue`	`string`	The value returned when the parameter is not present.

Returns The parameter value, or the default.

GetInteger

Filter::GetInteger(string $filterName, int $defaultValue = 0): int

Read a named filter value as an integer, coercing it through To::Int, or the coerced default when it is not present.

Name	Type	Description
`$filterName`	`string`	The filter name to read.
`$defaultValue`	`int`	The integer used when the filter is not present.

Returns int The filter value as an integer.

GetIntegerOptional

Filter::GetIntegerOptional(string $filterName): ?int

Read a named filter value as an integer, or null when it is not present or is an empty string.

Name	Type	Description
`$filterName`	`string`	The filter name to read.

Returns ?int The integer, or null.

GetOptional

Filter::GetOptional(string $filterName): ?string

Read a named filter value as a string, or null when it is not present or is an empty string.

Name	Type	Description
`$filterName`	`string`	The filter name to read.

Returns ?string The filter value, or null.

Link

Filter::Link(string $u_url, array $filters): string

Attach a set of filters to a URL as filter query parameters, skipping null values, and joining with a ? or an & as needed.

Name	Type	Description
`$u_url`	`string`	The URL to attach the filters to.
`$filters`	`array`	A map of filter name to value; null values are skipped.

Returns string The URL with the filters attached, unchanged when there are none.

FilterUi

Render a filter form and the inputs that go in it. The form submits with the GET method, and each input is named so its value is read back by the matching Filter function.

Functions

Dropdown Form Integer Text

FilterUi::Dropdown(string $name, string $label, $defaultValue, array $options)

Render a labelled select input for a filter, with an empty first option and the current filter value selected.

Name	Type	Description
`$name`	`string`	The filter name for the input.
`$label`	`string`	The label shown above the input.
`$defaultValue`		The value selected when the filter is not present.
`$options`	`array`	A map of option value to option label.

Returns Nothing; the input is echoed directly.

Form

FilterUi::Form(string $submitText, Callable $content)

Render a GET filter form, calling the content callback to add the inputs and appending a submit button.

Name	Type	Description
`$submitText`	`string`	The text on the submit button.
`$content`	`Callable`	A callback that renders the form inputs.

Returns Nothing; the form is echoed directly.

Integer

FilterUi::Integer(string $name, string $label, int $defaultValue): void

Render a labelled number input for a filter, showing the current filter value or the default.

Name	Type	Description
`$name`	`string`	The filter name for the input.
`$label`	`string`	The label shown above the input.
`$defaultValue`	`int`	The value shown when the filter is not present.

Returns void

Text

FilterUi::Text(string $name, string $label, $defaultValue = '')

Render a labelled text input for a filter, showing the current filter value or the default.

Name	Type	Description
`$name`	`string`	The filter name for the input.
`$label`	`string`	The label shown above the input.
`$defaultValue`		The value shown when the filter is not present.

Returns Nothing; the input is echoed directly.