laravel-query-builders
Reusable query constraints live on a custom Eloquent builder per model, never in local scopes, and every query starts with Model::query(). Use when writing Eloquent queries, adding a query constraint or scope, defining an eager-load set, or registering a model's builder.
How do I install this agent skill?
npx skills add https://github.com/leeovery/agentic-skills --skill laravel-query-buildersIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides architectural guidance and PHP templates for implementing custom Laravel Query Builders. It contains no malicious code, remote downloads, or dangerous system commands. All code snippets follow standard Laravel security practices for database queries.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- ZeroLeakspass
2 findings · Score: 80/100
What does this agent skill do?
Laravel Query Builders
When a model needs query constraints that more than one caller uses, they go on a custom builder for that model: OrderBuilder extends Builder, one method per constraint, each returning self so they chain. Local scopes are never used. Every query is started with Model::query(), so the chain is typed as the model's builder from its first call.
Rules
- Start every query with
Model::query().Order::query()->wherePaid()->get(), neverOrder::wherePaid()orOrder::where(...). Every chain then reads the same way and starts from a real method that returns the model's builder, rather than a static call forwarded through__callStaticand__call. - A builder, never a local scope. No
scopeWherePaid(). A builder method is a plain, typed method that autocompletes and can call the other constraints on the builder. - Create a builder when a model needs a reusable constraint. Not for every model, and never empty "for later". A one-off
where()stays inline in the action or query class that uses it. - One builder per model, named
{Model}Builder. It lives inBuilders/beside the other classes of its kind (see laravel-architecture). - Register it with
#[UseEloquentBuilder(OrderBuilder::class)]on the model (Laravel 12.19+). Below 12.19, overridenewEloquentBuilder(), as shown after the example. - Name by what the method does.
where*adds a constraint:wherePaid(),whereCustomer(),whereHasBackorderedLines().with*loads relations or adds a computed column:withRelations(),withLowestBid(). - Methods compose. A constraint built from others calls them (
whereOverdue()callswherePaid()), so each rule is written once. - Type parameters as the domain types they are. Models, enums, contracts. A related model goes through
whereBelongsTo($customer); never acceptCustomer|intand branch oninstanceof. - Dates are
CarbonInterface, neverCarbon. The app runs onCarbonImmutable(see laravel-providers), so aCarbonparameter throws aTypeErrorwhen passednow(). - Type every query closure. A
whereHas()closure receives the related model's builder,function (OrderLineBuilder $query): void; a nestedwhere()closure receives this one,function (OrderBuilder $query): void. Eager-load constraints receive the relation itself: type them as what they are,HasMany; it forwards builder calls. The type is what makes the builder's methods autocomplete inside the closure. withRelations()is the model's eager-load set. When a model is usually loaded with the same relations, they're listed once, inwithRelations(), and reused by query classes, route binding and other builders' eager-load constraints. One name on every builder; neverwithRelated(),withAll()orwithFullRelations().
Example
<?php
declare(strict_types=1);
namespace App\Builders;
use App\Models\Customer;
use App\States\Order\OrderPaid;
use Carbon\CarbonInterface;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Relations\HasMany;
/**
* @method static OrderBuilder whereState(string $column, string|array $state)
* @method static OrderBuilder whereNotState(string $column, string|array $state)
*/
class OrderBuilder extends Builder
{
public function whereOverdue(CarbonInterface $asOf): self
{
return $this
->wherePaid()
->where('dispatch_by', '<', $asOf);
}
public function wherePaid(): self
{
return $this->whereState('state', OrderPaid::class);
}
public function whereCustomer(Customer $customer): self
{
return $this->whereBelongsTo($customer);
}
public function whereHasBackorderedLines(): self
{
return $this->whereHas('lines', function (OrderLineBuilder $query): void {
$query->whereBackordered();
});
}
public function withRelations(): self
{
return $this->with([
'customer',
'lines' => function (HasMany $query): void {
$query->withRelations();
},
]);
}
}
The model registers it:
use App\Builders\OrderBuilder;
use Illuminate\Database\Eloquent\Attributes\UseEloquentBuilder;
#[UseEloquentBuilder(OrderBuilder::class)]
class Order extends Model
{
// ...
}
Below Laravel 12.19, override the method instead. $query stays untyped: the parent's parameter is untyped, and PHP rejects a narrower type in an override.
class Order extends Model
{
public function newEloquentBuilder($query): OrderBuilder
{
return new OrderBuilder($query);
}
}
A caller reads as a sentence:
Order::query()
->whereCustomer($customer)
->whereOverdue(now())
->withRelations()
->get();
Reach for these when the situation calls for it
A package adds scopes to the model, such as spatie/laravel-model-states' whereState(). Declare each with @method static OrderBuilder on the builder, as in the example, so chains through them stay typed.
Several models share a constraint through a model concern and contract, such as ownership. Put the constraint in a builder trait, Builders/Concerns/IsOwnableScopes, used by each of those models' builders. It reads the column from the model rather than hard-coding it: $this->where($this->getModel()->getOwnedByField(), $owner->getKey()), taking the contract (Ownable $owner) as its parameter.
Every query on a model must carry a constraint. Add a global scope registered with #[ScopedBy(...)], and have its apply() call the builder's method rather than repeat the constraint. "No local scopes" doesn't rule out global ones.
The project's PHPStan level reports missing generic types. Add /** @extends Builder<Order> */ to the builder. Otherwise leave it off; the self return types already carry the type.
An index listing filtered, sorted and paginated from request input. That's a query class built on the builder, not a builder method; see laravel-controllers.
Anti-patterns
- ❌
public function scopePaid(Builder $query): a local scope. - ❌
Order::where('state', ...)orOrder::wherePaid(): noquery(). - ❌ An empty builder created in case it's needed later.
- ❌
wherePlacedBetween(Carbon $from, Carbon $to). - ❌
whereCustomer(Customer|int $customer)with aninstanceofbranch. - ❌
whereHas('lines', function ($query) { ... }): an untyped closure. - ❌ The same
->with([...])list repeated across query classes instead of onewithRelations(). - ❌ Request input, pagination or sorting parameters read inside a builder method.
Related
- laravel-models: the model a builder belongs to, and its relationships
- laravel-controllers: query classes for index listings
- laravel-state-machines: the states that
whereState()constrains - laravel-providers:
CarbonImmutabledates, and the lazy-loading reporting an incompletewithRelations()sets off
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/leeovery/agentic-skills/laravel-query-builders">View laravel-query-builders on skillZs</a>