Builder

class Builder (View source)

Traits

BuildsQueries
QueriesRelationships
ExplainsQueries
ForwardsCalls

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.
static protected array $macros All of the globally registered builder macros.
protected array $localMacros All of the locally registered builder macros.
protected Closure $onDelete A replacement for the typical delete function.
protected string[] $passthru The methods that should be returned from query builder.
protected array $scopes Applied global scopes.
protected array $removedScopes Removed global scopes.

Methods

bool chunk(int $count, callable $callback)

Chunk the results of the query.

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

Execute a callback over each item while chunking.

 from BuildsQueries
bool chunkById(int $count, callable $callback, string|null $column = null, string|null $alias = null)

Chunk the results of a query by comparing IDs.

 from BuildsQueries
bool eachById(callable $callback, int $count = 1000, string|null $column = null, string|null $alias = null)

Execute a callback over each item while chunking by ID.

 from BuildsQueries
Model|object|BuildsQueries|null first(array|string $columns = ['*'])

Execute the query and get the first result.

 from BuildsQueries
mixed|$this when(mixed $value, callable $callback, callable|null $default = null)

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

 from BuildsQueries
$this tap(callable $callback)

Pass the query to a given callback.

 from BuildsQueries
mixed|$this unless(mixed $value, callable $callback, callable|null $default = null)

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

 from BuildsQueries
LengthAwarePaginator paginator(Collection $items, int $total, int $perPage, int $currentPage, array $options)

Create a new length-aware paginator instance.

 from BuildsQueries
Paginator simplePaginator(Collection $items, int $perPage, int $currentPage, array $options)

Create a new simple paginator instance.

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

Add a relationship count / exists condition to the query.

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

Add nested relationship count / exists conditions to the query.

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

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

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

Add a relationship count / exists condition to the query.

 from QueriesRelationships
Builder|QueriesRelationships orDoesntHave(string $relation)

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

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

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

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

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

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

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

 from QueriesRelationships
Builder|QueriesRelationships orWhereDoesntHave(string $relation, Closure $callback = null)

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

 from QueriesRelationships
Builder|QueriesRelationships hasMorph(MorphTo|string $relation, string|array $types, string $operator = '>=', int $count = 1, string $boolean = 'and', Closure $callback = null)

Add a polymorphic relationship count / exists condition to the query.

 from QueriesRelationships
BelongsTo getBelongsToRelation(MorphTo $relation, string $type)

Get the BelongsTo relationship for a single polymorphic type.

 from QueriesRelationships
Builder|QueriesRelationships orHasMorph(MorphTo|string $relation, string|array $types, string $operator = '>=', int $count = 1)

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

 from QueriesRelationships
Builder|QueriesRelationships doesntHaveMorph(MorphTo|string $relation, string|array $types, string $boolean = 'and', Closure $callback = null)

Add a polymorphic relationship count / exists condition to the query.

 from QueriesRelationships
Builder|QueriesRelationships orDoesntHaveMorph(MorphTo|string $relation, string|array $types)

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

 from QueriesRelationships
Builder|QueriesRelationships whereHasMorph(MorphTo|string $relation, string|array $types, Closure $callback = null, string $operator = '>=', int $count = 1)

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

 from QueriesRelationships
Builder|QueriesRelationships orWhereHasMorph(MorphTo|string $relation, string|array $types, Closure $callback = null, string $operator = '>=', int $count = 1)

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

 from QueriesRelationships
Builder|QueriesRelationships whereDoesntHaveMorph(MorphTo|string $relation, string|array $types, Closure $callback = null)

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

 from QueriesRelationships
Builder|QueriesRelationships orWhereDoesntHaveMorph(MorphTo|string $relation, string|array $types, Closure $callback = null)

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

 from QueriesRelationships
$this withAggregate(mixed $relations, string $column, string $function = null)

Add subselect queries to include an aggregate value for a relationship.

 from QueriesRelationships
$this withCount(mixed $relations)

Add subselect queries to count the relations.

 from QueriesRelationships
$this withMax(string $relation, string $column)

Add subselect queries to include the max of the relation's column.

 from QueriesRelationships
$this withMin(string $relation, string $column)

Add subselect queries to include the min of the relation's column.

 from QueriesRelationships
$this withSum(string $relation, string $column)

Add subselect queries to include the sum of the relation's column.

 from QueriesRelationships
$this withAvg(string $relation, string $column)

Add subselect queries to include the average of the relation's column.

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

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

 from QueriesRelationships
Builder|QueriesRelationships mergeConstraintsFrom(Builder $from)

Merge the where constraints from another query to the current query.

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

Add a sub-query count clause to this query.

 from QueriesRelationships
Relation getRelationWithoutConstraints(string $relation)

Get the "has relation" base query instance.

 from QueriesRelationships
bool canUseExistsForExistenceCheck(string $operator, int $count)

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

 from QueriesRelationships
Collection explain()

Explains the query.

 from ExplainsQueries
mixed forwardCallTo(mixed $object, string $method, array $parameters)

Forward a method call to the given object.

 from ForwardsCalls
static void throwBadMethodCallException(string $method)

Throw a bad method call exception for the given method.

 from ForwardsCalls
void __construct(Builder $query)

Create a new Eloquent query builder instance.
Model|Builder make(array $attributes = [])

Create and return an un-saved model 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.
$this whereKey(mixed $id)

Add a where clause on the primary key to the query.
$this whereKeyNot(mixed $id)

Add a where clause on the primary key to the query.
$this where(Closure|string|array|Expression $column, mixed $operator = null, mixed $value = null, string $boolean = 'and')

Add a basic where clause to the query.
Model|Builder firstWhere(Closure|string|array|Expression $column, mixed $operator = null, mixed $value = null, string $boolean = 'and')

Add a basic where clause to the query, and return the first result.
$this orWhere(Closure|array|string|Expression $column, mixed $operator = null, mixed $value = null)

Add an "or where" clause to the query.
$this latest(string|Expression $column = null)

Add an "order by" clause for a timestamp to the query.
$this oldest(string|Expression $column = null)

Add an "order by" clause for a timestamp to the query.
Collection hydrate(array $items)

Create a collection of models from plain arrays.
Collection fromQuery(string $query, array $bindings = [])

Create a collection of models from a raw query.
Model|Collection|Builder[]|Builder|null find(mixed $id, array $columns = ['*'])

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

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

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

Find a model by its primary key or return fresh model instance.
Model|Builder firstOrNew(array $attributes = [], array $values = [])

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

Get the first record matching the attributes or create it.
Model|Builder updateOrCreate(array $attributes, array $values = [])

Create or update a record matching the attributes, and fill it with values.
Model|Builder firstOrFail(array $columns = ['*'])

Execute the query and get the first result or throw an exception.
Model|Builder|mixed firstOr(Closure|array $columns = ['*'], Closure $callback = null)

Execute the query and get the first result or call a callback.
mixed value(string|Expression $column)

Get a single column's value from the first result of a query.
Collection|Builder[] get(array|string $columns = ['*'])

Execute the query as a "select" statement.
Model[]|Builder[] getModels(array|string $columns = ['*'])

Get the hydrated models without eager loading.
array eagerLoadRelations(array $models)

Eager load the relationships for the models.
array eagerLoadRelation(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 relationsNestedUnder(string $relation)

Get the deeply nested relations for a given top-level relation.
bool isNestedUnder(string $relation, string $name)

Determine if the relationship is nested.
LazyCollection cursor()

Get a lazy collection for the given query.
void enforceOrderBy()

Add a generic "order by" clause if the query doesn't already have one.
Collection pluck(string|Expression $column, string|null $key = null)

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

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

Paginate the given query into a simple paginator.
Model|$this create(array $attributes = [])

Save a new model and return the instance.
Model|$this forceCreate(array $attributes)

Save a new model and return the instance. Allow mass-assignment.
int update(array $values)

Update records in the database.
int upsert(array $values, array|string $uniqueBy, array|null $update = null)

Insert new records or update the existing ones.
int increment(string|Expression $column, float|int $amount = 1, array $extra = [])

Increment a column's value by a given amount.
int decrement(string|Expression $column, float|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.
array addTimestampsToUpsertValues(array $values)

Add timestamps to the inserted values.
array addUpdatedAtToUpsertColumns(array $update)

Add the "updated at" column to the updated columns.
mixed delete()

Delete records 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.
bool hasNamedScope(string $scope)

Determine if the given model has a scope.
Builder|mixed scopes(array|string $scopes)

Call the given local model scopes.
Builder applyScopes()

Apply the scopes to the Eloquent builder instance and return it.
mixed callScope(callable $scope, array $parameters = [])

Apply the given scope on the current builder instance.
mixed callNamedScope(string $scope, array $parameters = [])

Apply the given named scope on the current builder instance.
void addNewWheresWithinGroup(Builder $query, int $originalWhereCount)

Nest where conditions by slicing them at the given where count.
void groupWhereSliceForScope(Builder $query, array $whereSlice)

Slice where conditions at the given offset and add them to the query as a nested condition.
array createNestedWhere(array $whereSlice, string $boolean = 'and')

Create a where array with nested where conditions.
$this with(string|array $relations, string|Closure|null $callback = null)

Set the relationships that should be eager loaded.
$this without(mixed $relations)

Prevent the specified relations from being eager loaded.
Model|Builder newModelInstance(array $attributes = [])

Create a new instance of the model being queried.
array parseWithRelations(array $relations)

Parse a list of relations into individuals.
array createSelectWithConstraint(string $name)

Create a constraint to select the given columns for the relation.
array addNestedWiths(string $name, array $results)

Parse the nested relationships in a relation.
$this withCasts(array $casts)

Apply query-time casts to the model instance.
Builder getQuery()

Get the underlying query builder instance.
$this setQuery(Builder $query)

Set the underlying query builder instance.
Builder toBase()

Get a base query builder instance.
array getEagerLoads()

Get the relationships being eagerly loaded.
$this setEagerLoads(array $eagerLoad)

Set the relationships being eagerly loaded.
string defaultKeyName()

Get the default key name of the table.
Model|Builder getModel()

Get the model instance being queried.
$this setModel(Model $model)

Set a model instance for the model being queried.
string qualifyColumn(string|Expression $column)

Qualify the given column name by the model's table.
Closure getMacro(string $name)

Get the given macro by name.
bool hasMacro(string $name)

Checks if a macro is registered.
static Closure getGlobalMacro(string $name)

Get the given global macro by name.
static bool hasGlobalMacro(string $name)

Checks if a global macro is registered.
mixed __get(string $key)

Dynamically access builder proxies.
mixed __call(string $method, array $parameters)

Dynamically handle calls into the query instance.
static mixed __callStatic(string $method, array $parameters)

Dynamically handle calls into the query instance.
static void registerMixin(string $mixin, bool $replace)

Register the given mixin with the builder.
void __clone()

Force a clone of the underlying query builder when cloning.

Details

bool chunk(int $count, callable $callback)

Chunk the results of the query.

Parameters

int $count
callable $callback

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

bool chunkById(int $count, callable $callback, string|null $column = null, string|null $alias = null)

Chunk the results of a query by comparing IDs.

Parameters

int $count
callable $callback
string|null $column
string|null $alias

Return Value

bool

bool eachById(callable $callback, int $count = 1000, string|null $column = null, string|null $alias = null)

Execute a callback over each item while chunking by ID.

Parameters

callable $callback
int $count
string|null $column
string|null $alias

Return Value

bool

Model|object|BuildsQueries|null first(array|string $columns = ['*'])

Execute the query and get the first result.

Parameters

array|string $columns

Return Value

Model|object|BuildsQueries|null

mixed|$this when(mixed $value, callable $callback, callable|null $default = null)

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

Parameters

mixed $value
callable $callback
callable|null $default

Return Value

mixed|$this

$this tap(callable $callback)

Pass the query to a given callback.

Parameters

callable $callback

Return Value

$this

mixed|$this unless(mixed $value, callable $callback, callable|null $default = null)

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

Parameters

mixed $value
callable $callback
callable|null $default

Return Value

mixed|$this

protected LengthAwarePaginator paginator(Collection $items, int $total, int $perPage, int $currentPage, array $options)

Create a new length-aware paginator instance.

Parameters

Collection $items
int $total
int $perPage
int $currentPage
array $options

Return Value

LengthAwarePaginator

protected Paginator simplePaginator(Collection $items, int $perPage, int $currentPage, array $options)

Create a new simple paginator instance.

Parameters

Collection $items
int $perPage
int $currentPage
array $options

Return Value

Paginator

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

Add a relationship count / exists condition to the query.

Parameters

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

Return Value

Builder|QueriesRelationships

Exceptions

RuntimeException

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

Add nested relationship count / exists conditions to the query.

Sets up recursive call to whereHas until we finish the nested relation.

Parameters

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

Return Value

Builder|QueriesRelationships

Builder|QueriesRelationships 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|QueriesRelationships

Builder|QueriesRelationships 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|QueriesRelationships

Builder|QueriesRelationships orDoesntHave(string $relation)

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

Parameters

string $relation

Return Value

Builder|QueriesRelationships

Builder|QueriesRelationships 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|QueriesRelationships

Builder|QueriesRelationships orWhereHas(string $relation, Closure $callback = null, 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|QueriesRelationships

Builder|QueriesRelationships 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|QueriesRelationships

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

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

Parameters

string $relation
Closure $callback

Return Value

Builder|QueriesRelationships

Builder|QueriesRelationships hasMorph(MorphTo|string $relation, string|array $types, string $operator = '>=', int $count = 1, string $boolean = 'and', Closure $callback = null)

Add a polymorphic relationship count / exists condition to the query.

Parameters

MorphTo|string $relation
string|array $types
string $operator
int $count
string $boolean
Closure $callback

Return Value

Builder|QueriesRelationships

protected BelongsTo getBelongsToRelation(MorphTo $relation, string $type)

Get the BelongsTo relationship for a single polymorphic type.

Parameters

MorphTo $relation
string $type

Return Value

BelongsTo

Builder|QueriesRelationships orHasMorph(MorphTo|string $relation, string|array $types, string $operator = '>=', int $count = 1)

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

Parameters

MorphTo|string $relation
string|array $types
string $operator
int $count

Return Value

Builder|QueriesRelationships

Builder|QueriesRelationships doesntHaveMorph(MorphTo|string $relation, string|array $types, string $boolean = 'and', Closure $callback = null)

Add a polymorphic relationship count / exists condition to the query.

Parameters

MorphTo|string $relation
string|array $types
string $boolean
Closure $callback

Return Value

Builder|QueriesRelationships

Builder|QueriesRelationships orDoesntHaveMorph(MorphTo|string $relation, string|array $types)

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

Parameters

MorphTo|string $relation
string|array $types

Return Value

Builder|QueriesRelationships

Builder|QueriesRelationships whereHasMorph(MorphTo|string $relation, string|array $types, Closure $callback = null, string $operator = '>=', int $count = 1)

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

Parameters

MorphTo|string $relation
string|array $types
Closure $callback
string $operator
int $count

Return Value

Builder|QueriesRelationships

Builder|QueriesRelationships orWhereHasMorph(MorphTo|string $relation, string|array $types, Closure $callback = null, string $operator = '>=', int $count = 1)

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

Parameters

MorphTo|string $relation
string|array $types
Closure $callback
string $operator
int $count

Return Value

Builder|QueriesRelationships

Builder|QueriesRelationships whereDoesntHaveMorph(MorphTo|string $relation, string|array $types, Closure $callback = null)

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

Parameters

MorphTo|string $relation
string|array $types
Closure $callback

Return Value

Builder|QueriesRelationships

Builder|QueriesRelationships orWhereDoesntHaveMorph(MorphTo|string $relation, string|array $types, Closure $callback = null)

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

Parameters

MorphTo|string $relation
string|array $types
Closure $callback

Return Value

Builder|QueriesRelationships

$this withAggregate(mixed $relations, string $column, string $function = null)

Add subselect queries to include an aggregate value for a relationship.

Parameters

mixed $relations
string $column
string $function

Return Value

$this

$this withCount(mixed $relations)

Add subselect queries to count the relations.

Parameters

mixed $relations

Return Value

$this

$this withMax(string $relation, string $column)

Add subselect queries to include the max of the relation's column.

Parameters

string $relation
string $column

Return Value

$this

$this withMin(string $relation, string $column)

Add subselect queries to include the min of the relation's column.

Parameters

string $relation
string $column

Return Value

$this

$this withSum(string $relation, string $column)

Add subselect queries to include the sum of the relation's column.

Parameters

string $relation
string $column

Return Value

$this

$this withAvg(string $relation, string $column)

Add subselect queries to include the average of the relation's column.

Parameters

string $relation
string $column

Return Value

$this

protected Builder|QueriesRelationships 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|QueriesRelationships

Builder|QueriesRelationships mergeConstraintsFrom(Builder $from)

Merge the where constraints from another query to the current query.

Parameters

Builder $from

Return Value

Builder|QueriesRelationships

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

Add a sub-query count clause to this query.

Parameters

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

Return Value

$this

protected Relation getRelationWithoutConstraints(string $relation)

Get the "has relation" base query instance.

Parameters

string $relation

Return Value

Relation

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

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

Parameters

string $operator
int $count

Return Value

bool

Collection explain()

Explains the query.

Return Value

Collection

protected mixed forwardCallTo(mixed $object, string $method, array $parameters)

Forward a method call to the given object.

Parameters

mixed $object
string $method
array $parameters

Return Value

mixed

Exceptions

BadMethodCallException

static protected void throwBadMethodCallException(string $method)

Throw a bad method call exception for the given method.

Parameters

string $method

Return Value

void

Exceptions

BadMethodCallException

void __construct(Builder $query)

Create a new Eloquent query builder instance.

Parameters

Builder $query

Return Value

void

Model|Builder make(array $attributes = [])

Create and return an un-saved model instance.

Parameters

array $attributes

Return Value

Model|Builder

$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

$this whereKey(mixed $id)

Add a where clause on the primary key to the query.

Parameters

mixed $id

Return Value

$this

$this whereKeyNot(mixed $id)

Add a where clause on the primary key to the query.

Parameters

mixed $id

Return Value

$this

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

Add a basic where clause to the query.

Parameters

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

Return Value

$this

Model|Builder firstWhere(Closure|string|array|Expression $column, mixed $operator = null, mixed $value = null, string $boolean = 'and')

Add a basic where clause to the query, and return the first result.

Parameters

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

Return Value

Model|Builder

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

Add an "or where" clause to the query.

Parameters

Closure|array|string|Expression $column
mixed $operator
mixed $value

Return Value

$this

$this latest(string|Expression $column = null)

Add an "order by" clause for a timestamp to the query.

Parameters

string|Expression $column

Return Value

$this

$this oldest(string|Expression $column = null)

Add an "order by" clause for a timestamp to the query.

Parameters

string|Expression $column

Return Value

$this

Collection hydrate(array $items)

Create a collection of models from plain arrays.

Parameters

array $items

Return Value

Collection

Collection fromQuery(string $query, array $bindings = [])

Create a collection of models from a raw query.

Parameters

string $query
array $bindings

Return Value

Collection

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(Arrayable|array $ids, array $columns = ['*'])

Find multiple models by their primary keys.

Parameters

Arrayable|array $ids
array $columns

Return Value

Collection

Model|Collection|Builder|Builder[] 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|Builder|Builder[]

Exceptions

ModelNotFoundException

Model|Builder 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|Builder

Model|Builder firstOrNew(array $attributes = [], array $values = [])

Get the first record matching the attributes or instantiate it.

Parameters

array $attributes
array $values

Return Value

Model|Builder

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

Get the first record matching the attributes or create it.

Parameters

array $attributes
array $values

Return Value

Model|Builder

Model|Builder 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|Builder

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

Model|Builder|mixed firstOr(Closure|array $columns = ['*'], Closure $callback = null)

Execute the query and get the first result or call a callback.

Parameters

Closure|array $columns
Closure $callback

Return Value

Model|Builder|mixed

mixed value(string|Expression $column)

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

Parameters

string|Expression $column

Return Value

mixed

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

Execute the query as a "select" statement.

Parameters

array|string $columns

Return Value

Collection|Builder[]

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

Get the hydrated models without eager loading.

Parameters

array|string $columns

Return Value

Model[]|Builder[]

array eagerLoadRelations(array $models)

Eager load the relationships for the models.

Parameters

array $models

Return Value

array

protected array eagerLoadRelation(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 relationsNestedUnder(string $relation)

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

Parameters

string $relation

Return Value

array

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

Determine if the relationship is nested.

Parameters

string $relation
string $name

Return Value

bool

LazyCollection cursor()

Get a lazy collection for the given query.

Return Value

LazyCollection

protected void enforceOrderBy()

Add a generic "order by" clause if the query doesn't already have one.

Return Value

void

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

Get an array with the values of a given column.

Parameters

string|Expression $column
string|null $key

Return Value

Collection

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

Paginate the given query.

Parameters

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

Return Value

LengthAwarePaginator

Exceptions

InvalidArgumentException

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

Paginate the given query into a simple paginator.

Parameters

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

Return Value

Paginator

Model|$this create(array $attributes = [])

Save a new model and return the instance.

Parameters

array $attributes

Return Value

Model|$this

Model|$this forceCreate(array $attributes)

Save a new model and return the instance. Allow mass-assignment.

Parameters

array $attributes

Return Value

Model|$this

int update(array $values)

Update records in the database.

Parameters

array $values

Return Value

int

int upsert(array $values, array|string $uniqueBy, array|null $update = null)

Insert new records or update the existing ones.

Parameters

array $values
array|string $uniqueBy
array|null $update

Return Value

int

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

Increment a column's value by a given amount.

Parameters

string|Expression $column
float|int $amount
array $extra

Return Value

int

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

Decrement a column's value by a given amount.

Parameters

string|Expression $column
float|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

protected array addTimestampsToUpsertValues(array $values)

Add timestamps to the inserted values.

Parameters

array $values

Return Value

array

protected array addUpdatedAtToUpsertColumns(array $update)

Add the "updated at" column to the updated columns.

Parameters

array $update

Return Value

array

mixed delete()

Delete records from the database.

Return Value

mixed

mixed forceDelete()

Run the default delete function on the builder.

Since we do not apply scopes here, the row will actually be deleted.

Return Value

mixed

void onDelete(Closure $callback)

Register a replacement for the default delete function.

Parameters

Closure $callback

Return Value

void

bool hasNamedScope(string $scope)

Determine if the given model has a scope.

Parameters

string $scope

Return Value

bool

Builder|mixed scopes(array|string $scopes)

Call the given local model scopes.

Parameters

array|string $scopes

Return Value

Builder|mixed

Builder applyScopes()

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

Return Value

Builder

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

Apply the given scope on the current builder instance.

Parameters

callable $scope
array $parameters

Return Value

mixed

protected mixed callNamedScope(string $scope, array $parameters = [])

Apply the given named scope on the current builder instance.

Parameters

string $scope
array $parameters

Return Value

mixed

protected void addNewWheresWithinGroup(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 groupWhereSliceForScope(Builder $query, array $whereSlice)

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

Parameters

Builder $query
array $whereSlice

Return Value

void

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

Create a where array with nested where conditions.

Parameters

array $whereSlice
string $boolean

Return Value

array

$this with(string|array $relations, string|Closure|null $callback = null)

Set the relationships that should be eager loaded.

Parameters

string|array $relations
string|Closure|null $callback

Return Value

$this

$this without(mixed $relations)

Prevent the specified relations from being eager loaded.

Parameters

mixed $relations

Return Value

$this

Model|Builder newModelInstance(array $attributes = [])

Create a new instance of the model being queried.

Parameters

array $attributes

Return Value

Model|Builder

protected array parseWithRelations(array $relations)

Parse a list of relations into individuals.

Parameters

array $relations

Return Value

array

protected array createSelectWithConstraint(string $name)

Create a constraint to select the given columns for the relation.

Parameters

string $name

Return Value

array

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

Parse the nested relationships in a relation.

Parameters

string $name
array $results

Return Value

array

$this withCasts(array $casts)

Apply query-time casts to the model instance.

Parameters

array $casts

Return Value

$this

Builder getQuery()

Get the underlying query builder instance.

Return Value

Builder

$this setQuery(Builder $query)

Set the underlying query builder instance.

Parameters

Builder $query

Return Value

$this

Builder toBase()

Get a base query builder instance.

Return Value

Builder

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

protected string defaultKeyName()

Get the default key name of the table.

Return Value

string

Model|Builder getModel()

Get the model instance being queried.

Return Value

Model|Builder

$this setModel(Model $model)

Set a model instance for the model being queried.

Parameters

Model $model

Return Value

$this

string qualifyColumn(string|Expression $column)

Qualify the given column name by the model's table.

Parameters

string|Expression $column

Return Value

string

Closure getMacro(string $name)

Get the given macro by name.

Parameters

string $name

Return Value

Closure

bool hasMacro(string $name)

Checks if a macro is registered.

Parameters

string $name

Return Value

bool

static Closure getGlobalMacro(string $name)

Get the given global macro by name.

Parameters

string $name

Return Value

Closure

static bool hasGlobalMacro(string $name)

Checks if a global macro is registered.

Parameters

string $name

Return Value

bool

mixed __get(string $key)

Dynamically access builder proxies.

Parameters

string $key

Return Value

mixed

Exceptions

Exception

mixed __call(string $method, array $parameters)

Dynamically handle calls into the query instance.

Parameters

string $method
array $parameters

Return Value

mixed

static mixed __callStatic(string $method, array $parameters)

Dynamically handle calls into the query instance.

Parameters

string $method
array $parameters

Return Value

mixed

Exceptions

BadMethodCallException

static protected void registerMixin(string $mixin, bool $replace)

Register the given mixin with the builder.

Parameters

string $mixin
bool $replace

Return Value

void

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/8.x/Illuminate/Database/Eloquent/Builder.html