Download the PHP package maurice2k/querycheck without Composer

QueryCheck for PHP

QueryCheck is a logical JSON query evaluator which uses the MongoDB™ query style.

This is a PHP 8.3+ port of the original JavaScript/Node.js querycheck package. Both packages support the same query and $expr aggregation operators. The PHP version has its own comparison rules, so it does not inherit PHP's type juggling (see Differences from the JavaScript Version).

Supported Operators

Comparison Operators

• $eq - Matches values that are equal to a specified value
• $ne - Matches values that are not equal to a specified value
• $gt - Matches values that are greater than a specified value
• $gte - Matches values that are greater than or equal to a specified value
• $lt - Matches values that are less than a specified value
• $lte - Matches values that are less than or equal to a specified value
• $in - Matches any of the values specified in an array
• $regex - Matches values using regular expression pattern matching

Logical Operators

• $and - Joins query clauses with a logical AND
• $or - Joins query clauses with a logical OR
• $not - Inverts the effect of a query expression

Aggregation Expressions ($expr)

• $expr - Allows aggregation expressions within query predicates

The following operators can be used within $expr:

Arithmetic Operators:

• $add - Adds numbers together
• $subtract - Subtracts two numbers
• $multiply - Multiplies numbers together
• $divide - Divides two numbers
• $mod - Returns the modulo of two numbers

Query Operators (for aggregation context):

• $eq - Returns true if values are equal
• $ne - Returns true if values are not equal
• $gt - Returns true if first value is greater than second
• $gte - Returns true if first value is greater than or equal to second
• $lt - Returns true if first value is less than second
• $lte - Returns true if first value is less than or equal to second

Logical Operators:

• $not - Returns the boolean opposite of an expression
• $in - Returns true if a value is in an array

Array Operators:

• $size - Returns the number of elements in an array

String Operators:

• $toLower - Converts a string to lowercase
• $toUpper - Converts a string to uppercase
• $concat - Concatenates strings
• $substr - Returns a substring (codepoint-based)
• $substrBytes - Returns a substring (byte-based)
• $strLenBytes - Returns the byte length of a string
• $strLenCP - Returns the codepoint length of a string
• $trim - Removes whitespace or characters from both ends
• $ltrim - Removes whitespace or characters from the start
• $rtrim - Removes whitespace or characters from the end

Conditional Operators:

• $cond - Conditional expression with if/then/else branches

Literal Operators:

• $literal - Returns a value without parsing it, so "$1" stays a string instead of a field reference

Field References: Field references within $expr use MongoDB syntax with $ prefix (e.g., $fieldName, $customer.address.city).

Installation

Install with Composer:

Simple Example

Using $expr for Aggregation Expressions

The $expr operator allows you to use aggregation expressions for field-to-field comparisons and calculations:

Notes:

• Field references in $expr require the $ prefix (e.g., $fieldName). Without the prefix, values are treated as literals.
• A string that starts with $ is always a field reference. Wrap values that may start with $, such as user input, in $literal: ['$eq' => ['$price', ['$literal' => $userInput]]]. Otherwise "$role" would compare with the field role. $literal returns its value without evaluating anything inside, also {$add: [2, 3]} stays that object.
• $expr can be combined with $and and $or operators to mix regular field queries with aggregation expressions.
• The aggregation $not operator evaluates false, null, and 0 as false; all other values (including non-zero numbers and arrays) as true.
• The aggregation $in operator checks if a value exists in an array, similar to the query $in but used within expressions.

Comparison Rules

These rules apply to the query operators and to the same operators inside $expr, with and without strict mode unless noted.

Types

PHP uses arrays for both lists and objects. QueryCheck treats a sequential array ([1, 2]) as an array and an associative array (['x' => 1]) as an object. Integers and floats are one numeric type everywhere: 12.1 > 10 is true, {v: 12} matches 12.0, and {v: {$ne: 1}} does not match 1.0. This matters because JSON encoders often write 137.0 as 137.

Equality ($eq, $ne, $in)

• Values of the same type are compared as they are: "abc" only equals "abc", objects are equal if they have the same keys and equal values.
• Numbers compare by value, also beyond 2^53 (9007199254740993 does not equal 9007199254740992.0). NaN equals NaN, as in MongoDB.
• null only equals null.
• Without strict mode, a string and a number are equal if the number written as text is the string: "137" equals 137, "137.0" does not. In strict mode a string never equals a number (see Strict Mode).
• $ne is always the negation of $eq.

Ordering ($gt, $gte, $lt, $lte)

PHP's own > and < order values of any type: "admin" > 18, [] > 18 and null < 5 are all true. QueryCheck only compares values that can be ordered against each other:

To order numeric strings as numbers, compare them with a number: {v: {$gt: 9}} matches "10", {v: {$gt: "9"}} does not. String bounds compare as text, so zero-pad times and dates ("09:00", "2020-09-15").

$not inverts the result, so {age: {$not: {$gte: 18}}} matches "admin". Use QueryCheck as an allow check (if ($qc->test($doc)) allow();), not as a deny list.

Array Fields

As in MongoDB, $eq, $ne and $in on an array field match if the whole array matches or one of its elements does:

So {role: {$ne: "banned"}} does not match ["banned", "admin"]. A whole array can be matched too: {tags: ["a", "b"]} and {tags: {$in: [["a", "b"]]}} match ["a", "b"], while {tags: ["a"]} does not match ["a", "b"]. {v: null} matches [null].

$gt, $gte, $lt and $lte do not look into arrays: an array field never matches them (MongoDB compares each element, see Differences from MongoDB).

Strict Mode

Strict mode is off by default. It turns type mismatches into errors:

• Two non-null values of different types are an error and throw a StrictTypeError: string vs number, array vs number, string vs array, boolean vs number, and so on. Integers and floats are one type, so 12 vs 12.0 is not a mismatch.
• null is "no value", not a wrong type. It never throws: it does not match $eq, $gt, $gte, $lt and $lte, and it matches $ne. Use the default UnknownVariableException (see Missing Fields) if missing data should be an error.
• Array fields are compared element by element for $eq, $ne and $in. Arrays may mix types, so an element of another type does not match, but does not throw either.
• Comparisons of the same type are identical in both modes. Strict mode only changes what happens when types differ.

Without strict mode, strings and numbers mix ("137" equals 137, 137 > "136") and every other mismatch simply does not match. Use strict mode when your documents have reliable types and a wrong type points to bad data or a wrong query; leave it off for loosely typed input such as form fields or CSV.

Missing Fields

By default, a field that does not exist in the document throws an UnknownVariableException. An existing field with the value null is not missing.

setThrowOnUnknownVariable(false) makes a missing field compare as null instead of throwing. Use it for MongoDB-like queries where {field: null} means "null or missing":

A null in the middle of a path makes the whole path null: {'profile.age': null} matches ['profile' => null].

Differences from MongoDB

QueryCheck follows MongoDB's query semantics where that is safe. It deliberately differs in these places:

Values of the same type, integer vs float, NaN, null vs null, booleans, $eq/$ne/$in on array fields and text comparison of strings behave as in MongoDB.

Differences from the JavaScript Version

The JavaScript version 2.0.0 follows this version: the same operators, Comparison Rules, strict mode, missing-field handling, compiled queries and syntax errors. What differs comes from the languages:

• Numbers: JavaScript has numbers and BigInts instead of integers and floats; integers beyond 2^53 are compared exactly with BigInts there.
• Number as text: "137" equals 137 in both, but each language writes numbers as text by its own rules (1.0E+21 here, 1e+21 in JavaScript).
• undefined: a field with the value undefined counts as missing in JavaScript.
• Dates: JavaScript also compares Date objects (by time).
• Regular expressions: JavaScript uses RegExp instead of PCRE (x is emulated, there is no backtrack limit).
• $trim with chars: a..z is a range here (PHP's trim()), not in JavaScript.
• Own properties: JavaScript only resolves own properties of the document.

Advanced Features

Compiled Queries

The query is compiled into a tree of closures on the first call to test() and reused for every later call, so create one QueryCheck per query and call test() as often as needed. Changing a setting (setStrictMode(), setOperandEvaluator(), ...) discards the compiled query; it is rebuilt on the next test().

Because the whole query is compiled up front, a syntax error such as an unknown $operator throws a SyntaxError on the first test(), even if it sits in a branch that would not have been evaluated for that document. The message starts with the location of the error:

To find syntax errors before the first document, call validate() after the setters, for example where rules are loaded or saved. It compiles the query and throws the SyntaxError; the compiled query is kept, so the next test() does not compile again:

Besides unknown operators and the wrong number of arguments, compiling rejects mistakes that would otherwise silently change the result:

validate() cannot find errors that depend on the document, such as a value $add cannot add. With an operand evaluator, objects like {$var: ...} are custom functions, not unknown operators; parts of $expr, $not and literal operands are then only checked when a document reaches them and the evaluator returns them unchanged. Errors there come from test(), also with the location.

A $regex that fails while matching a value, because PCRE's backtrack limit is exhausted or the value is not valid UTF-8 with the u option, throws a RegexError instead of counting as "no match". Otherwise $not would turn the failure into a match.

Short-circuit Evaluation

$and stops at the first branch that does not match and $or stops at the first branch that matches, in the order given. Later branches are not evaluated, so they cannot throw, and an operand evaluator is not called for them. This lets an earlier branch guard a later one:

MongoDB's evaluators short-circuit the same way, but MongoDB does not guarantee it and may reorder branches, so errors in skipped branches can differ.

Custom Operand Evaluator

You can extend QueryCheck with custom operand evaluation functions. The operand evaluator works with both regular query operators and $expr aggregation expressions:

Testing

Run the test suite locally:

Run static analysis:

Or with Docker (tests PHP 8.3, 8.4, and 8.5):

License

QueryCheck is available under the MIT license.