Laravel Sculptor Laravel Package

Product Decisions This Supports

• Build vs. buy on the query layer. Sculptor replaces the bespoke "query object / repository / filter" scaffolding most Laravel teams hand-roll. v2.0.0 signals this is a real abstraction, not a one-off: Query, CachedQuery, and BuilderCachedQuery are now the canonical presets, and the removed legacy traits consolidate the API into three choices.
• Whether to standardize query construction across teams. PHP attribute support (#[ForModel], #[Select], #[WithRelations], #[Limit]) with inheritance moves query metadata out of scattered method bodies and into declarative, reviewable class headers. That is a consistency and code-review decision as much as a technical one.
• Whether to invest in a caching layer now vs. later. CachedQuery gives result-level caching through Laravel's cache; BuilderCachedQuery integrates with atldays/laravel-eloquent-query-cache. For read-heavy endpoints (catalogs, dashboards, public APIs) this can defer infrastructure work rather than trigger it — a roadmap-sequencing input.
• Upgrade timing as an explicit roadmap item. Dropping Laravel 10 and 11 is a hard gate, not a deprecation. Any product on those versions must either upgrade Laravel first or stay pinned to v1 — a decision that needs a slot on the platform roadmap, not a silent dependency bump.
• Risk posture on a young dependency. v2.0.0 is the second stable release and already carries breaking changes (removed traits, removed paginate() shortcut, changed default page size). That informs a decision to adopt in a bounded module first, pin the version, and avoid spreading it platform-wide until the API stabilizes.
• Pagination behavior as a product-surface decision. Default per-page now follows Laravel's own model/builder defaults instead of an implicit 15. This changes API response shapes and payload sizes for any endpoint relying on the old default — worth flagging to whoever owns client contracts and mobile data usage.
• Use cases that justify adoption: multi-tenant or role-filtered listings, admin tables with consistent filtering/sorting, cached reference-data endpoints, and any codebase where N+1 regressions recur (the improved eager-load validation for builder-cache is directly aimed at that).

When to Consider This Package

Adopt when:

• You are on Laravel 12 or 13 and PHP 8.2+. On Laravel 10 or 11, v2.0.0 is simply not available — either upgrade Laravel or pin to v1 and accept that you are off the supported path.
• Your application has repeated read patterns (filters, selects, eager loads, pagination) that currently live in duplicated controller or repository code.
• You have read-heavy endpoints where result-level or builder-level caching would be a genuine win, and you want the caching logic co-located with the query definition rather than bolted on.
• Your team is comfortable with class-based, attribute-driven configuration and prefers conventions over per-feature wiring.
• You can absorb a breaking-change upgrade cycle roughly once per Laravel major — and you are willing to pin the version and read upgrade notes each time.

Look elsewhere when:

• You are locked to Laravel 10/11 for host, package, or compliance reasons.
• You need a dependency with long-term support guarantees, a large maintainer base, or extensive third-party documentation. This is an early-stage package with two stable releases; treat it as a bet on a small maintainer, not as infrastructure.
• Your data access is simple CRUD — the abstraction cost will exceed the benefit.
• You already have a mature internal query/filter abstraction; the migration cost likely outweighs the caching and attribute gains.
• You depend on the removed static paginate(perPage:, page:) shortcut or the legacy HasQueryWith* traits in many call sites. The upgrade is mechanical (make()->perPage()->page()->effect(), traits → presets) but volume matters — scope it before committing.
• You rely on an implicit 15-item default page size. That behavior is gone; you must call perPage(15) explicitly or set the model's $perPage. Audit any client that assumed the old page size before upgrading.

How to Pitch It (Stakeholders)

To executives: This is a developer-velocity dependency for our Laravel query layer, not a customer-facing feature. It replaces hand-written, inconsistent query code with a small set of standardized presets and adds optional caching at the query level, which lets us speed up read-heavy screens without new infrastructure. The cost is a contained upgrade cycle: v2.0.0 requires Laravel 12/13, so it is only viable alongside a framework upgrade we would need to schedule anyway for security support. Risk is moderate and bounded — the package is young and shipped breaking changes in this release, so we would adopt it in one module first, pin the version, and expand only after a clean cycle.

To engineering: v2.0.0 is a cleanup release that makes the package more predictable. Query metadata is now declarative via PHP attributes (#[ForModel], #[Select], #[WithRelations], #[Limit]) with inheritance support, so configuration is shared and reviewable instead of copy-pasted. The API narrows to three presets — Query, CachedQuery (Laravel cache, result-level), and BuilderCachedQuery (via atldays/laravel-eloquent-query-cache). Internals for caching are simplified and deduplicated, and builder-cache now validates eager-loaded relations, which should reduce N+1 surprises. Pagination aligns with Laravel's native defaults and adds stricter validation, so no more hidden 15-per-page magic. Breaking changes are limited and documented: Laravel 10/11 dropped, QueryResultPaginated::paginate() removed, legacy HasQueryWith* traits and CacheAttributeProvider removed. Migration is three steps — swap paginate() for make()->perPage()->page()->effect(), move legacy traits to the presets, and set perPage explicitly anywhere the old default mattered.