Doctrine Specification Laravel Package

Product Decisions This Supports

• Feature roadmap — composable filtering and search. Any roadmap item that involves "filter by X and Y, plus permissions, plus tenant" can be delivered as small Spec classes combined with andX/orX/notX, instead of adding another findActiveUserWithPictureAndCompany() method. This directly reduces the per-feature cost of new filtered views, admin screens, and API list endpoints.
• Build vs. buy on query infrastructure. The Specification pattern is well-understood and the library is a thin, MIT-licensed implementation. Buying this (a small dependency) beats a multi-week internal abstraction that would end up with the same API. The investment is adoption and code review discipline, not R&D.
• Repository refactoring strategy. Because specs are additive and composable, the fat-repository problem can be paid down incrementally — migrate one query per sprint without a big-bang rewrite. This is a low-risk way to schedule tech-debt work alongside feature work instead of competing with it.
• Business rules as first-class, dual-mode objects. The same spec runs against the database (match()) and in memory (isSatisfiedBy(), filterCollection()). That supports previews, dry-run eligibility checks, exports, validation, and "does this entity qualify?" UIs without duplicating logic in two languages (DQL and PHP).
• Authorization and scoping consistency. Permission-based filtering can be expressed as a spec and composed with feature filters, rather than reimplemented per query — a meaningful reduction in the risk of a filter being forgotten on a new endpoint.
• Dependency risk posture. 449 stars, MIT, releases through 2026 including Doctrine ORM 3 support with ORM 2 compatibility retained — acceptable for a library of this scope. However, the near-zero Packagist dependent count means we should treat it as internally owned and pin versions deliberately.

When to Consider This Package

Adopt when:

• The application uses Doctrine ORM 2.x or 3.x (typically Symfony, or Laravel via laravel-doctrine — note this is not an Eloquent library).
• Repository classes are growing past the point of comfort: many find* methods, many optional parameters, duplicated andWhere blocks.
• The same filtering logic is needed in more than one place — API filters, permission scoping, reporting, tenant isolation.
• The team is comfortable with the Specification pattern, or willing to invest an afternoon learning it, and values testable units over inline QueryBuilder calls.
• You need the identical rule enforced in the database and against in-memory data.

Look elsewhere when:

• The stack is Eloquent/Laravel-native. This package does not apply; use query scopes, dedicated query objects, or where closures instead.
• The domain is simple CRUD with handful of queries. The abstraction will cost more in indirection and onboarding than it saves.
• The team is pursuing CQRS/read models or already standardizes on query objects / custom DQL builders — you would be adding a second convention.
• Query performance tuning is a dominant concern and engineers need to see raw QueryBuilder output at all times; the extra layer gets in the way.
• You require a commercial support contract or SLA. This is a community package with no vendor backing.
• Doctrine is at a version outside the supported range, or the team cannot absorb the v2.0 breaking changes (private properties, removed Bitwise, moved/removed classes) given your current usage.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, MIT-licensed library that changes how our engineering team writes database queries. Today, query logic accumulates inside repository classes as long, duplicated methods that are hard to test and easy to get subtly wrong — especially around permission and tenant filtering. This package replaces that with small, named, reusable query components that compose together, so a new filtered screen or API endpoint reuses existing pieces instead of copying them. It is actively maintained (supporting both Doctrine ORM 2 and 3, with releases through 2026), carries no license cost, and its main cost is a short learning curve. Expected payoff is faster delivery of filtered views and a materially lower chance of a permission filter being missed on a new endpoint.

For engineering leads (bullets):

• Implements the Specification pattern: Spec::andX(...), orX, notX compose into a tree, which plain QueryBuilder mutation cannot express or reuse.
• Specs are small classes with a single responsibility — unit-testable without a database, and reusable across repositories and services.
• Hides QueryBuilder/DQL details from calling code, so services express what to fetch, not how.
• Same spec object works in three modes: repository->match($spec) for DB queries, isSatisfiedBy($entity) for single-entity checks, filterCollection($items) for in-memory filtering — no duplicated rule logic.
• Supports joins, aggregates (including DISTINCT and Count), SelectNew, GroupBy, OrderBy, Limit/Offset, and iteration with real keys.
• Requires Doctrine ORM 2.5+/3.x; migration from 1.x to 2.x is breaking (visibility changes, removed Bitwise, relocated Having), so budget for a version audit if we have legacy usage.
• Low external adoption (≈0 reported dependents) means we should own it: pin the version, keep specs in our own namespaces, and avoid relying on the maintainer for roadmap.

Recommendation: Approve a scoped pilot on one bounded area — e.g., a search/filter endpoint with permission scoping — with success measured by duplication removed and test coverage of query logic gained. Decision to standardize follows the pilot.