PHP Class Illuminate\Database\Eloquent\Builder

Show file Open project: illuminate/database Class Usage Examples

Protected Properties

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

Public Methods

Method Description
__call ( string $method, array $parameters ) : mixed Dynamically handle calls into the query instance.
__clone ( ) : void Force a clone of the underlying query builder when cloning.
__construct ( Builder $query ) : void Create a new Eloquent query builder instance.
applyScopes ( ) : Builder | static Apply the scopes to the Eloquent builder instance and return it.
chunk ( integer $count, callable $callback ) : boolean Chunk the results of the query.
chunkById ( integer $count, callable $callback, string $column = 'id' ) : boolean Chunk the results of a query by comparing numeric IDs.
cursor ( ) : Generator Get a generator for the given query.
decrement ( string $column, integer $amount = 1, array $extra = [] ) : integer Decrement a column's value by a given amount.
delete ( ) : mixed Delete a record from the database.
doesntHave ( string $relation, string $boolean = 'and', Closure $callback = null ) : Builder | static Add a relationship count / exists condition to the query.
each ( callable $callback, integer $count = 1000 ) : boolean Execute a callback over each item while chunking.
eagerLoadRelations ( array $models ) : array Eager load the relationships for the models.
find ( mixed $id, array $columns = ['*'] ) : Model | Illuminate\Database\Eloquent\Collection | static[] | static | null Find a model by its primary key.
findMany ( array $ids, array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection Find multiple models by their primary keys.
findOrFail ( mixed $id, array $columns = ['*'] ) : Model | Illuminate\Database\Eloquent\Collection Find a model by its primary key or throw an exception.
findOrNew ( mixed $id, array $columns = ['*'] ) : Model Find a model by its primary key or return fresh model instance.
first ( array $columns = ['*'] ) : Model | static | null Execute the query and get the first result.
firstOr ( Closure | array $columns = ['*'], Closure $callback = null ) : Model | static | mixed Execute the query and get the first result or call a callback.
firstOrCreate ( array $attributes, array $values = [] ) : Model Get the first record matching the attributes or create it.
firstOrFail ( array $columns = ['*'] ) : Model | static Execute the query and get the first result or throw an exception.
firstOrNew ( array $attributes, array $values = [] ) : Model Get the first record matching the attributes or instantiate it.
forceDelete ( ) : mixed Run the default delete function on the builder.
get ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection | static[] Execute the query as a "select" statement.
getEagerLoads ( ) : array Get the relationships being eagerly loaded.
getMacro ( string $name ) : Closure Get the given macro by name.
getModel ( ) : Model Get the model instance being queried.
getModels ( array $columns = ['*'] ) : Model[] Get the hydrated models without eager loading.
getQuery ( ) : Builder Get the underlying query builder instance.
getRelation ( string $name ) : Illuminate\Database\Eloquent\Relations\Relation Get the relation instance for the given relation name.
has ( string $relation, string $operator = '>=', integer $count = 1, string $boolean = 'and', Closure $callback = null ) : Builder | static Add a relationship count / exists condition to the query.
increment ( string $column, integer $amount = 1, array $extra = [] ) : integer Increment a column's value by a given amount.
macro ( string $name, Closure $callback ) : void Extend the builder with a given callback.
mergeModelDefinedRelationConstraints ( Builder $relation ) : Builder | static Merge the constraints from a relation query to the current query.
onDelete ( Closure $callback ) : void Register a replacement for the default delete function.
orHas ( string $relation, string $operator = '>=', integer $count = 1 ) : Builder | static Add a relationship count / exists condition to the query with an "or".
orWhere ( string | Closure $column, string $operator = null, mixed $value = null ) : Builder | static Add an "or where" clause to the query.
orWhereHas ( string $relation, Closure $callback, string $operator = '>=', integer $count = 1 ) : Builder | static Add a relationship count / exists condition to the query with where clauses and an "or".
paginate ( integer $perPage = null, array $columns = ['*'], string $pageName = 'page', integer | null $page = null ) : Illuminate\Contracts\Pagination\LengthAwarePaginator Paginate the given query.
pluck ( string $column, string | null $key = null ) : Collection Get an array with the values of a given column.
removedScopes ( ) : array Get an array of global scopes that were removed from the query.
scopes ( array $scopes ) : mixed Add the given scopes to the current builder instance.
setEagerLoads ( array $eagerLoad ) Set the relationships being eagerly loaded.
setModel ( Model $model ) Set a model instance for the model being queried.
setQuery ( Builder $query ) Set the underlying query builder instance.
simplePaginate ( integer $perPage = null, array $columns = ['*'], string $pageName = 'page', integer | null $page = null ) : Illuminate\Contracts\Pagination\Paginator Paginate the given query into a simple paginator.
toBase ( ) : Builder Get a base query builder instance.
update ( array $values ) : integer Update a record in the database.
updateOrCreate ( array $attributes, array $values = [] ) : Model Create or update a record matching the attributes, and fill it with values.
value ( string $column ) : mixed Get a single column's value from the first result of a query.
when ( boolean $value, Closure $callback, Closure $default = null ) Apply the callback's query changes if the given "value" is true.
where ( string | Closure $column, string $operator = null, mixed $value = null, string $boolean = 'and' ) Add a basic where clause to the query.
whereDoesntHave ( string $relation, Closure $callback = null ) : Builder | static Add a relationship count / exists condition to the query with where clauses.
whereHas ( string $relation, Closure $callback = null, string $operator = '>=', integer $count = 1 ) : Builder | static Add a relationship count / exists condition to the query with where clauses.
whereKey ( mixed $id ) Add a where clause on the primary key to the query.
with ( mixed $relations ) Set the relationships that should be eager loaded.
withCount ( mixed $relations ) Add subselect queries to count the relations.
withGlobalScope ( string $identifier, Illuminate\Database\Eloquent\Scope | Closure $scope ) Register a new global scope.
without ( mixed $relations ) Prevent the specified relations from being eager loaded.
withoutGlobalScope ( Illuminate\Database\Eloquent\Scope | string $scope ) Remove a registered global scope.
withoutGlobalScopes ( array $scopes = null ) Remove all or passed registered global scopes.

Protected Methods

Method Description
addHasWhere ( Builder $hasQuery, Illuminate\Database\Eloquent\Relations\Relation $relation, string $operator, integer $count, string $boolean ) : Builder | static Add the "has" condition where clause to the query.
addNestedWhereSlice ( Builder $query, array $wheres, integer $offset, integer $length = null ) : void Slice where conditions at the given offset and add them to the query as a nested condition.
addUpdatedAtColumn ( array $values ) : array Add the "updated at" column to an array of values.
callScope ( callable $scope, array $parameters = [] ) : mixed Apply the given scope on the current builder instance.
enforceOrderBy ( ) : void Add a generic "order by" clause if the query doesn't already have one.
getHasRelationQuery ( string $relation ) : Illuminate\Database\Eloquent\Relations\Relation Get the "has relation" base query instance.
hasNested ( string $relations, string $operator = '>=', integer $count = 1, string $boolean = 'and', Closure | null $callback = null ) : Builder | static Add nested relationship count / exists conditions to the query.
isNested ( string $name, string $relation ) : boolean Determine if the relationship is nested.
loadRelation ( array $models, string $name, Closure $constraints ) : array Eagerly load the relationship on a set of models.
nestWhereSlice ( array $whereSlice, string $boolean = 'and' ) : array Create a where array with nested where conditions.
nestWheresForScope ( Builder $query, integer $originalWhereCount ) : void Nest where conditions by slicing them at the given where count.
nestedRelations ( string $relation ) : array Get the deeply nested relations for a given top-level relation.
parseNestedWith ( string $name, array $results ) : array Parse the nested relationships in a relation.
parseWithRelations ( array $relations ) : array Parse a list of relations into individuals.
shouldNestWheresForScope ( Builder $query, integer $originalWhereCount ) : boolean Determine if the scope added after the given offset should be nested.
shouldRunExistsQuery ( string $operator, integer $count ) : boolean Check if we can run an "exists" query to optimize performance.
whereCountQuery ( Builder $query, string $operator = '>=', integer $count = 1, string $boolean = 'and' ) Add a sub query count clause to the query.

Method Details

__call() public method

Dynamically handle calls into the query instance.
public __call ( string $method, array $parameters ) : mixed
$method string
$parameters array
return mixed

__clone() public method

Force a clone of the underlying query builder when cloning.
public __clone ( ) : void
return void

__construct() public method

Create a new Eloquent query builder instance.
public __construct ( Builder $query ) : void
$query Illuminate\Database\Query\Builder
return void

addHasWhere() protected method

Add the "has" condition where clause to the query.
protected addHasWhere ( Builder $hasQuery, Illuminate\Database\Eloquent\Relations\Relation $relation, string $operator, integer $count, string $boolean ) : Builder | static
$hasQuery Builder
$relation Illuminate\Database\Eloquent\Relations\Relation
$operator string
$count integer
$boolean string
return Builder | static

addNestedWhereSlice() protected method

Slice where conditions at the given offset and add them to the query as a nested condition.
protected addNestedWhereSlice ( Builder $query, array $wheres, integer $offset, integer $length = null ) : void
$query Illuminate\Database\Query\Builder
$wheres array
$offset integer
$length integer
return void

addUpdatedAtColumn() protected method

Add the "updated at" column to an array of values.
protected addUpdatedAtColumn ( array $values ) : array
$values array
return array

applyScopes() public method

Apply the scopes to the Eloquent builder instance and return it.
public applyScopes ( ) : Builder | static
return Builder | static

callScope() protected method

Apply the given scope on the current builder instance.
protected callScope ( callable $scope, array $parameters = [] ) : mixed
$scope callable
$parameters array
return mixed

chunk() public method

Chunk the results of the query.
public chunk ( integer $count, callable $callback ) : boolean
$count integer
$callback callable
return boolean

chunkById() public method

Chunk the results of a query by comparing numeric IDs.
public chunkById ( integer $count, callable $callback, string $column = 'id' ) : boolean
$count integer
$callback callable
$column string
return boolean

cursor() public method

Get a generator for the given query.
public cursor ( ) : Generator
return Generator

decrement() public method

Decrement a column's value by a given amount.
public decrement ( string $column, integer $amount = 1, array $extra = [] ) : integer
$column string
$amount integer
$extra array
return integer

delete() public method

Delete a record from the database.
public delete ( ) : mixed
return mixed

doesntHave() public method

Add a relationship count / exists condition to the query.
public doesntHave ( string $relation, string $boolean = 'and', Closure $callback = null ) : Builder | static
$relation string
$boolean string
$callback Closure
return Builder | static

each() public method

Execute a callback over each item while chunking.
public each ( callable $callback, integer $count = 1000 ) : boolean
$callback callable
$count integer
return boolean

eagerLoadRelations() public method

Eager load the relationships for the models.
public eagerLoadRelations ( array $models ) : array
$models array
return array

enforceOrderBy() protected method

Add a generic "order by" clause if the query doesn't already have one.
protected enforceOrderBy ( ) : void
return void

find() public method

Find a model by its primary key.
public find ( mixed $id, array $columns = ['*'] ) : Model | Illuminate\Database\Eloquent\Collection | static[] | static | null
$id mixed
$columns array
return Model | Illuminate\Database\Eloquent\Collection | static[] | static | null

findMany() public method

Find multiple models by their primary keys.
public findMany ( array $ids, array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection
$ids array
$columns array
return Illuminate\Database\Eloquent\Collection

findOrFail() public method

Find a model by its primary key or throw an exception.
public findOrFail ( mixed $id, array $columns = ['*'] ) : Model | Illuminate\Database\Eloquent\Collection
$id mixed
$columns array
return Model | Illuminate\Database\Eloquent\Collection

findOrNew() public method

Find a model by its primary key or return fresh model instance.
public findOrNew ( mixed $id, array $columns = ['*'] ) : Model
$id mixed
$columns array
return Model

first() public method

Execute the query and get the first result.
public first ( array $columns = ['*'] ) : Model | static | null
$columns array
return Model | static | null

firstOr() public method

Execute the query and get the first result or call a callback.
public firstOr ( Closure | array $columns = ['*'], Closure $callback = null ) : Model | static | mixed
$columns Closure | array
$callback Closure
return Model | static | mixed

firstOrCreate() public method

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

firstOrFail() public method

Execute the query and get the first result or throw an exception.
public firstOrFail ( array $columns = ['*'] ) : Model | static
$columns array
return Model | static

firstOrNew() public method

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

forceDelete() public method

Run the default delete function on the builder.
public forceDelete ( ) : mixed
return mixed

get() public method

Execute the query as a "select" statement.
public get ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection | static[]
$columns array
return Illuminate\Database\Eloquent\Collection | static[]

getEagerLoads() public method

Get the relationships being eagerly loaded.
public getEagerLoads ( ) : array
return array

getHasRelationQuery() protected method

Get the "has relation" base query instance.
protected getHasRelationQuery ( string $relation ) : Illuminate\Database\Eloquent\Relations\Relation
$relation string
return Illuminate\Database\Eloquent\Relations\Relation

getMacro() public method

Get the given macro by name.
public getMacro ( string $name ) : Closure
$name string
return Closure

getModel() public method

Get the model instance being queried.
public getModel ( ) : Model
return Model

getModels() public method

Get the hydrated models without eager loading.
public getModels ( array $columns = ['*'] ) : Model[]
$columns array
return Model[]

getQuery() public method

Get the underlying query builder instance.
public getQuery ( ) : Builder
return Illuminate\Database\Query\Builder

getRelation() public method

Get the relation instance for the given relation name.
public getRelation ( string $name ) : Illuminate\Database\Eloquent\Relations\Relation
$name string
return Illuminate\Database\Eloquent\Relations\Relation

has() public method

Add a relationship count / exists condition to the query.
public has ( string $relation, string $operator = '>=', integer $count = 1, string $boolean = 'and', Closure $callback = null ) : Builder | static
$relation string
$operator string
$count integer
$boolean string
$callback Closure
return Builder | static

hasNested() protected method

Add nested relationship count / exists conditions to the query.
protected hasNested ( string $relations, string $operator = '>=', integer $count = 1, string $boolean = 'and', Closure | null $callback = null ) : Builder | static
$relations string
$operator string
$count integer
$boolean string
$callback Closure | null
return Builder | static

increment() public method

Increment a column's value by a given amount.
public increment ( string $column, integer $amount = 1, array $extra = [] ) : integer
$column string
$amount integer
$extra array
return integer

isNested() protected method

Determine if the relationship is nested.
protected isNested ( string $name, string $relation ) : boolean
$name string
$relation string
return boolean

loadRelation() protected method

Eagerly load the relationship on a set of models.
protected loadRelation ( array $models, string $name, Closure $constraints ) : array
$models array
$name string
$constraints Closure
return array

macro() public method

Extend the builder with a given callback.
public macro ( string $name, Closure $callback ) : void
$name string
$callback Closure
return void

mergeModelDefinedRelationConstraints() public method

Merge the constraints from a relation query to the current query.
public mergeModelDefinedRelationConstraints ( Builder $relation ) : Builder | static
$relation Builder
return Builder | static

nestWhereSlice() protected method

Create a where array with nested where conditions.
protected nestWhereSlice ( array $whereSlice, string $boolean = 'and' ) : array
$whereSlice array
$boolean string
return array

nestWheresForScope() protected method

Nest where conditions by slicing them at the given where count.
protected nestWheresForScope ( Builder $query, integer $originalWhereCount ) : void
$query Illuminate\Database\Query\Builder
$originalWhereCount integer
return void

nestedRelations() protected method

Get the deeply nested relations for a given top-level relation.
protected nestedRelations ( string $relation ) : array
$relation string
return array

onDelete() public method

Register a replacement for the default delete function.
public onDelete ( Closure $callback ) : void
$callback Closure
return void

orHas() public method

Add a relationship count / exists condition to the query with an "or".
public orHas ( string $relation, string $operator = '>=', integer $count = 1 ) : Builder | static
$relation string
$operator string
$count integer
return Builder | static

orWhere() public method

Add an "or where" clause to the query.
public orWhere ( string | Closure $column, string $operator = null, mixed $value = null ) : Builder | static
$column string | Closure
$operator string
$value mixed
return Builder | static

orWhereHas() public method

Add a relationship count / exists condition to the query with where clauses and an "or".
public orWhereHas ( string $relation, Closure $callback, string $operator = '>=', integer $count = 1 ) : Builder | static
$relation string
$callback Closure
$operator string
$count integer
return Builder | static

paginate() public method

Paginate the given query.
public paginate ( integer $perPage = null, array $columns = ['*'], string $pageName = 'page', integer | null $page = null ) : Illuminate\Contracts\Pagination\LengthAwarePaginator
$perPage integer
$columns array
$pageName string
$page integer | null
return Illuminate\Contracts\Pagination\LengthAwarePaginator

parseNestedWith() protected method

Parse the nested relationships in a relation.
protected parseNestedWith ( string $name, array $results ) : array
$name string
$results array
return array

parseWithRelations() protected method

Parse a list of relations into individuals.
protected parseWithRelations ( array $relations ) : array
$relations array
return array

pluck() public method

Get an array with the values of a given column.
public pluck ( string $column, string | null $key = null ) : Collection
$column string
$key string | null
return Illuminate\Support\Collection

removedScopes() public method

Get an array of global scopes that were removed from the query.
public removedScopes ( ) : array
return array

scopes() public method

Add the given scopes to the current builder instance.
public scopes ( array $scopes ) : mixed
$scopes array
return mixed

setEagerLoads() public method

Set the relationships being eagerly loaded.
public setEagerLoads ( array $eagerLoad )
$eagerLoad array

setModel() public method

Set a model instance for the model being queried.
public setModel ( Model $model )
$model Model

setQuery() public method

Set the underlying query builder instance.
public setQuery ( Builder $query )
$query Illuminate\Database\Query\Builder

shouldNestWheresForScope() protected method

Determine if the scope added after the given offset should be nested.
protected shouldNestWheresForScope ( Builder $query, integer $originalWhereCount ) : boolean
$query Illuminate\Database\Query\Builder
$originalWhereCount integer
return boolean

shouldRunExistsQuery() protected method

Check if we can run an "exists" query to optimize performance.
protected shouldRunExistsQuery ( string $operator, integer $count ) : boolean
$operator string
$count integer
return boolean

simplePaginate() public method

Paginate the given query into a simple paginator.
public simplePaginate ( integer $perPage = null, array $columns = ['*'], string $pageName = 'page', integer | null $page = null ) : Illuminate\Contracts\Pagination\Paginator
$perPage integer
$columns array
$pageName string
$page integer | null
return Illuminate\Contracts\Pagination\Paginator

toBase() public method

Get a base query builder instance.
public toBase ( ) : Builder
return Illuminate\Database\Query\Builder

update() public method

Update a record in the database.
public update ( array $values ) : integer
$values array
return integer

updateOrCreate() public method

Create or update a record matching the attributes, and fill it with values.
public updateOrCreate ( array $attributes, array $values = [] ) : Model
$attributes array
$values array
return Model

value() public method

Get a single column's value from the first result of a query.
public value ( string $column ) : mixed
$column string
return mixed

when() public method

Apply the callback's query changes if the given "value" is true.
public when ( boolean $value, Closure $callback, Closure $default = null )
$value boolean
$callback Closure
$default Closure

where() public method

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

whereCountQuery() protected method

Add a sub query count clause to the query.
protected whereCountQuery ( Builder $query, string $operator = '>=', integer $count = 1, string $boolean = 'and' )
$query Illuminate\Database\Query\Builder
$operator string
$count integer
$boolean string

whereDoesntHave() public method

Add a relationship count / exists condition to the query with where clauses.
public whereDoesntHave ( string $relation, Closure $callback = null ) : Builder | static
$relation string
$callback Closure
return Builder | static

whereHas() public method

Add a relationship count / exists condition to the query with where clauses.
public whereHas ( string $relation, Closure $callback = null, string $operator = '>=', integer $count = 1 ) : Builder | static
$relation string
$callback Closure
$operator string
$count integer
return Builder | static

whereKey() public method

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

with() public method

Set the relationships that should be eager loaded.
public with ( mixed $relations )
$relations mixed

withCount() public method

Add subselect queries to count the relations.
public withCount ( mixed $relations )
$relations mixed

withGlobalScope() public method

Register a new global scope.
public withGlobalScope ( string $identifier, Illuminate\Database\Eloquent\Scope | Closure $scope )
$identifier string
$scope Illuminate\Database\Eloquent\Scope | Closure

without() public method

Prevent the specified relations from being eager loaded.
public without ( mixed $relations )
$relations mixed

withoutGlobalScope() public method

Remove a registered global scope.
public withoutGlobalScope ( Illuminate\Database\Eloquent\Scope | string $scope )
$scope Illuminate\Database\Eloquent\Scope | string

withoutGlobalScopes() public method

Remove all or passed registered global scopes.
public withoutGlobalScopes ( array $scopes = null )
$scopes array

Property Details

$eagerLoad protected property

The relationships that should be eager loaded.
protected array $eagerLoad
return array

$macros protected property

All of the registered builder macros.
protected array $macros
return array

$model protected property

The model being queried.
protected Model,Illuminate\Database\Eloquent $model
return Model

$onDelete protected property

A replacement for the typical delete function.
protected Closure $onDelete
return Closure

$passthru protected property

The methods that should be returned from query builder.
protected array $passthru
return array

$query protected property

The base query builder instance.
protected Builder,Illuminate\Database\Query $query
return Illuminate\Database\Query\Builder

$removedScopes protected property

Removed global scopes.
protected array $removedScopes
return array

$scopes protected property

Applied global scopes.
protected array $scopes
return array