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 is constructed with a database driver name (pgsql, mysql, sqlite). For each condition it:

1. Resolves the effective SQL template (operator’s own sql key, or its base operator’s).
2. Validates the raw value against the operator’s pattern (if defined).
3. Normalizes the value: booleans → 0/1, arrays → delimiter-joined string.
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.

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.

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)
        ├── Normalizes & casts value
        ├── Creates named parameters
        └── Returns SqlQuery { sql, parameters }
              │
              ▼
        Engine::execute(sql, parameters)
              │
              ▼
        array of result rows