⚙️ Expression Engine

About 290 wordsLess than 1 minute

The Expression Engine is a flexible and expressive filtering engine designed to handle both flat and deeply nested filters, including relationships and their attributes.

It is ideal when you want the power of RuleSet-style syntax but also need to filter through relationships and nested relations easily.

📦 Example Request

GET /posts?filter[status]=pending&filter[author.profile.name][like]=kettasoft

This will:

Filter posts where status is pending
AND where the related author's profile name contains kettasoft

🛠️ How It Works

Filters are parsed from the request's filter key.
Each filter can be a:
- Simple key-value pair (e.g., filter[status]=active)
- Operator-based pair (e.g., filter[name][like]=kettasoft)
- Nested relation filter (e.g., filter[author.profile.name]=ahmed)
The engine determines the filter structure and applies the corresponding query constraints.

🔧 Default Operator

If a filter doesn't specify an operator, the default operator will be used.
This default is configurable in the engine settings.

'default_operator' => '='

✅ Supported Features

✅ Flat and nested filters
✅ Dot notation for relationships (e.g., author.profile.name)
✅ Customizable default operator
✅ Whitelisting of allowed fields & relations
✅ Works well with eager loading and relationship validation
✅ Prevents filtering on undefined fields (optional strict mode)

✅ Allowed Fields & Relations

To avoid unauthorized or unintended access, you can configure the engine to only accept specific fields or relations:

Filterable::create()->useEngine('expression')
  ->allowedFields(['status'])
  ->allowRelations([
    'author.profile' => ['name'] // specific fields in this relation
  ])->paginate()

In strict mode, unsupported fields will be rejected with a validation error.

📌 Use Case

Post::filter($filters, Expression::class)->get();

🧠 Internal Logic (Simplified)

Parse the filter array recursively.
Detect relationships via dot notation.
Resolve the relation path and apply whereHas queries for related models.
Build appropriate SQL queries via the Eloquent builder.
Use the defined or default operator.

Invokable

Annotations