PHPackages                             adnanmula/criteria - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. adnanmula/criteria

ActiveLibrary

adnanmula/criteria
==================

0.4.0(8mo ago)0350MITPHPPHP >=8.4CI passing

Since Jan 12Pushed 7mo ago1 watchersCompare

[ Source](https://github.com/adnanmula/criteria)[ Packagist](https://packagist.org/packages/adnanmula/criteria)[ RSS](/packages/adnanmula-criteria/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (7)Versions (11)Used By (0)

Criteria
========

[](#criteria)

[![PHP Version](https://camo.githubusercontent.com/cf006c89c772d2582fc87986b0a244ce096bd804b71f67434ec781b48f43077e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d2533453d382e342d3737374242342e737667)](https://www.php.net/)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)

A powerful PHP library for building dynamic database queries with a fluent interface, specifically optimized for PostgreSQL.

Table of Contents
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
    - [Creating a Criteria Object](#creating-a-criteria-object)
    - [Using with Doctrine DBAL](#using-with-doctrine-dbal)
    - [Filter Operators](#filter-operators)
    - [Filter Fields](#filter-fields)
    - [Filter Values](#filter-values)
- [License](#license)

Requirements
------------

[](#requirements)

- PHP 8.4 or higher
- Doctrine DBAL 3.5 or higher

Installation
------------

[](#installation)

Install via [Composer](https://getcomposer.org/):

```
composer require adnanmula/criteria
```

Usage
-----

[](#usage)

### Creating a Criteria Object

[](#creating-a-criteria-object)

The `Criteria` class is the main entry point for building queries:

```
// Create a criteria object with filters, pagination and sorting
$criteria = new Criteria(
    filters: new Filters(
        FilterType::AND, // How top-level filters are combined
        // Simple filter
        new Filter(
            new FilterField('status'),
            new StringArrayFilterValue('active', 'pending', 'review'),
            FilterOperator::IN,
        ),
        // Filter composed of other filters
        new CompositeFilter(
            FilterType::OR, // How each expression of this composite filter is combined
            new Filter(
                new FilterField('id'),
                new StringFilterValue('abc123'),
                FilterOperator::EQUAL,
            ),
            new Filter(
                new FilterField('id'),
                new StringFilterValue('asdasd'),
                FilterOperator::EQUAL,
            ),
        ),
        // Composite filters can contain other composite filters (example: (id = 'abc123') OR (amount  '["value"]')
        new CompositeFilter(
            FilterType::OR,
            new Filter(
                new FilterField('id'),
                new StringFilterValue('abc123'),
                FilterOperator::EQUAL,
            ),
            new CompositeFilter(
                FilterType::AND,
                new Filter(
                    new FilterField('amount'),
                    new IntFilterValue(3),
                    FilterOperator::LESS_OR_EQUAL,
                ),
                new Filter(
                    new FilterField('json_field'),
                    new ArrayElementFilterValue('value'),
                    FilterOperator::IN_ARRAY,
                ),
            ),
        ),
        // You can add any number of filters or composite filters
    ),
    offset: 10,
    limit: 20,
    sorting: new Sorting(
        new Order(
            new FilterField('name'),
            OrderType::ASC,
        ),
        new Order(
            new FilterField('created_at'),
            OrderType::DESC,
        ),
    ),
);

// Helper methods
// Copy a criteria adding any number of filters
$originalCriteria = new Criteria();
$newCriteria = new Criteria()->with(
    new Filter(new FilterField('otherField'), new NullFilterValue(), FilterOperator::IS_NULL),
    new CompositeFilter(
        FilterType::OR,
        new Filter(new FilterField('domainId'), new IntFilterValue(3), FilterOperator::EQUAL),
        new Filter(new FilterField('random_string_or_null'), new StringFilterValue('imnotrandom'), FilterOperator::EQUAL),
    ),
);

// Copy a criteria removing pagination
$newCriteria = $criteria->withoutPagination();
// Copy a criteria removing pagination and sorting
$newCriteria = $criteria->withoutPaginationAndSorting();
// Copy a criteria removing filters
$newCriteria = $criteria->withoutFilters();
```

### Using with Doctrine DBAL

[](#using-with-doctrine-dbal)

The library integrates with Doctrine DBAL's QueryBuilder:

```
// Get a query builder from your Doctrine DBAL connection
$builder = $this->connection->createQueryBuilder();

// Build your base query
$query = $builder->select('a.fields')
    ->from('table', 'a');

// Apply criteria to the query builder
(new DbalCriteriaAdapter($builder))->execute($criteria);

// Execute the query
$result = $query->executeQuery()->fetchAllAssociative();
```

### Filter Operators

[](#filter-operators)

The library supports various filter operators:

- Comparison: `EQUAL`, `NOT_EQUAL`, `GREATER`, `GREATER_OR_EQUAL`, `LESS`, `LESS_OR_EQUAL`
- Text search: `CONTAINS`, `NOT_CONTAINS`, `CONTAINS_INSENSITIVE`, `NOT_CONTAINS_INSENSITIVE`
- Collection: `IN`, `NOT_IN`
- Null checks: `IS_NULL`, `IS_NOT_NULL`
- JSON array operations: `IN_ARRAY`, `NOT_IN_ARRAY`

### Filter Fields

[](#filter-fields)

- `FilterField`: Standard field for most column types
- `JsonKeyFilterField`: For accessing JSON/JSONB fields with specific keys

### Filter Values

[](#filter-values)

Value types for different data types:

- `StringFilterValue`: For string values
- `IntFilterValue`: For integer values
- `StringArrayFilterValue`: For arrays of strings (used with IN and NOT\_IN operators)
- `IntArrayFilterValue`: For arrays of integers (used with IN and NOT\_IN operators)
- `ArrayElementFilterValue`: For JSON array operations
- `NullFilterValue`: For NULL checks

License
-------

[](#license)

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance62

Regular maintenance activity

Popularity13

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~105 days

Recently: every ~40 days

Total

10

Last Release

264d ago

PHP version history (2 changes)0.0.1PHP >=8.1

0.3.0PHP >=8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/2ae3c9248d4074b98971b2701eb581a71567f8c1484d23b29ee85b32075e2deb?d=identicon)[adnanmula](/maintainers/adnanmula)

---

Top Contributors

[![adnanmula](https://avatars.githubusercontent.com/u/33516302?v=4)](https://github.com/adnanmula "adnanmula (34 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/adnanmula-criteria/health.svg)

```
[![Health](https://phpackages.com/badges/adnanmula-criteria/health.svg)](https://phpackages.com/packages/adnanmula-criteria)
```

###  Alternatives

[sonata-project/entity-audit-bundle

Audit for Doctrine Entities

644989.8k1](/packages/sonata-project-entity-audit-bundle)[overtrue/laravel-versionable

Make Laravel model versionable.

585308.0k5](/packages/overtrue-laravel-versionable)[elgg/elgg

Elgg is an award-winning social networking engine, delivering the building blocks that enable businesses, schools, universities and associations to create their own fully-featured social networks and applications.

1.7k15.7k4](/packages/elgg-elgg)[neos/flow

Flow Application Framework

862.0M450](/packages/neos-flow)[neos/flow-development-collection

Flow packages in a joined repository for pull requests.

144179.3k3](/packages/neos-flow-development-collection)[rias/statamic-redirect

28298.4k](/packages/rias-statamic-redirect)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)