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.

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

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.
• $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.

PHP vs JavaScript Differences

Undefined Values

In JavaScript, accessing a non-existent property returns undefined. In PHP, there is no undefined type.

To handle this difference, the PHP version:

• Undefined in PHP means a key doesn't exist in an array (checked with !isset() or !array_key_exists())
• When a key doesn't exist, it's treated as null internally, but the comparison logic distinguishes between actual null values and non-existent keys
• By default, non-existent keys (undefined) do NOT equal null
• You can use setUndefinedEqualsNull(true) to make undefined values equal to null

Arrays vs Objects

PHP uses arrays for both lists and associative arrays (objects). The package automatically detects:

• Sequential numeric arrays (list-style) are treated as arrays
• Associative arrays are treated as objects/hashes

Advanced Features

Strict Mode

Enable strict type checking:

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.