yuriitatur/query-builder

A simple package to build query node tree

v1.0.1 2025-08-01 21:48 UTC

Requires

• php: >=8.3
• doctrine/lexer: ^3.0
• psr/log: ^3.0
• yuriitatur/exceptions: ^1.0

Requires (Dev)

• doctrine/orm: ^4.0
• kint-php/kint: dev-master
• phpunit/phpunit: ^12.0

MIT

• Yurii Tatur

• php
• repository
• query
• builder

README

Query builder

This is a simple AST nodes set that comes with a very simple query lexer and parser. It uses doctrine/lexer project to deal with text tokens.

Installation

Composer:

composer require yuriitatur/query-builder

Testing

composer test

Why?

This package is needed to abstract a query construction process when dealing with repositories. After building an ast tree, this tree will be passed to a corresponding db driver to perform actual query.

Syntax

Although this package is purposely designed to expose it as ast, as a side effect, it's possible to write queries as a string. It's very basic, don't use it in production. Example:

FILTER={name = "Alice" AND (status in ["open", "closed"] OR priority >= 2)}
ORDER={createdAt desc, name asc}
PAGINATION={page=1, limit=10}
META={key="value"}
AGGREGATE={COUNT(id), SUM(amount)}

It features 5 top-level keywords:

• filter - defines a set of criteria bound together with and / or keywords. Groups can be nested with (). Supported operators: = != < > <= >= in !in like !like
• order - a list of columns each followed by asc or desc, separated by commas
• pagination - key-value pairs for page, limit, and offset (all integers)
• meta - a simple key-value storage for query-specific config passed to the db driver
• aggregate - a list of aggregate function calls; supported functions: avg, count, min, max, sum

License

This code is under MIT license, read more in the LICENSE file.