Architecture

derafu/query is organized into six cooperating layers. Understanding them helps you choose which classes to instantiate, which bridges to use, and where to add custom behavior.

Layers at a Glance

Filter Layer

The filter layer turns a raw string expression like customers[alias:c]__invoices[on:id=customer_id,alias:i]__total?>1000 into an object tree.

Key Classes

Parsing Pipeline

"status?=active&&total?>1000"
       │
       ▼ CompositeExpressionParser
  CompositeCondition (AND)
  ├── Condition
  │   ├── Path [Segment("status")]
  │   └── Filter [Operator("="), value="active"]
  └── Condition
      ├── Path [Segment("total")]
      └── Filter [Operator(">"), value="1000"]

The literal flag on Condition distinguishes normal filter values from expression references (used with the ?E marker for self-referencing conditions like id?E!=other_alias.id).

Operator Layer

Operators are defined in resources/operators.yaml and loaded at startup. Each operator carries:

• A symbol (e.g. >=, like:, b&)
• A type classifying its behavior
• Engine-specific SQL templates with {{column}} / {{value}} / {{values}} / {{value_1}} / {{value_2}} placeholders
• An optional validation pattern (regex) for the value
• Optional casting rules that transform the value before binding
• An optional alias pointing to another operator’s SQL template

Key Classes

Builder Layer

The builder layer converts condition objects into SQL strings with named parameters.

Key Classes

SqlBuilderWhere Internals

SqlBuilderWhere accepts an engine name, a non-empty list delimiter (comma by default), and an optional dql flag (false by default). The ORM bridge requests DQL variants automatically. For each condition it:

1. Resolves and validates the effective template (operator’s own sql key, or its base operator’s), selects the engine, and uses default for SQL or dql with default fallback for ORM.
2. Validates the raw value against the operator’s pattern (if defined).
3. Reads the raw string|null value from Filter; booleans, arrays and objects are not filter-value inputs.
4. Applies casting rules (e.g. like_start appends %, date normalizes YYYYMMDD → YYYY-MM-DD).
5. Creates named parameters (param_{column}_{uniqid}).
6. Replaces {{column}}, {{value}}, {{values}}, {{value_1}}, {{value_2}} in the template.

For composite conditions it recursively builds each child and joins them with AND / OR inside parentheses. The Illuminate bridge adapts the resulting named parameters to positional bindings in SQL occurrence order.

For EXISTS paths (starting with ___) it generates correlated EXISTS (SELECT 1 FROM …) or NOT EXISTS (…) subqueries. Aggregate column segments like SUM(amount) produce scalar subqueries: (SELECT SUM(p.amount) FROM payments p WHERE …) >= :param.

For PostgreSQL comparisons of correlated COUNT, SUM and AVG aggregates, numeric scalar/list/range parameters use CAST(parameter AS NUMERIC). The ORM bridge uses mapped types and NumericComparisonType for numeric aggregate operands, emitting a cast on SQLite/PostgreSQL while preserving the original decimal strings.

The ORM bridge separately renders mapped association subqueries with EXISTS and HAVING. Internal aliases are allocated to avoid collisions with explicit or previously generated aliases.

Column Resolution from Paths

When a path has more than one segment, SqlBuilderWhere qualifies the column with the previous segment’s alias (or name):

authors__books__title  →  books.title
authors[alias:a]__books[alias:b]__title  →  b.title

For SqlQueryBuilder, intermediate segments automatically become JOIN clauses (INNER by default; override with join:left option).

Engine Layer

The engine layer executes the SQL produced by the builder against a real connection.

Bridge Layer

Bridges apply parsed conditions to existing third-party query builder instances, without requiring the full SqlQueryBuilder.

All bridge appliers share ConditionApplierTrait, which provides:

• buildConditionSql() — compiles to SQL via SqlBuilderWhere
• extractPaths() — collects all paths from a condition tree
• inferFromTable() — detects the base table from multi-segment paths
• buildJoinSpecsFromPaths() — builds JOIN specs for SQL-level bridges
• buildOrmJoinSpecsFromPaths() — builds JOIN specs for Doctrine ORM DQL

Config Layer

The config layer provides a declarative alternative to the fluent builder API.

QueryConfig::fromFile() auto-detects YAML vs JSON by file extension.

Data Flow Summary

User provides string expression
        │
        ▼
CompositeExpressionParser
  ├── ExpressionParser
  │     ├── PathParser  → Path (Segments)
  │     └── FilterParser → Filter (Operator + value)
  └── returns Condition | CompositeCondition
        │
        ▼
SqlQueryBuilder  (or a Bridge applier)
  └── SqlBuilderWhere
        ├── Resolves SQL template (operator + engine)
        ├── Reads string/null value & applies casting rules
        ├── Creates named parameters
        └── Returns SqlQuery { sql, parameters }
              │
              ▼
        Engine::execute(sql, parameters)
              │
              ▼
        array of result rows