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?
- Happyr Doctrine Specification is a Composer package that brings the Specification pattern to Doctrine ORM query building. It lets you replace bloated repositories and long QueryBuilder calls with small, reusable specification classes. You can compose those specs into query expressions or evaluate them in memory. The goal is clearer business rules, less duplication, and query logic that is easier to test.
- How do I install happyr/doctrine-specification in a Laravel app?
- Install it with Composer using composer require happyr/doctrine-specification. There is no service provider, configuration file, or database schema change required. In a Laravel app you still need Doctrine ORM set up, because this package integrates with Doctrine repositories rather than Eloquent. After installation, wire a repository to use match() or extend the provided base repository and start writing specs.
- Does happyr/doctrine-specification work with Laravel if my app uses Eloquent?
- It works in Laravel applications that already use Doctrine ORM, but it does not make Eloquent queries use specifications. The library is framework-agnostic and has no container or configuration requirements. If your Laravel app is Eloquent-only, you would need to introduce Doctrine ORM before adopting this package.
- Which Doctrine ORM and PHP versions does happyr/doctrine-specification support?
- The 2.x line required Doctrine ORM 2.5+ and PHP 7.2+ at the time of the 2.0 release. Version 2.2.0 added Doctrine ORM 3 support while explicitly restoring ORM 2 compatibility. Check the package constraints with Composer for your exact Laravel, PHP, and Doctrine versions before upgrading. This version alignment is the main integration gate rather than setup effort.
- How do I apply a specification in a Doctrine repository?
- Make the target repository extend the package's base repository or add a match() method that accepts a specification. Build a spec from the provided combinators, such as Spec::andX with Spec::eq or Spec::join, and apply it through match(). The same specification can often also be checked in memory with isSatisfiedBy() or filterCollection(). Start with one read path and convert more as the pattern proves useful.
- How do I compose specifications with logical operators like AND and OR?
- Use the provided logical combinators such as Spec::andX and Spec::orX to combine smaller specification objects. You can nest specs to express rules like active adverts owned by a company without duplicating QueryBuilder code. Comparison and join specs such as Spec::eq, Spec::join, and Spec::isNull cover common predicates. For anything outside the combinators, write a custom Specification class rather than forcing the abstraction.
- Can I unit test specifications without hitting the database?
- Yes. Specifications support in-memory evaluation through isSatisfiedBy() and filterCollection(), so you can test business rules against entity objects without a database. That lets the same rule be enforced in SQL at query time and validated in a unit test. It is a practical testability benefit, not just a code-cleanliness one.
- Do I have to extend a base repository to use happyr/doctrine-specification?
- No, extending the base repository is one integration path but not the only one. You can add a match() method to an existing repository instead, which avoids consuming your single inheritance slot. That matters in larger codebases where repositories already extend a custom base class. Choose the approach that fits your existing repository hierarchy.
- When should I use QueryBuilder or plain DQL instead of specifications?
- Use QueryBuilder or plain DQL when a query is genuinely complex, one-off, or outside the provided combinators. The package is an abstraction over QueryBuilder, not a full query language, and complex fetching with multi-root joins, WITH clauses, native SQL, or window functions can become awkward. The common predicates are well covered, but the tail usually requires custom Specification classes or an escape hatch to DQL.
- Is happyr/doctrine-specification actively maintained and safe for production?
- It is MIT-licensed and the codebase is small and readable, but maintenance signal is mixed. The project has a small maintainer set, predominantly one contributor across the 2.x changelog, no commercial support tier, and reported zero dependents despite 449 GitHub stars. Version 2.2.0 adding Doctrine ORM 3 support is a positive sign, but 2.0 was a large breaking release, so budget for future major-version churn. Treat adoption as a conscious risk decision and pin versions.
Weaver
How can I help you explore Laravel packages today?