Weave Code
Doctrine Specification Laravel Package
happyr/doctrine-specification
Happyr Doctrine Specification brings the Specification pattern to Doctrine: compose small, reusable, testable specification classes into query expressions instead of bloated repositories with long QueryBuilder calls and duplicated logic.
Happyr Doctrine Specification brings the Specification pattern to Doctrine, replacing bloated repositories and long QueryBuilder calls with small, reusable query classes. Compose specifications to express business rules clearly, keep repository methods focused, and avoid parameter-heavy finder methods as your application grows.
- Composable queries with logical operators
- Reusable specification classes
- Testable query logic
- Doctrine-friendly QueryBuilder integration
- Cleaner repositories with less duplication
Frequently asked questions about Doctrine Specification
- What is happyr/doctrine-specification and what problem does it solve?
- It brings the Specification pattern to Doctrine queries by moving query criteria into small, reusable specification classes instead of long QueryBuilder calls and parameter-heavy repository methods. You can compose those specs with AND, OR and NOT, which raw QueryBuilder callbacks cannot do cleanly. It sits between your service layer and Doctrine repositories rather than replacing Doctrine itself.
- How do I install happyr/doctrine-specification with Composer?
- Run composer require happyr/doctrine-specification and confirm the installed version matches your PHP and Doctrine ORM matrix. v2.x requires PHP 7.2 or newer and supports Doctrine ORM 2 and 3, with ORM 3 support added in 2.2.0. There are no schema or infrastructure changes, so integration is limited to a dependency and a repository class change.
- Does happyr/doctrine-specification work with Laravel?
- It is a Doctrine ORM library, not an Eloquent package, so it only applies to Laravel applications that already use Doctrine through an integration such as laravel-doctrine. If your app is Eloquent-only, this package will not help and you should look at Eloquent query scopes or dedicated filter packages instead. In a Laravel-plus-Doctrine setup, it installs as a normal Composer dependency with no schema impact.
- Which PHP, Doctrine ORM and Symfony versions are supported?
- The v2 line requires PHP 7.2 or higher and supports Doctrine ORM 2 and 3, with v2.2.0 explicitly restoring ORM 2 compatibility alongside ORM 3. Symfony 6 and 7 support was added in 2.0.2 and 2.1.0 respectively. Confirm the exact matrix against Packagist and run your own CI against the target versions before standardizing.
- How do I combine specifications with AND, OR and NOT?
- Use the fluent Spec factory methods andX, orX and notX to build composite specifications from smaller ones. That composability is the main advantage over raw QueryBuilder callbacks, because the same spec such as active users can be reused inside active users not owned by company X. Composition happens at the object level and is then translated into DQL when the query runs.
- How do I test specifications without hitting the database?
- Specifications are plain objects, so you can unit test them directly and use isSatisfiedBy or filterCollection to evaluate them against in-memory collections. That lets you verify query behavior without a database connection. You should additionally add tests that assert the generated SQL or DQL, because the PHP and SQL evaluation paths can drift apart.
- Does happyr/doctrine-specification support pagination, sorting and hydration modes?
- The library focuses on composing query criteria, not on pagination or hydration. Sorting, pagination with the Doctrine paginator or Pagerfanta, hydration modes, INDEX BY, partial selects and locking are handled by Doctrine and should be verified separately against your use cases. Treat those as explicit evaluation items rather than assumed features.
- What is the difference between isSatisfiedBy and SQL evaluation?
- isSatisfiedBy evaluates a specification in PHP, while the same spec is also translated into DQL for database execution. Those two paths can diverge semantically, especially around nulls, case sensitivity and type coercion. Test parity explicitly so in-memory filtering and database results agree.
- How do I migrate a bloated Doctrine repository to specifications?
- Adopt incrementally rather than doing a big-bang rewrite, starting with one bounded context that has demonstrably painful repository code. Introduce the specification repository base class and the match method for that entity, move one query at a time into specification classes, and keep the old methods until the new path is covered by tests. This keeps risk contained and makes review easier.
- What are the alternatives to happyr/doctrine-specification and is it still maintained?
- It is an MIT library from a small organization with a narrow maintainer base and no SLA, and the metadata reports 0 dependents despite roughly 450 stars, so third-party battle-testing is limited. Alternatives include API Platform filter systems, CQRS read models with hand-written DQL, and, in Laravel, Eloquent query scopes if you are not using Doctrine. Because it is MIT you can fork it internally, but decide who owns the abstractions first.
Weaver
How can I help you explore Laravel packages today?