Download the PHP package exegeseit/doctrinequerysearch-helper without Composer

DoctrineQuerySearchHelper

DoctrineQuerySearchHelper is a lightweight helper package for building dynamic WHERE clauses with Doctrine ORM or Doctrine DBAL query builders.

It helps you convert a structured $search array into safe, reusable and centralized query conditions, while keeping your repositories easy to read and maintain.

Table of contents

• Requirements
• Installation
• Quick start
• How it works
  • QueryClauseBuilder
  • SearchFilter
• Defining searchable fields
• Basic usage with Doctrine ORM
• Using SearchFilter helpers
  • Equality filters
  • LIKE filters
  • NULL filters
  • Comparison filters
  • Composition helpers
• About tokenized search keys
• Security
• License

Requirements

• PHP 8.2 or higher
• Doctrine ORM or Doctrine DBAL

Installation

Run the following command to install the package in your application:

Quick start

The following example shows a minimal usage of the package with a Doctrine ORM QueryBuilder.

This produces a condition equivalent to:

How it works

The package is based on two main components:

• QueryClauseBuilder
• SearchFilter

A typical use case is to create a fetchQb() method in your repository.

This method receives a $search array as parameter and returns a fully configured Doctrine QueryBuilder instance, including both the SELECT statement and the dynamic WHERE clause.

The $search parameter is an associative array where each entry defines one condition of the final WHERE clause:

QueryClauseBuilder

QueryClauseBuilder receives a Doctrine QueryBuilder instance and applies the dynamic conditions defined in the $search array.

It also defines the list of allowed search keys and maps them to actual Doctrine fields or expressions.

For example:

With this configuration, the $search array can use id, email and createdAt as search keys.

SearchFilter

SearchFilter provides static helper methods used to generate the keys of the $search array.

For example:

Each helper defines the type of condition to apply:

• equality
• inequality
• LIKE
• NULL
• comparison
• grouped AND / OR conditions

Defining searchable fields

Search keys must be explicitly declared before they can be used.

This is done with setSearchFields():

You can also define default LIKE fields with setDefaultLikeFields():

Default LIKE fields allow these two definitions to be equivalent:

Basic usage with Doctrine ORM

The examples below use Doctrine ORM, but the same approach can also be applied with Doctrine DBAL query builders.

The following example shows a repository method that creates a QueryBuilder to fetch Market objects.

It defines:

• the base SELECT statement;
• the allowed search keys;
• default LIKE fields;
• a default ORDER BY clause;
• the dynamic WHERE clause.

You can then use this repository method from a controller or an application service:

Using SearchFilter helpers

The following table summarizes the available filter helpers.

Equality filters

SearchFilter::filter()

SearchFilter::filter() applies the default condition only when the provided value is not falsy.

If the value is falsy, no filtering condition is added. Internaly, a falsy value is defined as:

Equivalent condition when $status is not falsy:

SearchFilter::equal()

Applies an equality condition.

Equivalent condition:

SearchFilter::notEqual()

Applies an inequality condition.

Equivalent condition:

LIKE filters

SearchFilter::like()

Applies a LIKE condition.

Equivalent condition:

SearchFilter::notLike()

Applies a NOT LIKE condition.

Equivalent condition:

SearchFilter::likeStrict()

Applies a strict LIKE condition.

Unlike SearchFilter::like(), the provided value is used as-is. Characters such as % and _ are neither appended nor escaped. This is useful for exact matches.

Equivalent condition:

SearchFilter::notLikeStrict()

Applies a strict NOT LIKE condition.

Unlike SearchFilter::notLike(), the provided value is used as-is. Characters such as % and _ are neither appended nor escaped. This is useful for exact matches.

Equivalent condition:

NULL filters

SearchFilter::null()

Applies an IS NULL condition.

Equivalent condition:

SearchFilter::notNull()

Applies an IS NOT NULL condition.

Equivalent condition:

Comparison filters

SearchFilter::greater()

Applies a greater-than condition.

Equivalent condition:

SearchFilter::greaterOrEqual()

Applies a greater-than-or-equal condition.

Equivalent condition:

SearchFilter::lower()

Applies a lower-than condition.

Equivalent condition:

SearchFilter::lowerOrEqual()

Applies a lower-than-or-equal condition.

Equivalent condition:

Range example

You can combine comparison filters to define numeric or date ranges.

Equivalent condition:

Another example with a numeric range:

Equivalent condition:

Composition helpers

SearchFilter also provides helpers to compose grouped conditions.

SearchFilter::andOr()

Applies a grouped OR condition joined to the current query with AND.

Equivalent condition:

SearchFilter::and()

Applies a grouped AND condition joined to the current query with AND.

Equivalent condition:

SearchFilter::or()

Applies a grouped AND condition joined to the current query with OR.

Equivalent condition:

About tokenized search keys

Most SearchFilter methods accept a $tokenize argument.

When $tokenize is enabled, a random suffix is added to the generated search key in order to avoid collisions when the same field is used multiple times in the same $search array.

This is useful when applying several conditions to the same field. For example:

Without tokenization, both conditions would use the same array key and one condition could overwrite the other.

Tokenization makes each generated key unique.

Security

Search values should be bound as query parameters and must not be interpolated directly into DQL or SQL strings.

This package is designed around declared search keys:

• allowed fields are explicitly configured with setSearchFields();
• default LIKE fields are explicitly configured with setDefaultLikeFields();
• user-provided search keys should not be passed directly without being mapped first.

This approach helps centralize the filtering logic and reduces the risk of exposing arbitrary fields or expressions.

License

This package is released under the MIT License.