class Builder (View source)

Properties

protected Builder $query The base query builder instance.
protected Model $model The model being queried.
protected array $eagerLoad The relationships that should be eager loaded.
protected array $macros All of the registered builder macros.
protected Closure $onDelete A replacement for the typical delete function.
protected array $passthru The methods that should be returned from query builder.
protected array $scopes Applied global scopes.
protected array $removedScopes Removed global scopes.

Methods

void
__construct(Builder $query)

Create a new Eloquent query builder instance.

$this
withGlobalScope(string $identifier, Scope|Closure $scope)

Register a new global scope.

$this
withoutGlobalScope(Scope|string $scope)

Remove a registered global scope.

$this
withoutGlobalScopes(array $scopes = null)

Remove all or passed registered global scopes.

array
removedScopes()

Get an array of global scopes that were removed from the query.

find(mixed $id, array $columns = ['*'])

Find a model by its primary key.

findMany(array $ids, array $columns = ['*'])

Find multiple models by their primary keys.

findOrFail(mixed $id, array $columns = ['*'])

Find a model by its primary key or throw an exception.

findOrNew(mixed $id, array $columns = ['*'])

Find a model by its primary key or return fresh model instance.

firstOrNew(array $attributes)

Get the first record matching the attributes or instantiate it.

firstOrCreate(array $attributes, array $values = [])

Get the first record matching the attributes or create it.

updateOrCreate(array $attributes, array $values = [])

Create or update a record matching the attributes, and fill it with values.

Model|Builder|null
first(array $columns = ['*'])

Execute the query and get the first result.

firstOrFail(array $columns = ['*'])

Execute the query and get the first result or throw an exception.

get(array $columns = ['*'])

Execute the query as a "select" statement.

mixed
value(string $column)

Get a single column's value from the first result of a query.

cursor()

Get a generator for the given query.

bool
chunk(int $count, callable $callback)

Chunk the results of the query.

bool
chunkById(int $count, callable $callback, string $column = 'id')

Chunk the results of a query by comparing numeric IDs.

bool
each(callable $callback, int $count = 1000)

Execute a callback over each item while chunking.

pluck(string $column, string|null $key = null)

Get an array with the values of a given column.

paginate(int $perPage = null, array $columns = ['*'], string $pageName = 'page', int|null $page = null)

Paginate the given query.

simplePaginate(int $perPage = null, array $columns = ['*'], string $pageName = 'page', int|null $page = null)

Paginate the given query into a simple paginator.

int
update(array $values)

Update a record in the database.

int
increment(string $column, int $amount = 1, array $extra = [])

Increment a column's value by a given amount.

int
decrement(string $column, int $amount = 1, array $extra = [])

Decrement a column's value by a given amount.

array
addUpdatedAtColumn(array $values)

Add the "updated at" column to an array of values.

mixed
delete()

Delete a record from the database.

mixed
forceDelete()

Run the default delete function on the builder.

void
onDelete(Closure $callback)

Register a replacement for the default delete function.

Model[]
getModels(array $columns = ['*'])

Get the hydrated models without eager loading.

array
eagerLoadRelations(array $models)

Eager load the relationships for the models.

array
loadRelation(array $models, string $name, Closure $constraints)

Eagerly load the relationship on a set of models.

getRelation(string $name)

Get the relation instance for the given relation name.

array
nestedRelations(string $relation)

Get the deeply nested relations for a given top-level relation.

bool
isNested(string $name, string $relation)

Determine if the relationship is nested.

$this
when(bool $value, Closure $callback, Closure $default = null)

Apply the callback's query changes if the given "value" is true.

$this
where(string|Closure $column, string $operator = null, mixed $value = null, string $boolean = 'and')

Add a basic where clause to the query.

orWhere(string|Closure $column, string $operator = null, mixed $value = null)

Add an "or where" clause to the query.

has(string $relation, string $operator = '>=', int $count = 1, string $boolean = 'and', Closure $callback = null)

Add a relationship count / exists condition to the query.

hasNested(string $relations, string $operator = '>=', int $count = 1, string $boolean = 'and', Closure|null $callback = null)

Add nested relationship count / exists conditions to the query.

doesntHave(string $relation, string $boolean = 'and', Closure $callback = null)

Add a relationship count / exists condition to the query.

whereHas(string $relation, Closure $callback = null, string $operator = '>=', int $count = 1)

Add a relationship count / exists condition to the query with where clauses.

whereDoesntHave(string $relation, Closure $callback = null)

Add a relationship count / exists condition to the query with where clauses.

orHas(string $relation, string $operator = '>=', int $count = 1)

Add a relationship count / exists condition to the query with an "or".

orWhereHas(string $relation, Closure $callback, string $operator = '>=', int $count = 1)

Add a relationship count / exists condition to the query with where clauses and an "or".

addHasWhere(Builder $hasQuery, Relation $relation, string $operator, int $count, string $boolean)

Add the "has" condition where clause to the query.

bool
shouldRunExistsQuery(string $operator, int $count)

Check if we can run an "exists" query to optimize performance.

$this
whereCountQuery(Builder $query, string $operator = '>=', int $count = 1, string $boolean = 'and')

Add a sub query count clause to the query.

mergeModelDefinedRelationConstraints(Builder $relation)

Merge the constraints from a relation query to the current query.

getHasRelationQuery(string $relation)

Get the "has relation" base query instance.

$this
with(mixed $relations)

Set the relationships that should be eager loaded.

$this
without(mixed $relations)

Prevent the specified relations from being eager loaded.

$this
withCount(mixed $relations)

Add subselect queries to count the relations.

array
parseWithRelations(array $relations)

Parse a list of relations into individuals.

array
parseNestedWith(string $name, array $results)

Parse the nested relationships in a relation.

mixed
scopes(array $scopes)

Add the given scopes to the current builder instance.

mixed
callScope(callable $scope, array $parameters = [])

Apply the given scope on the current builder instance.

applyScopes()

Apply the scopes to the Eloquent builder instance and return it.

bool
shouldNestWheresForScope(Builder $query, int $originalWhereCount)

Determine if the scope added after the given offset should be nested.

void
nestWheresForScope(Builder $query, int $originalWhereCount)

Nest where conditions by slicing them at the given where count.

void
addNestedWhereSlice(Builder $query, array $wheres, int $offset, int $length = null)

Slice where conditions at the given offset and add them to the query as a nested condition.

array
nestWhereSlice(array $whereSlice, string $boolean = 'and')

Create a where array with nested where conditions.

getQuery()

Get the underlying query builder instance.

toBase()

Get a base query builder instance.

$this
setQuery(Builder $query)

Set the underlying query builder instance.

array
getEagerLoads()

Get the relationships being eagerly loaded.

$this
setEagerLoads(array $eagerLoad)

Set the relationships being eagerly loaded.

getModel()

Get the model instance being queried.

$this
setModel(Model $model)

Set a model instance for the model being queried.

void
macro(string $name, Closure $callback)

Extend the builder with a given callback.

getMacro(string $name)

Get the given macro by name.

mixed
__call(string $method, array $parameters)

Dynamically handle calls into the query instance.

void
__clone()

Force a clone of the underlying query builder when cloning.

Details

void __construct(Builder $query)

Create a new Eloquent query builder instance.

Parameters

Builder $query

Return Value

void

$this withGlobalScope(string $identifier, Scope|Closure $scope)

Register a new global scope.

Parameters

string $identifier
Scope|Closure $scope

Return Value

$this

$this withoutGlobalScope(Scope|string $scope)

Remove a registered global scope.

Parameters

Scope|string $scope

Return Value

$this

$this withoutGlobalScopes(array $scopes = null)

Remove all or passed registered global scopes.

Parameters

array $scopes

Return Value

$this

array removedScopes()

Get an array of global scopes that were removed from the query.

Return Value

array

Model|Collection|Builder[]|Builder|null find(mixed $id, array $columns = ['*'])

Find a model by its primary key.

Parameters

mixed $id
array $columns

Return Value

Model|Collection|Builder[]|Builder|null

Collection findMany(array $ids, array $columns = ['*'])

Find multiple models by their primary keys.

Parameters

array $ids
array $columns

Return Value

Collection

Model|Collection findOrFail(mixed $id, array $columns = ['*'])

Find a model by its primary key or throw an exception.

Parameters

mixed $id
array $columns

Return Value

Model|Collection

Exceptions

ModelNotFoundException

Model findOrNew(mixed $id, array $columns = ['*'])

Find a model by its primary key or return fresh model instance.

Parameters

mixed $id
array $columns

Return Value

Model

Model firstOrNew(array $attributes)

Get the first record matching the attributes or instantiate it.

Parameters

array $attributes

Return Value

Model

Model firstOrCreate(array $attributes, array $values = [])

Get the first record matching the attributes or create it.

Parameters

array $attributes
array $values

Return Value

Model

Model updateOrCreate(array $attributes, array $values = [])

Create or update a record matching the attributes, and fill it with values.

Parameters

array $attributes
array $values

Return Value

Model

Model|Builder|null first(array $columns = ['*'])

Execute the query and get the first result.

Parameters

array $columns

Return Value

Model|Builder|null

Model|Builder firstOrFail(array $columns = ['*'])

Execute the query and get the first result or throw an exception.

Parameters

array $columns

Return Value

Model|Builder

Exceptions

ModelNotFoundException

Collection|Builder[] get(array $columns = ['*'])

Execute the query as a "select" statement.

Parameters

array $columns

Return Value

Collection|Builder[]

mixed value(string $column)

Get a single column's value from the first result of a query.

Parameters

string $column

Return Value

mixed

Generator cursor()

Get a generator for the given query.

Return Value

Generator

bool chunk(int $count, callable $callback)

Chunk the results of the query.

Parameters

int $count
callable $callback

Return Value

bool

bool chunkById(int $count, callable $callback, string $column = 'id')

Chunk the results of a query by comparing numeric IDs.

Parameters

int $count
callable $callback
string $column

Return Value

bool

bool each(callable $callback, int $count = 1000)

Execute a callback over each item while chunking.

Parameters

callable $callback
int $count

Return Value

bool

Collection pluck(string $column, string|null $key = null)

Get an array with the values of a given column.

Parameters

string $column
string|null $key

Return Value

Collection

LengthAwarePaginator paginate(int $perPage = null, array $columns = ['*'], string $pageName = 'page', int|null $page = null)

Paginate the given query.

Parameters

int $perPage
array $columns
string $pageName
int|null $page

Return Value

LengthAwarePaginator

Exceptions

InvalidArgumentException

Paginator simplePaginate(int $perPage = null, array $columns = ['*'], string $pageName = 'page', int|null $page = null)

Paginate the given query into a simple paginator.

Parameters

int $perPage
array $columns
string $pageName
int|null $page

Return Value

Paginator

int update(array $values)

Update a record in the database.

Parameters

array $values

Return Value

int

int increment(string $column, int $amount = 1, array $extra = [])

Increment a column's value by a given amount.

Parameters

string $column
int $amount
array $extra

Return Value

int

int decrement(string $column, int $amount = 1, array $extra = [])

Decrement a column's value by a given amount.

Parameters

string $column
int $amount
array $extra

Return Value

int

protected array addUpdatedAtColumn(array $values)

Add the "updated at" column to an array of values.

Parameters

array $values

Return Value

array

mixed delete()

Delete a record from the database.

Return Value

mixed

mixed forceDelete()

Run the default delete function on the builder.

Return Value

mixed

void onDelete(Closure $callback)

Register a replacement for the default delete function.

Parameters

Closure $callback

Return Value

void

Model[] getModels(array $columns = ['*'])

Get the hydrated models without eager loading.

Parameters

array $columns

Return Value

Model[]

array eagerLoadRelations(array $models)

Eager load the relationships for the models.

Parameters

array $models

Return Value

array

protected array loadRelation(array $models, string $name, Closure $constraints)

Eagerly load the relationship on a set of models.

Parameters

array $models
string $name
Closure $constraints

Return Value

array

Relation getRelation(string $name)

Get the relation instance for the given relation name.

Parameters

string $name

Return Value

Relation

protected array nestedRelations(string $relation)

Get the deeply nested relations for a given top-level relation.

Parameters

string $relation

Return Value

array

protected bool isNested(string $name, string $relation)

Determine if the relationship is nested.

Parameters

string $name
string $relation

Return Value

bool

$this when(bool $value, Closure $callback, Closure $default = null)

Apply the callback's query changes if the given "value" is true.

Parameters

bool $value
Closure $callback
Closure $default

Return Value

$this

$this where(string|Closure $column, string $operator = null, mixed $value = null, string $boolean = 'and')

Add a basic where clause to the query.

Parameters

string|Closure $column
string $operator
mixed $value
string $boolean

Return Value

$this

Builder|Builder orWhere(string|Closure $column, string $operator = null, mixed $value = null)

Add an "or where" clause to the query.

Parameters

string|Closure $column
string $operator
mixed $value

Return Value

Builder|Builder

Builder|Builder has(string $relation, string $operator = '>=', int $count = 1, string $boolean = 'and', Closure $callback = null)

Add a relationship count / exists condition to the query.

Parameters

string $relation
string $operator
int $count
string $boolean
Closure $callback

Return Value

Builder|Builder

protected Builder|Builder hasNested(string $relations, string $operator = '>=', int $count = 1, string $boolean = 'and', Closure|null $callback = null)

Add nested relationship count / exists conditions to the query.

Parameters

string $relations
string $operator
int $count
string $boolean
Closure|null $callback

Return Value

Builder|Builder

Builder|Builder doesntHave(string $relation, string $boolean = 'and', Closure $callback = null)

Add a relationship count / exists condition to the query.

Parameters

string $relation
string $boolean
Closure $callback

Return Value

Builder|Builder

Builder|Builder whereHas(string $relation, Closure $callback = null, string $operator = '>=', int $count = 1)

Add a relationship count / exists condition to the query with where clauses.

Parameters

string $relation
Closure $callback
string $operator
int $count

Return Value

Builder|Builder

Builder|Builder whereDoesntHave(string $relation, Closure $callback = null)

Add a relationship count / exists condition to the query with where clauses.

Parameters

string $relation
Closure $callback

Return Value

Builder|Builder

Builder|Builder orHas(string $relation, string $operator = '>=', int $count = 1)

Add a relationship count / exists condition to the query with an "or".

Parameters

string $relation
string $operator
int $count

Return Value

Builder|Builder

Builder|Builder orWhereHas(string $relation, Closure $callback, string $operator = '>=', int $count = 1)

Add a relationship count / exists condition to the query with where clauses and an "or".

Parameters

string $relation
Closure $callback
string $operator
int $count

Return Value

Builder|Builder

protected Builder|Builder addHasWhere(Builder $hasQuery, Relation $relation, string $operator, int $count, string $boolean)

Add the "has" condition where clause to the query.

Parameters

Builder $hasQuery
Relation $relation
string $operator
int $count
string $boolean

Return Value

Builder|Builder

protected bool shouldRunExistsQuery(string $operator, int $count)

Check if we can run an "exists" query to optimize performance.

Parameters

string $operator
int $count

Return Value

bool

protected $this whereCountQuery(Builder $query, string $operator = '>=', int $count = 1, string $boolean = 'and')

Add a sub query count clause to the query.

Parameters

Builder $query
string $operator
int $count
string $boolean

Return Value

$this

Builder|Builder mergeModelDefinedRelationConstraints(Builder $relation)

Merge the constraints from a relation query to the current query.

Parameters

Builder $relation

Return Value

Builder|Builder

protected Relation getHasRelationQuery(string $relation)

Get the "has relation" base query instance.

Parameters

string $relation

Return Value

Relation

$this with(mixed $relations)

Set the relationships that should be eager loaded.

Parameters

mixed $relations

Return Value

$this

$this without(mixed $relations)

Prevent the specified relations from being eager loaded.

Parameters

mixed $relations

Return Value

$this

$this withCount(mixed $relations)

Add subselect queries to count the relations.

Parameters

mixed $relations

Return Value

$this

protected array parseWithRelations(array $relations)

Parse a list of relations into individuals.

Parameters

array $relations

Return Value

array

protected array parseNestedWith(string $name, array $results)

Parse the nested relationships in a relation.

Parameters

string $name
array $results

Return Value

array

mixed scopes(array $scopes)

Add the given scopes to the current builder instance.

Parameters

array $scopes

Return Value

mixed

protected mixed callScope(callable $scope, array $parameters = [])

Apply the given scope on the current builder instance.

Parameters

callable $scope
array $parameters

Return Value

mixed

Builder|Builder applyScopes()

Apply the scopes to the Eloquent builder instance and return it.

Return Value

Builder|Builder

protected bool shouldNestWheresForScope(Builder $query, int $originalWhereCount)

Determine if the scope added after the given offset should be nested.

Parameters

Builder $query
int $originalWhereCount

Return Value

bool

protected void nestWheresForScope(Builder $query, int $originalWhereCount)

Nest where conditions by slicing them at the given where count.

Parameters

Builder $query
int $originalWhereCount

Return Value

void

protected void addNestedWhereSlice(Builder $query, array $wheres, int $offset, int $length = null)

Slice where conditions at the given offset and add them to the query as a nested condition.

Parameters

Builder $query
array $wheres
int $offset
int $length

Return Value

void

protected array nestWhereSlice(array $whereSlice, string $boolean = 'and')

Create a where array with nested where conditions.

Parameters

array $whereSlice
string $boolean

Return Value

array

Builder getQuery()

Get the underlying query builder instance.

Return Value

Builder

Builder toBase()

Get a base query builder instance.

Return Value

Builder

$this setQuery(Builder $query)

Set the underlying query builder instance.

Parameters

Builder $query

Return Value

$this

array getEagerLoads()

Get the relationships being eagerly loaded.

Return Value

array

$this setEagerLoads(array $eagerLoad)

Set the relationships being eagerly loaded.

Parameters

array $eagerLoad

Return Value

$this

Model getModel()

Get the model instance being queried.

Return Value

Model

$this setModel(Model $model)

Set a model instance for the model being queried.

Parameters

Model $model

Return Value

$this

void macro(string $name, Closure $callback)

Extend the builder with a given callback.

Parameters

string $name
Closure $callback

Return Value

void

Closure getMacro(string $name)

Get the given macro by name.

Parameters

string $name

Return Value

Closure

mixed __call(string $method, array $parameters)

Dynamically handle calls into the query instance.

Parameters

string $method
array $parameters

Return Value

mixed

void __clone()

Force a clone of the underlying query builder when cloning.

Return Value

void