Builder

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.
Model|Collection|Builder[]|Builder|null find(mixed $id, array $columns = ['*'])

Find a model by its primary key.
Collection findMany(array $ids, array $columns = ['*'])

Find multiple models by their primary keys.
Model|Collection findOrFail(mixed $id, array $columns = ['*'])

Find a model by its primary key or throw an exception.
Model findOrNew(mixed $id, array $columns = ['*'])

Find a model by its primary key or return fresh model instance.
Model firstOrNew(array $attributes)

Get the first record matching the attributes or instantiate it.
Model firstOrCreate(array $attributes, array $values = [])

Get the first record matching the attributes or create it.
Model 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.
Model|Builder firstOrFail(array $columns = ['*'])

Execute the query and get the first result or throw an exception.
Collection|Builder[] 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.
Generator 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.
Collection pluck(string $column, string|null $key = null)

Get an array with the values of a given column.
LengthAwarePaginator paginate(int $perPage = null, array $columns = ['*'], string $pageName = 'page', int|null $page = null)

Paginate the given query.
Paginator 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.
Relation 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.
Builder|Builder orWhere(string|Closure $column, string $operator = null, mixed $value = null)

Add an "or where" clause to the query.
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.
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.
Builder|Builder doesntHave(string $relation, string $boolean = 'and', Closure $callback = null)

Add a relationship count / exists condition to the query.
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.
Builder|Builder whereDoesntHave(string $relation, Closure $callback = null)

Add a relationship count / exists condition to the query with where clauses.
Builder|Builder orHas(string $relation, string $operator = '>=', int $count = 1)

Add a relationship count / exists condition to the query with an "or".
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".
Builder|Builder 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.
Builder|Builder mergeModelDefinedRelationConstraints(Builder $relation)

Merge the constraints from a relation query to the current query.
Relation 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.
Builder|Builder 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.
Builder getQuery()

Get the underlying query builder instance.
Builder 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.
Model 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.
Closure 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

© Taylor Otwell
Licensed under the MIT License.
Laravel is a trademark of Taylor Otwell.
https://laravel.com/api/5.3/Illuminate/Database/Eloquent/Builder.html