Laravel Sculptor Laravel Package

Technical Evaluation

• Architecture fit: Laravel Sculptor sits as a query-preset/metadata layer over Eloquent, standardizing model binding, selected columns, eager loading, limits, caching, and pagination. The shift to PHP attributes (#[ForModel], #[Select], #[WithRelations], #[Limit]) aligns with modern Laravel/PHP conventions and centralizes query metadata near the model. This is a good fit for teams standardizing read-path query behavior, but it adds an abstraction layer that must be understood by application developers.
• Integration feasibility: Feasible for applications already on Laravel 12 or 13 and PHP 8.2+. The upgrade is not drop-in: removed static pagination, removed legacy cache/filter traits, removed CacheAttributeProvider, and changed pagination defaults require call-site and class-level changes. Applications on Laravel 10 or 11 are blocked until framework upgrades are complete.
• Technical risk: Medium-to-high because this is a major release with multiple breaking changes. The most material risks are silent pagination behavior changes (no explicit perPage() now falls back to Laravel’s model/builder default instead of the old package default of 15), removal of widely referenced traits, and dependency alignment for BuilderCachedQuery with atldays/laravel-eloquent-query-cache. Attribute inheritance and cache-store resolution via attributes need validation against our model hierarchy and cache configuration.
• Key questions: Are we on Laravel 12/13, or is a framework upgrade a prerequisite? Do we directly use any removed traits, CacheAttributeProvider, or QueryResultPaginated::paginate(...)? Do any APIs, exports, or UI flows assume a default page size of 15? Does our model inheritance work correctly with shared attribute reading? Is atldays/laravel-eloquent-query-cache compatible with Laravel 12/13 in our dependency set? What is our rollback plan if caching or pagination regressions appear?

Integration Approach

• Stack fit: Best suited to a Laravel 12/13 codebase on PHP 8.2+. Greenfield or actively maintained services can adopt attribute-based query metadata cleanly. Legacy Laravel 10/11 applications should treat this as a framework-upgrade-coupled initiative rather than a package bump.
• Migration path: Inventory usage of removed APIs first: HasQueryWithCache, HasQueryWithBuilderCache, HasQueryWithFiltersAndCache, HasQueryWithFiltersAndBuilderCache, CacheAttributeProvider, and QueryResultPaginated::paginate(...). Migrate those to Query, CachedQuery, or BuilderCachedQuery presets. Replace static pagination calls with Query::make()->perPage(...)->page(...)->effect(). Audit every paginated endpoint for implicit reliance on the old default page size and set perPage() explicitly or configure the model’s $perPage.
• Compatibility: Verify the third-party query-cache integration against Laravel 12/13 and our cache stores. Confirm attribute inheritance behavior for base models, traits, and child models. Validate that existing cache keys or invalidation assumptions are not broken by the simplified CachedQuery/BuilderCachedQuery internals. Run the package’s supported-version matrix against our actual PHP/Laravel versions, not just CI coverage.
• Sequencing: (1) Confirm framework/version baseline; (2) upgrade Laravel if required; (3) upgrade Sculptor in an isolated branch; (4) perform codemods for removed APIs and pagination calls; (5) update tests for pagination defaults and cache behavior; (6) validate staging performance and cache correctness; (7) roll out behind a feature flag or phased deployment if possible.

Operational Impact

• Maintenance: The major-version release reduces long-term API surface by removing legacy traits and simplifying cache internals, but it also establishes a new baseline that will require future upgrade discipline. Attribute-based metadata should reduce scattered query configuration, provided the team maintains conventions and documentation.
• Support: README and CI have been updated for the new pagination flow and attributes, which helps onboarding. However, this is a relatively specialized package with a third-party caching dependency; internal ownership and an escalation path are needed. Support for Laravel 10/11 is intentionally dropped, so teams on older frameworks must plan separately.
• Scaling: Result-level caching (CachedQuery) and builder-level caching (BuilderCachedQuery) can improve read scaling. Attribute-based cache-store resolution allows per-query store selection, which is useful for isolating heavy queries. Stricter pagination validation and improved eager-load validation reduce some correctness risks, but cache configuration and invalidation remain operational concerns.
• Failure modes: Pagination regressions from the changed default page size; fatal errors from removed traits during partial deployments; stale or misconfigured cache entries; attribute metadata silently not applied due to inheritance or placement mistakes; incompatibility with the third-party query-cache package; and increased response payloads if model defaults differ from assumed page sizes. These should be covered by automated tests and a staged rollout.
• Ramp-up: Developers need training on the attribute model, query presets, and the new pagination flow. Budget time for codemods, test updates, and cache-behavior validation. A short internal migration guide with before/after examples from the release notes will reduce friction.