Filtering

For a task-focused walkthrough (typed filters, controller usage, resource integration), see the Add filtering how-to.

Route Configuration

To enable filtering for a specific route, you use the filtering() method on the Route object. This automatically handles the documentation and request parameter resolution.

use apivalk\apivalk\Router\Route\Filter\StringFilter;
use apivalk\apivalk\Router\Route\Filter\EnumFilter;
use apivalk\apivalk\Router\Route\Filter\IntegerFilter;
use apivalk\apivalk\Router\Route\Filter\FloatFilter;
use apivalk\apivalk\Router\Route\Filter\DateFilter;
use apivalk\apivalk\Router\Route\Filter\DateTimeFilter;
use apivalk\apivalk\Router\Route\Filter\BooleanFilter;
use apivalk\apivalk\Router\Route\Route;
use apivalk\apivalk\Documentation\Property\StringProperty;
use apivalk\apivalk\Documentation\Property\EnumProperty;
use apivalk\apivalk\Documentation\Property\IntegerProperty;
use apivalk\apivalk\Documentation\Property\FloatProperty;
use apivalk\apivalk\Documentation\Property\DateProperty;
use apivalk\apivalk\Documentation\Property\DateTimeProperty;
use apivalk\apivalk\Documentation\Property\BooleanProperty;

public static function getRoute(): Route
{
    return Route::get('/contracts')
        ->filtering([
            EnumFilter::equals(new EnumProperty('status', 'Filter by status', ['active', 'inactive'])),
            StringFilter::contains(new StringProperty('name', 'Filter by name (contains)')),
            FloatFilter::greaterThan(new FloatProperty('amount', 'Minimum amount', FloatProperty::FORMAT_DOUBLE)),
            IntegerFilter::lessThan(new IntegerProperty('id', 'Filter by ID (less than)')),
            DateFilter::greaterThan(new DateProperty('created_at', 'Filter by creation date (greater than)')),
            DateTimeFilter::lessThan(new DateTimeProperty('updated_at', 'Filter by update date (less than)')),
            BooleanFilter::equals(new BooleanProperty('is_active', 'Filter by active flag', false)),
        ]);
}

Type-Safe Filtering

Apivalk provides specialized filter classes for different property types. Each filter is linked to its corresponding property type, ensuring that filter values are correctly type-cast when retrieved in your controller.

StringFilter: Linked to StringProperty. Supports equals, in, like, and contains.
EnumFilter: Linked to EnumProperty. Supports equals and in.
IntegerFilter: Linked to IntegerProperty. Supports equals, in, greaterThan, and lessThan. Returns int values.
FloatFilter: Linked to FloatProperty. Supports equals, in, greaterThan, and lessThan. Returns float values.
DateFilter: Linked to DateProperty. Supports equals, in, greaterThan, and lessThan. Returns \DateTime values.
DateTimeFilter: Linked to DateTimeProperty. Supports equals, in, greaterThan, and lessThan. Returns \DateTime values.
ByteFilter: Linked to ByteProperty. Supports equals and in.
BinaryFilter: Linked to BinaryProperty. Supports equals and in.
BooleanFilter: Linked to BooleanProperty. Supports equals. Returns bool values.

Benefits:

OpenAPI Accuracy: The documentation reflects the correct data type (e.g., number, integer, string).
Automatic Casting: getValue() returns the correct PHP type (string, int, float, or \DateTime), or null if the filter was not provided by the client.
Raw Access: getRawValue() returns the original query string the client sent (e.g. "2024-01-15T14:30:00+00:00" for a DateTimeFilter), or null if the filter wasn’t provided. Useful for audit logs, error messages that quote the user’s literal input, or distinguishing “client supplied an unparseable value” (getRawValue() !== null && getValue() === null) from “client omitted the filter” (both null).
Detailed Documentation: You can add custom descriptions, examples, and constraints to your filters.

IntegerFilter::equals(new IntegerProperty('id', 'Filter by ID (equals)', IntegerProperty::FORMAT_INT64))

Supported Filter Types

StringFilter

StringFilter::equals(StringProperty $property): Exact match for a single string.
StringFilter::in(StringProperty $property): Match against a list of strings.
StringFilter::like(StringProperty $property): Partial string matching (e.g., prefix%).
StringFilter::contains(StringProperty $property): Match if a string contains another.

EnumFilter

EnumFilter::equals(EnumProperty $property): Exact match against allowed values.
EnumFilter::in(EnumProperty $property): Match against a list of allowed values.

IntegerFilter

IntegerFilter::equals(IntegerProperty $property): Exact integer match.
IntegerFilter::in(IntegerProperty $property): Match against a list of integers.
IntegerFilter::greaterThan(IntegerProperty $property): Integer comparison.
IntegerFilter::lessThan(IntegerProperty $property): Integer comparison.

FloatFilter

FloatFilter::equals(FloatProperty $property): Exact float match.
FloatFilter::in(FloatProperty $property): Match against a list of floats.
FloatFilter::greaterThan(FloatProperty $property): Float comparison.
FloatFilter::lessThan(FloatProperty $property): Float comparison.

DateFilter

DateFilter::equals(DateProperty $property): Exact date match.
DateFilter::in(DateProperty $property): Match against a list of dates.
DateFilter::greaterThan(DateProperty $property): Date comparison.
DateFilter::lessThan(DateProperty $property): Date comparison.

DateTimeFilter

DateTimeFilter::equals(DateTimeProperty $property): Exact date-time match.
DateTimeFilter::in(DateTimeProperty $property): Match against a list of date-times.
DateTimeFilter::greaterThan(DateTimeProperty $property): Date-time comparison.
DateTimeFilter::lessThan(DateTimeProperty $property): Date-time comparison.

ByteFilter

ByteFilter::equals(ByteProperty $property): Exact byte match.
ByteFilter::in(ByteProperty $property): Match against a list of byte values.

BinaryFilter

BinaryFilter::equals(BinaryProperty $property): Exact binary match.
BinaryFilter::in(BinaryProperty $property): Match against a list of binary values.

BooleanFilter

BooleanFilter::equals(BooleanProperty $property): Exact boolean match. Returns a bool value.

Usage in Controller

When a route has filtering enabled, you can access the resolved filters from the request via the filtering() method.

public function __invoke(ApivalkRequestInterface $request): AbstractApivalkResponse
{
    $filters = $request->filtering();
    
    // Check if a specific filter was provided by the client
    if ($filters->has('status')) {
        $type = $filters->status->getType(); // for example contains, so you know you do str_contains for example
        $status = $filters->status->getValue();
        // apply to your query...
    }
    
    // Iterate over all provided filters
    foreach ($filters as $field => $filter) {
        $type = $filter->getType();
        $value = $filter->getValue();
        // ...
    }
    
    // ...
}

Client-Side Usage

Apivalk supports two query string formats — both reach the same filter values in your controller.

Flat notation

Each filter is a top-level query parameter. Simple and compact.

GET /contracts?status=active
GET /contracts?status=active&name=Acme

Bracket notation

Filters are nested under a filter key. Useful when you want a clear namespace separation from other parameters (pagination, sorting, etc.), or when tooling like OpenAPI client generators constructs nested objects.

GET /contracts?filter[status]=active
GET /contracts?filter[status]=active&filter[name]=Acme

Both formats are equivalent — they produce the same FilterBag in your controller and can be mixed freely within a single request (flat takes precedence if both supply the same field).

OpenAPI Documentation

When you configure filters on a route, Apivalk generates a single filter parameter in the OpenAPI spec using style: deepObject. Each declared filter appears as a named property inside its schema:

- name: filter
  in: query
  required: false
  style: deepObject
  explode: true
  schema:
    type: object
    properties:
      status:
        type: string
        description: "Filter by status"
      amount:
        type: number
        description: "Minimum amount (greater than)"

In Swagger UI, this renders as separate inputs labelled filter[status], filter[amount], etc. — matching the bracket notation clients should use at runtime. Both flat notation (?status=active) and bracket notation (?filter[status]=active) are accepted by the server regardless of which style is chosen. Pass flatFilters: true to OpenAPIGenerator to switch to one flat query parameter per filter instead. See OpenAPI Generator → Filter Documentation Style for the full reference.

Getting started

Concepts

HTTP

Resources

Routing

Cache

Middleware

Documentation (OpenAPI)

Core System

Security

Customization

How-To Guides

API Standards

Route Configuration

Type-Safe Filtering

Supported Filter Types

StringFilter

EnumFilter

IntegerFilter

FloatFilter

DateFilter

DateTimeFilter

ByteFilter

BinaryFilter

BooleanFilter

Usage in Controller

Client-Side Usage

Flat notation

Bracket notation

OpenAPI Documentation

​Route Configuration

​Type-Safe Filtering

​Supported Filter Types

​StringFilter

​EnumFilter

​IntegerFilter

​FloatFilter

​DateFilter

​DateTimeFilter

​ByteFilter

​BinaryFilter

​BooleanFilter

​Usage in Controller

​Client-Side Usage

​Flat notation

​Bracket notation

​OpenAPI Documentation

Route Configuration

Type-Safe Filtering

Supported Filter Types

StringFilter

EnumFilter

IntegerFilter

FloatFilter

DateFilter

DateTimeFilter

ByteFilter

BinaryFilter

BooleanFilter

Usage in Controller

Client-Side Usage

Flat notation

Bracket notation

OpenAPI Documentation