Eloquent Builder Decorator Laravel Package

Product Decisions This Supports

• Build vs. buy (or rather: adopt vs. copy). The package solves a narrow, well-understood architectural problem — extracting reusable, composable query logic out of Eloquent models without polluting them with dozens of local scopes. The decision it informs is less "should we depend on this library" and more "do we want the decorator pattern for query builders in our domain layer, and what's the cheapest way to get it."
• Codebase organization / maintainability roadmap. If your models have grown 20+ scopes, or if the same "active, published, within-date-range, for-tenant" query fragments are being re-implemented across services, this pattern is a candidate for a refactor epic. It gives you named, injectable query objects that are unit-testable independently of the model.
• Domain-layer boundaries. Decorators let application/domain code express intent (UserQuery::active()->recent()) without leaking Illuminate\Database\Eloquent\Builder calls into controllers, jobs, and console commands. That's a real design-quality lever when you're preparing for a modularization or package-extraction effort.
• Feature scoping for multi-tenant or permission-filtered reads. Query decoration is a natural seam for inserting tenant scoping, soft-visibility rules, or audit filters in one place rather than at each call site — relevant when you're planning RBAC or tenancy work.
• Not supported: any decision requiring vendor confidence. With 11 stars, zero dependents, and a last release in April 2020, this is not a bet you can make on behalf of a team. It informs pattern decisions, not dependency decisions.

When to Consider This Package

Consider the pattern when:

• Your team already understands the decorator/proxy pattern and wants query objects that wrap a builder rather than extend the model.
• You have repeated, composable filter chains used across many entry points (HTTP, queue workers, scheduled jobs, internal APIs).
• You want query logic testable without touching a database — decorators are trivially mockable.
• You are on Laravel 6/7 and pinning there for the foreseeable future.

Look elsewhere — or implement in-house — when:

• You're on Laravel 9+. Eloquent's Builder gained strict return types and contract changes; a package last touched in April 2020 is unlikely to survive. Verify compatibility before it enters a design doc, let alone a composer.json.
• You need maintenance guarantees. Zero dependents and a two-plus-year release gap mean you are the maintainer the moment you install it. The implementation is small enough that forking it into app/Support/ costs hours, not weeks, and removes the supply-chain and upgrade risk entirely.
• Native alternatives suffice. Local scopes, dedicated *Query classes that contain rather than decorate a builder, or Illuminate\Database\Eloquent\Builder::macro cover most of the same ground with zero new dependencies.
• Your team lacks pattern fluency. A decorator layer that forwards __call to an underlying builder is easy to misuse; expect onboarding cost and confusing stack traces if the team is junior.

PM recommendation: treat this repository as a reference implementation and design precedent, not a dependency. Cite it in the design doc, budget a small spike to port the pattern internally, and avoid adding a stale third-party package to your upgrade path.

How to Pitch It (Stakeholders)

To executives: This is a small, single-purpose code-organization library for our Laravel backend. It doesn't ship user-facing features; it makes query logic easier to reuse and test, which reduces the cost of future features that filter data (permissions, tenancy, reporting). Given its age and negligible adoption, I do not recommend adding it as a dependency — instead we'd copy the ~100-line pattern internally at near-zero cost and keep full control. Net ask: a short engineering spike, no vendor commitment, no licensing or procurement work.

To engineering: It demonstrates a clean way to layer composable query logic over Illuminate\Database\Eloquent\Builder via the decorator pattern — better separation than a model bloated with scopes, and independently testable. Caveat: last release April 2020, zero dependents, 11 stars, and Laravel's builder contract has changed since. Proposal: use it as the design reference, implement the decorator ourselves against our pinned Laravel version, and add a thin test suite so the pattern survives framework upgrades. Revisit only if the upstream repo is revived and version-pinned to our stack.