class Builder implements Builder mixin Builder (View source)

Traits

Properties

protected Builder $query

The base query builder instance.

protected TModel $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[] $propertyPassthru

The properties that should be returned from query builder.

protected string[] $passthru

The methods that should be returned from query builder.

protected array $scopes

Applied global scopes.

protected array $removedScopes

Removed global scopes.

protected array $afterQueryCallbacks

The callbacks that should be invoked after retrieving data from the database.

HigherOrderBuilderProxy read-only $orWhere
HigherOrderBuilderProxy read-only $whereNot
HigherOrderBuilderProxy read-only $orWhereNot

Methods

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

Apply the callback if the given "value" is (or resolves to) truthy.

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

Apply the callback if the given "value" is (or resolves to) falsy.

bool
chunk(int $count, callable $callback)

Chunk the results of the query.

TReturn>
chunkMap(callable $callback, int $count = 1000)

Run a map over each item while chunking.

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

Execute a callback over each item while chunking.

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

Chunk the results of a query by comparing IDs.

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

Chunk the results of a query by comparing IDs in descending order.

bool
orderedChunkById(int $count, callable $callback, string|null $column = null, string|null $alias = null, bool $descending = false)

Chunk the results of a query by comparing IDs in a given order.

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.

lazy(int $chunkSize = 1000)

Query lazily, by chunks of the given size.

lazyById(int $chunkSize = 1000, string|null $column = null, string|null $alias = null)

Query lazily, by chunking the results of a query by comparing IDs.

lazyByIdDesc(int $chunkSize = 1000, string|null $column = null, string|null $alias = null)

Query lazily, by chunking the results of a query by comparing IDs in descending order.

orderedLazyById(int $chunkSize = 1000, string|null $column = null, string|null $alias = null, bool $descending = false)

Query lazily, by chunking the results of a query by comparing IDs in a given order.

TValue|null
first(array|string $columns = ['*'])

Execute the query and get the first result.

TModel
firstOrFail(array|string $columns = ['*'])

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

TModel
sole(array|string $columns = ['*'])

Execute the query and get the first result if it's the sole matching record.

paginateUsingCursor(int $perPage, array|string $columns = ['*'], string $cursorName = 'cursor', Cursor|string|null $cursor = null)

Paginate the given query using a cursor paginator.

string
getOriginalColumnNameForCursorPagination($builder, string $parameter)

Get the original column name of the given column, without any aliasing.

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

Create a new length-aware paginator instance.

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

Create a new simple paginator instance.

cursorPaginator(Collection $items, int $perPage, Cursor $cursor, array $options)

Create a new cursor paginator instance.

$this
tap($callback)

Pass the query to a given callback.

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

Forward a method call to the given object.

mixed
forwardDecoratedCallTo(mixed $object, string $method, array $parameters)

Forward a method call to the given object, returning $this if the forwarded call returned itself.

static never
throwBadMethodCallException(string $method)

Throw a bad method call exception for the given method.

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

Add a relationship count / exists condition to the query.

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

Add nested relationship count / exists conditions to the query.

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

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

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

Add a relationship count / exists condition to the query.

$this
orDoesntHave($relation)

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

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

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

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

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

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

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

$this
whereDoesntHave($relation, Closure|null $callback = null)

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

$this
orWhereDoesntHave($relation, Closure|null $callback = null)

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

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

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

TDeclaringModel>
getBelongsToRelation(MorphTo $relation, TRelatedModel> $type)

Get the BelongsTo relationship for a single polymorphic type.

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

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

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

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

$this
orDoesntHaveMorph($relation, string|array $types)

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

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

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

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

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

$this
whereDoesntHaveMorph($relation, string|array $types, Closure|null $callback = null)

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

$this
orWhereDoesntHaveMorph($relation, string|array $types, Closure|null $callback = null)

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

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

Add a basic where clause to a relationship query.

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

Add an "or where" clause to a relationship query.

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

Add a polymorphic relationship condition to the query with a where clause.

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

Add a polymorphic relationship condition to the query with an "or where" clause.

$this
whereMorphedTo($relation, Model|string|null $model, $boolean = 'and')

Add a morph-to relationship condition to the query.

$this
whereNotMorphedTo($relation, Model|string $model, $boolean = 'and')

Add a not morph-to relationship condition to the query.

$this
orWhereMorphedTo($relation, Model|string|null $model)

Add a morph-to relationship condition to the query with an "or where" clause.

$this
orWhereNotMorphedTo($relation, Model|string $model)

Add a not morph-to relationship condition to the query with an "or where" clause.

$this
whereBelongsTo(Model|Model> $related, string|null $relationshipName = null, string $boolean = 'and')

Add a "belongs to" relationship where clause to the query.

$this
orWhereBelongsTo(Model $related, string|null $relationshipName = null)

Add a "BelongsTo" relationship with an "or where" clause to the query.

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

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

string
getRelationHashedColumn(string $column, $relation)

Get the relation hashed column name for the given column and relation.

$this
withCount(mixed $relations)

Add subselect queries to count the relations.

$this
withMax(string|array $relation, Expression|string $column)

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

$this
withMin(string|array $relation, Expression|string $column)

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

$this
withSum(string|array $relation, Expression|string $column)

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

$this
withAvg(string|array $relation, Expression|string $column)

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

$this
withExists(string|array $relation)

Add subselect queries to include the existence of related models.

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

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

$this
mergeConstraintsFrom(Builder $from)

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

array
requalifyWhereTables(array $wheres, string $from, string $to)

Updates the table name for any columns with a new qualified name.

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

Add a sub-query count clause to this query.

getRelationWithoutConstraints(string $relation)

Get the "has relation" base query instance.

bool
canUseExistsForExistenceCheck(string $operator, int $count)

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

void
__construct(Builder $query)

Create a new Eloquent query builder instance.

TModel
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|null $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($column, mixed $operator = null, mixed $value = null, string $boolean = 'and')

Add a basic where clause to the query.

TModel|null
firstWhere($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($column, mixed $operator = null, mixed $value = null)

Add an "or where" clause to the query.

$this
whereNot($column, mixed $operator = null, mixed $value = null, string $boolean = 'and')

Add a basic "where not" clause to the query.

$this
orWhereNot($column, mixed $operator = null, mixed $value = null)

Add an "or where not" 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.

TModel>
hydrate(array $items)

Create a collection of models from plain arrays.

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

Create a collection of models from a raw query.

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

Find a model by its primary key.

TModel>
findMany(Arrayable|array $ids, array|string $columns = ['*'])

Find multiple models by their primary keys.

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

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

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

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

findOr($id, $columns = ['*'], Closure|null $callback = null)

No description

TModel
firstOrNew(array $attributes = [], array $values = [])

Get the first record matching the attributes or instantiate it.

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

Get the first record matching the attributes. If the record is not found, create it.

TModel
createOrFirst(array $attributes = [], array $values = [])

Attempt to create the record. If a unique constraint violation occurs, attempt to find the matching record.

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

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

firstOr($columns = ['*'], Closure|null $callback = null)

No description

mixed
value(string|Expression $column)

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

mixed
soleValue(string|Expression $column)

Get a single column's value from the first result of a query if it's the sole matching record.

mixed
valueOrFail(string|Expression $column)

Get a single column's value from the first result of the query or throw an exception.

TModel>
get(array|string $columns = ['*'])

Execute the query as a "select" statement.

TModel>
getModels(array|string $columns = ['*'])

Get the hydrated models without eager loading.

TModel>
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.

getRelation($name)

No description

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.

$this
afterQuery(Closure $callback)

Register a closure to be invoked after the query is executed.

mixed
applyAfterQueryCallbacks(mixed $result)

Invoke the "after query" modification callbacks.

TModel>
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<array-key,mixed>
pluck(string|Expression $column, string|null $key = null)

Get a collection with the values of a given column.

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

Paginate the given query.

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

Paginate the given query into a simple paginator.

cursorPaginate(int|null $perPage = null, array|string $columns = ['*'], string $cursorName = 'cursor', Cursor|string|null $cursor = null)

Paginate the given query into a cursor paginator.

ensureOrderForCursorPagination(bool $shouldReverse = false)

Ensure the proper order by required for cursor pagination.

TModel
create(array $attributes = [])

Save a new model and return the instance.

TModel
createQuietly(array $attributes = [])

Save a new model and return the instance without raising model events.

TModel
forceCreate(array $attributes)

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

TModel
forceCreateQuietly(array $attributes = [])

Save a new model instance with mass assignment without raising model events.

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|false
touch(string|null $column = null)

Update the column's update timestamp.

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
addUniqueIdsToUpsertValues(array $values)

Add unique IDs to the inserted 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.

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($relations, $callback = null)

Set the relationships that should be eager loaded.

$this
without(mixed $relations)

Prevent the specified relations from being eager loaded.

$this
withOnly($relations)

Set the relationships that should be eager loaded while removing any previously added eager loading specifications.

TModel
newModelInstance(array $attributes = [])

Create a new instance of the model being queried.

array
parseWithRelations(array $relations)

Parse a list of relations into individuals.

array
prepareNestedWithRelationships(array $relations, string $prefix = '')

Prepare nested with relationships.

combineConstraints(array $constraints)

Combine an array of constraints into a single constraint.

array
parseNameAndAttributeSelectionConstraint(string $name)

Parse the attribute select constraints from the name.

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.

mixed
withSavepointIfNeeded(Closure $scope)

No description

getUnionBuilders()

Get the Eloquent builder instances that are used in the union of the query.

getQuery()

Get the underlying query builder instance.

$this
setQuery(Builder $query)

Set the underlying query builder instance.

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.

$this
withoutEagerLoad(array $relations)

Indicate that the given relationships should not be eagerly loaded.

$this
withoutEagerLoads()

Flush the relationships being eagerly loaded.

mixed
getLimit()

Get the "limit" value from the query or null if it's not set.

mixed
getOffset()

Get the "offset" value from the query or null if it's not set.

string
defaultKeyName()

Get the default key name of the table.

TModel
getModel()

Get the model instance being queried.

setModel(Model $model)

No description

string
qualifyColumn(string|Expression $column)

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

array
qualifyColumns(array|Expression $columns)

Qualify the given columns with the model's table.

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.

clone()

Clone the Eloquent query builder.

void
__clone()

Force a clone of the underlying query builder when cloning.

Details

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

Apply the callback if the given "value" is (or resolves to) truthy.

Parameters

$value
callable|null $callback
callable|null $default

Return Value

$this|TWhenReturnType

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

Apply the callback if the given "value" is (or resolves to) falsy.

Parameters

$value
callable|null $callback
callable|null $default

Return Value

$this|TUnlessReturnType

bool chunk(int $count, callable $callback)

Chunk the results of the query.

Parameters

int $count
callable $callback

Return Value

bool

TReturn> chunkMap(callable $callback, int $count = 1000)

Run a map over each item while chunking.

Parameters

callable $callback
int $count

Return Value

TReturn>

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

Execute a callback over each item while chunking.

Parameters

callable $callback
int $count

Return Value

bool

Exceptions

RuntimeException

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 chunkByIdDesc(int $count, callable $callback, string|null $column = null, string|null $alias = null)

Chunk the results of a query by comparing IDs in descending order.

Parameters

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

Return Value

bool

bool orderedChunkById(int $count, callable $callback, string|null $column = null, string|null $alias = null, bool $descending = false)

Chunk the results of a query by comparing IDs in a given order.

Parameters

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

Return Value

bool

Exceptions

RuntimeException

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

LazyCollection lazy(int $chunkSize = 1000)

Query lazily, by chunks of the given size.

Parameters

int $chunkSize

Return Value

LazyCollection

Exceptions

InvalidArgumentException

LazyCollection lazyById(int $chunkSize = 1000, string|null $column = null, string|null $alias = null)

Query lazily, by chunking the results of a query by comparing IDs.

Parameters

int $chunkSize
string|null $column
string|null $alias

Return Value

LazyCollection

Exceptions

InvalidArgumentException

LazyCollection lazyByIdDesc(int $chunkSize = 1000, string|null $column = null, string|null $alias = null)

Query lazily, by chunking the results of a query by comparing IDs in descending order.

Parameters

int $chunkSize
string|null $column
string|null $alias

Return Value

LazyCollection

Exceptions

InvalidArgumentException

protected LazyCollection orderedLazyById(int $chunkSize = 1000, string|null $column = null, string|null $alias = null, bool $descending = false)

Query lazily, by chunking the results of a query by comparing IDs in a given order.

Parameters

int $chunkSize
string|null $column
string|null $alias
bool $descending

Return Value

LazyCollection

Exceptions

InvalidArgumentException

TValue|null first(array|string $columns = ['*'])

Execute the query and get the first result.

Parameters

array|string $columns

Return Value

TValue|null

TModel firstOrFail(array|string $columns = ['*'])

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

Parameters

array|string $columns

Return Value

TModel

Exceptions

TModel>

TModel sole(array|string $columns = ['*'])

Execute the query and get the first result if it's the sole matching record.

Parameters

array|string $columns

Return Value

TModel

Exceptions

TModel>
MultipleRecordsFoundException

protected CursorPaginator paginateUsingCursor(int $perPage, array|string $columns = ['*'], string $cursorName = 'cursor', Cursor|string|null $cursor = null)

Paginate the given query using a cursor paginator.

Parameters

int $perPage
array|string $columns
string $cursorName
Cursor|string|null $cursor

Return Value

CursorPaginator

protected string getOriginalColumnNameForCursorPagination($builder, string $parameter)

Get the original column name of the given column, without any aliasing.

Parameters

$builder
string $parameter

Return Value

string

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

protected CursorPaginator cursorPaginator(Collection $items, int $perPage, Cursor $cursor, array $options)

Create a new cursor paginator instance.

Parameters

Collection $items
int $perPage
Cursor $cursor
array $options

Return Value

CursorPaginator

$this tap($callback)

Pass the query to a given callback.

Parameters

$callback

Return Value

$this

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

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

Forward a method call to the given object, returning $this if the forwarded call returned itself.

Parameters

mixed $object
string $method
array $parameters

Return Value

mixed

Exceptions

BadMethodCallException

static protected never throwBadMethodCallException(string $method)

Throw a bad method call exception for the given method.

Parameters

string $method

Return Value

never

Exceptions

BadMethodCallException

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

Add a relationship count / exists condition to the query.

Parameters

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

Return Value

$this

Exceptions

RuntimeException

protected $this 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

$this

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

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

Parameters

$relation
string $operator
int $count

Return Value

$this

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

Add a relationship count / exists condition to the query.

Parameters

$relation
string $boolean
Closure|null $callback

Return Value

$this

$this orDoesntHave($relation)

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

Parameters

$relation

Return Value

$this

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

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

Parameters

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

Return Value

$this

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

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

Also load the relationship with same condition.

Parameters

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

Return Value

$this

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

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

Parameters

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

Return Value

$this

$this whereDoesntHave($relation, Closure|null $callback = null)

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

Parameters

$relation
Closure|null $callback

Return Value

$this

$this orWhereDoesntHave($relation, Closure|null $callback = null)

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

Parameters

$relation
Closure|null $callback

Return Value

$this

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

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

Parameters

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

Return Value

$this

protected TDeclaringModel> getBelongsToRelation(MorphTo $relation, TRelatedModel> $type)

Get the BelongsTo relationship for a single polymorphic type.

Parameters

MorphTo $relation
TRelatedModel> $type

Return Value

TDeclaringModel>

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

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

Parameters

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

Return Value

$this

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

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

Parameters

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

Return Value

$this

$this orDoesntHaveMorph($relation, string|array $types)

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

Parameters

$relation
string|array $types

Return Value

$this

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

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

Parameters

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

Return Value

$this

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

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

Parameters

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

Return Value

$this

$this whereDoesntHaveMorph($relation, string|array $types, Closure|null $callback = null)

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

Parameters

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

Return Value

$this

$this orWhereDoesntHaveMorph($relation, string|array $types, Closure|null $callback = null)

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

Parameters

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

Return Value

$this

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

Add a basic where clause to a relationship query.

Parameters

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

Return Value

$this

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

Add an "or where" clause to a relationship query.

Parameters

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

Return Value

$this

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

Add a polymorphic relationship condition to the query with a where clause.

Parameters

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

Return Value

$this

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

Add a polymorphic relationship condition to the query with an "or where" clause.

Parameters

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

Return Value

$this

$this whereMorphedTo($relation, Model|string|null $model, $boolean = 'and')

Add a morph-to relationship condition to the query.

Parameters

$relation
Model|string|null $model
$boolean

Return Value

$this

$this whereNotMorphedTo($relation, Model|string $model, $boolean = 'and')

Add a not morph-to relationship condition to the query.

Parameters

$relation
Model|string $model
$boolean

Return Value

$this

$this orWhereMorphedTo($relation, Model|string|null $model)

Add a morph-to relationship condition to the query with an "or where" clause.

Parameters

$relation
Model|string|null $model

Return Value

$this

$this orWhereNotMorphedTo($relation, Model|string $model)

Add a not morph-to relationship condition to the query with an "or where" clause.

Parameters

$relation
Model|string $model

Return Value

$this

$this whereBelongsTo(Model|Model> $related, string|null $relationshipName = null, string $boolean = 'and')

Add a "belongs to" relationship where clause to the query.

Parameters

Model|Model> $related
string|null $relationshipName
string $boolean

Return Value

$this

Exceptions

RelationNotFoundException

$this orWhereBelongsTo(Model $related, string|null $relationshipName = null)

Add a "BelongsTo" relationship with an "or where" clause to the query.

Parameters

Model $related
string|null $relationshipName

Return Value

$this

Exceptions

RuntimeException

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

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

Parameters

mixed $relations
Expression|string $column
string $function

Return Value

$this

protected string getRelationHashedColumn(string $column, $relation)

Get the relation hashed column name for the given column and relation.

Parameters

string $column
$relation

Return Value

string

$this withCount(mixed $relations)

Add subselect queries to count the relations.

Parameters

mixed $relations

Return Value

$this

$this withMax(string|array $relation, Expression|string $column)

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

Parameters

string|array $relation
Expression|string $column

Return Value

$this

$this withMin(string|array $relation, Expression|string $column)

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

Parameters

string|array $relation
Expression|string $column

Return Value

$this

$this withSum(string|array $relation, Expression|string $column)

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

Parameters

string|array $relation
Expression|string $column

Return Value

$this

$this withAvg(string|array $relation, Expression|string $column)

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

Parameters

string|array $relation
Expression|string $column

Return Value

$this

$this withExists(string|array $relation)

Add subselect queries to include the existence of related models.

Parameters

string|array $relation

Return Value

$this

protected $this 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

$this

$this mergeConstraintsFrom(Builder $from)

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

Parameters

Builder $from

Return Value

$this

protected array requalifyWhereTables(array $wheres, string $from, string $to)

Updates the table name for any columns with a new qualified name.

Parameters

array $wheres
string $from
string $to

Return Value

array

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 getRelationWithoutConstraints(string $relation)

Get the "has relation" base query instance.

Parameters

string $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

void __construct(Builder $query)

Create a new Eloquent query builder instance.

Parameters

Builder $query

Return Value

void

TModel make(array $attributes = [])

Create and return an un-saved model instance.

Parameters

array $attributes

Return Value

TModel

$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|null $scopes = null)

Remove all or passed registered global scopes.

Parameters

array|null $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($column, mixed $operator = null, mixed $value = null, string $boolean = 'and')

Add a basic where clause to the query.

Parameters

$column
mixed $operator
mixed $value
string $boolean

Return Value

$this

TModel|null firstWhere($column, mixed $operator = null, mixed $value = null, string $boolean = 'and')

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

Parameters

$column
mixed $operator
mixed $value
string $boolean

Return Value

TModel|null

$this orWhere($column, mixed $operator = null, mixed $value = null)

Add an "or where" clause to the query.

Parameters

$column
mixed $operator
mixed $value

Return Value

$this

$this whereNot($column, mixed $operator = null, mixed $value = null, string $boolean = 'and')

Add a basic "where not" clause to the query.

Parameters

$column
mixed $operator
mixed $value
string $boolean

Return Value

$this

$this orWhereNot($column, mixed $operator = null, mixed $value = null)

Add an "or where not" clause to the query.

Parameters

$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

TModel> hydrate(array $items)

Create a collection of models from plain arrays.

Parameters

array $items

Return Value

TModel>

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

Create a collection of models from a raw query.

Parameters

string $query
array $bindings

Return Value

TModel>

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

Find a model by its primary key.

Parameters

mixed $id
array|string $columns

TModel> findMany(Arrayable|array $ids, array|string $columns = ['*'])

Find multiple models by their primary keys.

Parameters

Arrayable|array $ids
array|string $columns

Return Value

TModel>

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

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

Parameters

mixed $id
array|string $columns

Exceptions

TModel>

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

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

Parameters

mixed $id
array|string $columns

findOr($id, $columns = ['*'], Closure|null $callback = null)

No description

Parameters

$id
$columns
Closure|null $callback

TModel firstOrNew(array $attributes = [], array $values = [])

Get the first record matching the attributes or instantiate it.

Parameters

array $attributes
array $values

Return Value

TModel

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

Get the first record matching the attributes. If the record is not found, create it.

Parameters

array $attributes
array $values

Return Value

TModel

TModel createOrFirst(array $attributes = [], array $values = [])

Attempt to create the record. If a unique constraint violation occurs, attempt to find the matching record.

Parameters

array $attributes
array $values

Return Value

TModel

TModel 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

TModel

firstOr($columns = ['*'], Closure|null $callback = null)

No description

Parameters

$columns
Closure|null $callback

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

mixed soleValue(string|Expression $column)

Get a single column's value from the first result of a query if it's the sole matching record.

Parameters

string|Expression $column

Return Value

mixed

Exceptions

TModel>
MultipleRecordsFoundException

mixed valueOrFail(string|Expression $column)

Get a single column's value from the first result of the query or throw an exception.

Parameters

string|Expression $column

Return Value

mixed

Exceptions

TModel>

TModel> get(array|string $columns = ['*'])

Execute the query as a "select" statement.

Parameters

array|string $columns

Return Value

TModel>

TModel> getModels(array|string $columns = ['*'])

Get the hydrated models without eager loading.

Parameters

array|string $columns

Return Value

TModel>

TModel> eagerLoadRelations(array $models)

Eager load the relationships for the models.

Parameters

array $models

Return Value

TModel>

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

getRelation($name)

No description

Parameters

$name

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

$this afterQuery(Closure $callback)

Register a closure to be invoked after the query is executed.

Parameters

Closure $callback

Return Value

$this

mixed applyAfterQueryCallbacks(mixed $result)

Invoke the "after query" modification callbacks.

Parameters

mixed $result

Return Value

mixed

TModel> cursor()

Get a lazy collection for the given query.

Return Value

TModel>

protected void enforceOrderBy()

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

Return Value

void

Collection<array-key,mixed> pluck(string|Expression $column, string|null $key = null)

Get a collection with the values of a given column.

Parameters

string|Expression $column
string|null $key

Return Value

Collection<array-key,mixed>

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

Paginate the given query.

Parameters

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

Return Value

LengthAwarePaginator

Exceptions

InvalidArgumentException

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

Paginate the given query into a simple paginator.

Parameters

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

Return Value

Paginator

CursorPaginator cursorPaginate(int|null $perPage = null, array|string $columns = ['*'], string $cursorName = 'cursor', Cursor|string|null $cursor = null)

Paginate the given query into a cursor paginator.

Parameters

int|null $perPage
array|string $columns
string $cursorName
Cursor|string|null $cursor

Return Value

CursorPaginator

protected Collection ensureOrderForCursorPagination(bool $shouldReverse = false)

Ensure the proper order by required for cursor pagination.

Parameters

bool $shouldReverse

Return Value

Collection

TModel create(array $attributes = [])

Save a new model and return the instance.

Parameters

array $attributes

Return Value

TModel

TModel createQuietly(array $attributes = [])

Save a new model and return the instance without raising model events.

Parameters

array $attributes

Return Value

TModel

TModel forceCreate(array $attributes)

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

Parameters

array $attributes

Return Value

TModel

TModel forceCreateQuietly(array $attributes = [])

Save a new model instance with mass assignment without raising model events.

Parameters

array $attributes

Return Value

TModel

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|false touch(string|null $column = null)

Update the column's update timestamp.

Parameters

string|null $column

Return Value

int|false

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 addUniqueIdsToUpsertValues(array $values)

Add unique IDs to the inserted 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($relations, $callback = null)

Set the relationships that should be eager loaded.

Parameters

$relations
$callback

Return Value

$this

$this without(mixed $relations)

Prevent the specified relations from being eager loaded.

Parameters

mixed $relations

Return Value

$this

$this withOnly($relations)

Set the relationships that should be eager loaded while removing any previously added eager loading specifications.

Parameters

$relations

Return Value

$this

TModel newModelInstance(array $attributes = [])

Create a new instance of the model being queried.

Parameters

array $attributes

Return Value

TModel

protected array parseWithRelations(array $relations)

Parse a list of relations into individuals.

Parameters

array $relations

Return Value

array

protected array prepareNestedWithRelationships(array $relations, string $prefix = '')

Prepare nested with relationships.

Parameters

array $relations
string $prefix

Return Value

array

protected Closure combineConstraints(array $constraints)

Combine an array of constraints into a single constraint.

Parameters

array $constraints

Return Value

Closure

protected array parseNameAndAttributeSelectionConstraint(string $name)

Parse the attribute select constraints from the name.

Parameters

string $name

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

mixed withSavepointIfNeeded(Closure $scope)

No description

Parameters

Closure $scope

Return Value

mixed

protected Collection getUnionBuilders()

Get the Eloquent builder instances that are used in the union of the query.

Return Value

Collection

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

$this withoutEagerLoad(array $relations)

Indicate that the given relationships should not be eagerly loaded.

Parameters

array $relations

Return Value

$this

$this withoutEagerLoads()

Flush the relationships being eagerly loaded.

Return Value

$this

mixed getLimit()

Get the "limit" value from the query or null if it's not set.

Return Value

mixed

mixed getOffset()

Get the "offset" value from the query or null if it's not set.

Return Value

mixed

protected string defaultKeyName()

Get the default key name of the table.

Return Value

string

TModel getModel()

Get the model instance being queried.

Return Value

TModel

setModel(Model $model)

No description

Parameters

Model $model

string qualifyColumn(string|Expression $column)

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

Parameters

string|Expression $column

Return Value

string

array qualifyColumns(array|Expression $columns)

Qualify the given columns with the model's table.

Parameters

array|Expression $columns

Return Value

array

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

Builder clone()

Clone the Eloquent query builder.

Return Value

Builder

void __clone()

Force a clone of the underlying query builder when cloning.

Return Value

void