Clause API

A clause is one comparison a filter offers, with the input it takes: no value, one value, a list, or a range. Custom clauses use InertiaX\Table\Filters\Clauses\Clause::make(string $key, ?string $label = null). Custom keys must be namespaced, such as acme/last-days.

Built-in comparisons

equals, not-equals Link to equals, not-equals: Input One value; a list with multiple() (select only); Value types Every built-in value type
contains, not-contains, starts-with, not-starts-with, ends-with, not-ends-with Link to contains, not-contains, starts-with, not-starts-with, ends-with, not-ends-with: Input One value; Value types text
greater-than, greater-than-or-equal, less-than, less-than-or-equal Link to greater-than, greater-than-or-equal, less-than, less-than-or-equal: Input One value; Value types number
between, not-between Link to between, not-between: Input A [from, to] range; Value types number, date, datetime, time
before, after Link to before, after: Input One value; Value types date, datetime, time
is-set, is-not-set Link to is-set, is-not-set: Input None; labelled Is not empty and Is empty; Value types Any filter

A built-in clause given another value type fails when the table is prepared, with a FilterDefinitionException such as clause [greater-than] does not support value type [text]. A custom value type takes only custom clauses, is-set, and is-not-set.

The corresponding ClauseType enum is in InertiaX\Table\Filters\Clauses\Enums. For example, ClauseType::Contains->make() creates the built-in contains clause. Text-pattern clauses support caseSensitive(?bool $value = true); the default comes from Filter::$defaultCaseSensitive, initially false. Database comparison behavior can vary by collation.

Inputs

A clause takes one value of its filter’s value type unless it says otherwise:

valueType(ValueType|string $type) Link to valueType: Input Its own value type: a built-in value type or vendor/name
withoutValue() Link to withoutValue: Input No value
range() Link to range: Input A [from, to] pair
multiple() Link to multiple: Input A non-empty list
options(array $options) Link to options: Input The values a select input offers; without them, a SelectFilter’s own options

The last of withoutValue(), range(), and multiple() wins. multiple() takes select values only, and range() takes number, date, datetime, time, or a custom value type. options() needs the select value type. Other combinations fail when the table is prepared, for example with clause [acme/x] cannot take a range value of type [text].

Value types

text Link to text: String
number Link to number: Finite number
boolean Link to boolean: Boolean
select Link to select: String, number, or Boolean
date Link to date: YYYY-MM-DD
datetime Link to datetime: Local YYYY-MM-DDTHH:mm[:ss[.fraction]]; a space may replace T
time Link to time: HH:mm[:ss[.fraction]]
vendor/name Link to vendor/name: Any JSON value except null

ValueType is in InertiaX\Table\Filters\Enums. Fractions contain one to six digits. Invalid dates fail, and so do ranges of a built-in value type whose start exceeds their end. Accepted temporal strings retain their submitted form in public state; comparisons use a separately normalized value.

null is never a value. A clause without input takes null, and every other clause rejects it. Use is-not-set to match missing values.

Custom methods

modifyUsing(Closure $modifier) Link to modifyUsing: Append an input transformation
validateUsing(?Closure $validator) Link to validateUsing: Return Boolean acceptance of the normalized value
applyUsing(?Closure $callback, DataSourceKind|string ...$sources) Link to applyUsing: Apply the comparison to a supported source
supports(DataSourceKind|string ...$sources) Link to supports: Declare source kinds separately

DataSourceKind is in InertiaX\Table\Enums. See Custom filters for complete comparison examples.

Validation order

For a clause that takes a value, the server checks the value against the clause’s input, runs modifiers, checks the input again, validates temporal values and range order, then calls the custom validator. A custom value type accepts any value except null, so its clauses must validate the value they expect.

A clause without input accepts only null and skips modifiers and the custom validator. Validation happens before query execution.

Execution contract

applyUsing() receives the source, the filter’s column as $column, the filter’s key as $key, and the validated value as $value. It may also request the filter, clause, and state through the callback evaluator. Declare supported source kinds explicitly.

Return the same source kind, or null to retain the incoming source. A custom clause that only implements SQL must declare only DataSourceKind::Eloquent. Unsupported sources and invalid return types fail with contextual exceptions.

For custom sources, the source receives the filter’s key and the validated value and performs the comparison. Use modifyUsing()/validateUsing() without an executor. Explicit applyUsing() conflicts with custom retrieval even with supports(DataSourceKind::Custom); a direct Clause implementation’s local apply() method is never invoked on this path.

See Callback context for injectable arguments and resolution rules.

View Markdown