Laravel Sculptor Laravel Package

Getting Started

Laravel Sculptor v2.0.0 targets PHP 8.2+ and Laravel 12/13. Start by installing the package and checking the README examples for the two main workflows: query presets and attribute-based query metadata.

First use case: create a query preset for a model and execute it through the new pagination flow.

$posts = PostsQuery::make()
    ->perPage(15)
    ->page(2)
    ->effect();

If you are upgrading, look first at any calls to QueryResultPaginated::paginate(...) or usage of the removed cache/filter traits. Those are the highest-risk migration points.

Implementation Patterns

Use the three query presets according to caching needs:

• Query for standard query composition.
• CachedQuery for result-level caching through Laravel’s cache.
• BuilderCachedQuery when integrating with atldays/laravel-eloquent-query-cache.

Prefer presets over the removed legacy traits. If your application used HasQueryWithCache, HasQueryWithBuilderCache, HasQueryWithFiltersAndCache, or HasQueryWithFiltersAndBuilderCache, migrate that behavior into the corresponding preset.

Define reusable query metadata with attributes on query classes:

#[ForModel(Post::class)]
#[Select(['id', 'title', 'published_at'])]
#[WithRelations(['author'])]
#[Limit(50)]
class PostsQuery extends Query
{
    //
}

Attribute reading supports inheritance, so shared base query classes can carry common ForModel, Select, WithRelations, and Limit metadata. Use this to standardize query behavior across related presets, then override in child classes where needed.

Use the builder-style pagination flow consistently:

$posts = PostsQuery::make()
    ->perPage(25)
    ->page(3)
    ->effect();

When perPage() is omitted, pagination now follows Laravel’s model/builder default per-page value. If a feature depends on a specific page size, set it explicitly or configure the model’s $perPage.

For cached queries, resolve cache stores through cache store attributes rather than hard-coding store names. Keep builder-cache usage aligned with eager-loaded relations, since v2 adds stricter validation around builder-cache interaction with eager loads.

Gotchas and Tips

• Laravel 10 and 11 are no longer supported. Upgrade to Laravel 12 or 13 before adopting v2.
• The static QueryResultPaginated::paginate(...) shortcut is removed. Replace it with make()->perPage(...)->page(...)->effect().
• Pagination no longer assumes the old default page size of 15. Call perPage(15) explicitly or set the model’s $perPage if you relied on that behavior.
• The legacy cache/query helper traits and CacheAttributeProvider are removed. Migrate directly to Query, CachedQuery, or BuilderCachedQuery.
• Pagination data validation is stricter in v2. Ensure page and perPage are valid integers and handle validation failures at the boundaries of your application.
• Attribute inheritance is convenient but can hide metadata changes. When debugging unexpected selects, relations, limits, or model bindings, inspect the full inheritance chain of the query preset.
• Builder-cache validation around eager-loaded relations may surface invalid relation names or missing eager loads earlier than before. Verify relation names and loading strategy before caching.
• CachedQuery caches results; BuilderCachedQuery integrates with the Eloquent query cache package. Do not mix expectations between result caching and builder/query caching.
• When cache behavior looks wrong, check the resolved cache store first, then the attribute metadata, then whether the query is using result-level or builder-level caching. The simplified internals in v2 make these the primary debugging surfaces.