PHPackages                             rikbruil/doctrine-specification - 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. [Database & ORM](/categories/database)
4. /
5. rikbruil/doctrine-specification

ActiveLibrary[Database & ORM](/categories/database)

rikbruil/doctrine-specification
===============================

Doctrine Specification pattern for building queries dynamically and with re-usable classes for composition.

1.2.0(9y ago)50251.6k—5.4%7[4 PRs](https://github.com/rikbruil/Doctrine-Specification/pulls)2MITPHPPHP >=5.5

Since Mar 7Pushed 1y ago4 watchersCompare

[ Source](https://github.com/rikbruil/Doctrine-Specification)[ Packagist](https://packagist.org/packages/rikbruil/doctrine-specification)[ RSS](/packages/rikbruil-doctrine-specification/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (7)Versions (17)Used By (2)

Doctrine Specification
======================

[](#doctrine-specification)

[![Build Status](https://camo.githubusercontent.com/f509e9e06d6dd791ef2be3778824c412f6db663b2411226bc090b55dce2eac1d/68747470733a2f2f7472617669732d63692e6f72672f72696b627275696c2f446f637472696e652d53706563696669636174696f6e2e737667)](https://travis-ci.org/rikbruil/Doctrine-Specification)[![Coverage Status](https://camo.githubusercontent.com/01c9577b6f550960bebe60313a38c4ad107b90b2fcbea11a251dcf348096ab33/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f72696b627275696c2f446f637472696e652d53706563696669636174696f6e2f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/r/rikbruil/Doctrine-Specification?branch=master)[![Latest Stable Version](https://camo.githubusercontent.com/d9cd2b2c1b9c709eb7721213746fbf2ff64aca53c9a5333e1937551d9d2ae312/68747470733a2f2f706f7365722e707567782e6f72672f72696b627275696c2f646f637472696e652d73706563696669636174696f6e2f762f737461626c652e737667)](https://packagist.org/packages/rikbruil/doctrine-specification)[![License](https://camo.githubusercontent.com/bb67440ae76ccd46538ee58cc704d72b66d13654af4a7b7e083ec2f02e2476c4/68747470733a2f2f706f7365722e707567782e6f72672f72696b627275696c2f646f637472696e652d73706563696669636174696f6e2f6c6963656e73652e737667)](https://packagist.org/packages/rikbruil/doctrine-specification)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/8cff9d7bacf8e2925377abf4e777248b5828c791f3619bf1fbdd034bb09f997a/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f72696b627275696c2f446f637472696e652d53706563696669636174696f6e2f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/rikbruil/Doctrine-Specification/?branch=master)[![SensioLabsInsight](https://camo.githubusercontent.com/73ee3a269e924277af13ca67fbe1577a6037f11b336ce777ab50ee537b889615/68747470733a2f2f696e73696768742e73656e73696f6c6162732e636f6d2f70726f6a656374732f62623232313832312d316261362d343631332d623339662d6634333731386161613932642f6d696e692e706e67)](https://insight.sensiolabs.com/projects/bb221821-1ba6-4613-b39f-f43718aaa92d)

Doctrine [Specification pattern](http://en.wikipedia.org/wiki/Specification_pattern) for building queries dynamically and with re-usable classes for composition.

This library started out as an adaptation of Benjamin Eberlei's [blog post](http://www.whitewashing.de/2013/03/04/doctrine_repositories.html). I was also inspired by the [Happyr Doctrine-Specification](https://github.com/Happyr/Doctrine-Specification) code, however this library has some small differences. The main one is that SpecificationRepository->match() does not return the results directly, but returns the query object.

Since I like Doctrine's Paginator object, I wanted to be able to use that in combination with the Specification pattern.

**Note:** In versions prior to 1.2 it was required to extend the SpecificationRepository class. This is no longer needed since we provide a SpecificationRepositoryTrait that you can use instead. The class is still provided for backwards compatibility reasons. There is also the SpecificationAwareInterface that you can use if you need it.

Usage
-----

[](#usage)

Install the latest version with `composer require rikbruil/doctrine-specification`

```
// Not using the lib
// Note: Advertisement repository is an instance of the Doctrine default repository class
$qb = $this->em->getRepository('Advertisement')
    ->createQueryBuilder('r');

return $qb->where('r.ended = 0')
    ->andWhere(
        $qb->expr()->orX(
            'r.endDate < :now',
            $qb->expr()->andX(
                'r.endDate IS NULL',
                'r.startDate < :timeLimit'
            )
        )
    )
    ->setParameter('now', new \DateTime())
    ->setParameter('timeLimit', new \DateTime('-4weeks'))
    ->getQuery()
    ->getResult();
```

```
use Rb\Specification\Doctrine\Condition\Equals;
use Rb\Specification\Doctrine\Condition\IsNull;
use Rb\Specification\Doctrine\Condition\LessThan;
use Rb\Specification\Doctrine\Logic\AndX;
use Rb\Specification\Doctrine\Logic\OrX;
use Rb\Specification\Doctrine\Specification;

// Using the lib
$spec = new Specification([
    new Equals('ended', 0),
    new OrX(
        new LessThan('endDate', new \DateTime()),
        new AndX(
            new IsNull('endDate'),
            new LessThan('startDate', new \DateTime('-4weeks'))
        )
    )
]);

// Note: Advertisement repository is an instance that uses the SpecificationRepositoryTrait
return $this->em->getRepository('Advertisement')->match($spec)->execute();
```

Composition
-----------

[](#composition)

A bonus of this pattern is composition, which makes specifications very reusable:

```
use Entity\Advertisement;

class ExpiredAds extends Specification
{
    public function __construct()
    {
        $specs = [
            new Equals('ended', 0),
            new OrX(
                new LessThan('endDate', new \DateTime()),
                new AndX(
                    new IsNull('endDate'),
                    new LessThan('startDate', new \DateTime('-4weeks'))
                )
            )
        ];
        parent::__construct($specs);
    }

    public function isSatisfiedBy($value)
    {
        return $value === Advertisement::class;
    }
}

use Entity\User;

class AdsByUser extends Specification
{
    public function __construct(User $user)
    {
        $specs = [
            new Select('u'),
            new Join('user', 'u'),
            new Equals('id', $user->getId(), 'u'),
        ];

        parent::__construct($specs);
    }

    public function isSatisfiedBy($value)
    {
        return $value == Advertisement::class && parent::isSatisfiedBy($value);
    }
}

class SomeService
{
    /**
     * Fetch Adverts that we should close but only for a specific company
     */
    public function myQuery(User $user)
    {
        $spec = new Specification([
            new ExpiredAds(),
            new AdsByUser($user),
        ]);

        return $this->em->getRepository('Advertisement')->match($spec)->execute();
    }

    /**
     * Fetch adverts paginated by Doctrine Paginator with joins intact.
     * A paginator can be iterated over like a normal array or Doctrine Collection
     */
    public function myPaginatedQuery(User $user, $page = 1, $size = 10)
    {
        $spec = new Specification([
            new ExpiredAds(),
            new AdsByUser($user),
        ]);

        $query = $this->em->getRepository('Advertisement')->match($spec);
        $query->setFirstResult(($page - 1) * $size))
            ->setMaxResults($size);
        return new Paginator($query);
    }
}
```

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

[](#requirements)

Doctrine-Specification requires:

- PHP 5.5+
- Doctrine 2.2

License
-------

[](#license)

Doctrine-Specification is licensed under the MIT License - see the `LICENSE` file for details

Acknowledgements
----------------

[](#acknowledgements)

This library is heavily inspired by Benjamin Eberlei's [blog post](http://www.whitewashing.de/2013/03/04/doctrine_repositories.html)and [Happyr's Doctrine-Specification library](https://github.com/Happyr/Doctrine-Specification).

###  Health Score

43

—

FairBetter than 91% of packages

Maintenance27

Infrequent updates — may be unmaintained

Popularity46

Moderate usage in the ecosystem

Community20

Small or concentrated contributor base

Maturity66

Established project with proven stability

 Bus Factor1

Top contributor holds 90.3% 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 ~53 days

Recently: every ~146 days

Total

15

Last Release

3349d ago

Major Versions

0.9.1 → 1.0.02015-03-07

### Community

Maintainers

![](https://www.gravatar.com/avatar/e62694a3877b86ed64be69e7e8f332f3bfd6850bf2efe97ab254966b4f41fb2c?d=identicon)[rikbruil](/maintainers/rikbruil)

---

Top Contributors

[![rikbruil](https://avatars.githubusercontent.com/u/154175?v=4)](https://github.com/rikbruil "rikbruil (102 commits)")[![friartuck6000](https://avatars.githubusercontent.com/u/4365821?v=4)](https://github.com/friartuck6000 "friartuck6000 (5 commits)")[![ErikMinekus](https://avatars.githubusercontent.com/u/1819481?v=4)](https://github.com/ErikMinekus "ErikMinekus (3 commits)")[![holtkamp](https://avatars.githubusercontent.com/u/776405?v=4)](https://github.com/holtkamp "holtkamp (3 commits)")

---

Tags

specificationdoctrinerepository

###  Code Quality

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/rikbruil-doctrine-specification/health.svg)

```
[![Health](https://phpackages.com/badges/rikbruil-doctrine-specification/health.svg)](https://phpackages.com/packages/rikbruil-doctrine-specification)
```

###  Alternatives

[happyr/doctrine-specification

Specification Pattern for your Doctrine repositories

452915.0k8](/packages/happyr-doctrine-specification)[knplabs/doctrine-behaviors

Doctrine Behavior Traits

92212.7M64](/packages/knplabs-doctrine-behaviors)[scienta/doctrine-json-functions

A set of extensions to Doctrine that add support for json query functions.

58723.9M36](/packages/scienta-doctrine-json-functions)[mediagone/doctrine-specifications

Doctrine implementation of repository Specifications pattern

353.8k3](/packages/mediagone-doctrine-specifications)

PHPackages © 2026

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