class Builder (View source)

Query builder for ODM.

Properties

protected string $currentField The current field we are operating on.

Methods

__construct(DocumentManager $dm, $documentName = null)

Construct a Builder

__clone()

No description

addAnd(array|Expr $expression, array|Expr ...$expressions)

Add one or more $and clauses to the current query.

addNor(array|Expr $expression, array|Expr ...$expressions)

Add one or more $nor clauses to the current query.

addOr(array|Expr $expression, array|Expr ...$expressions)

Add one or more $or clauses to the current query.

addToSet(mixed|Expr $valueOrExpression)

Append one or more values to the current array field only if they do not already exist in the array.

all(array $values)

Specify $all criteria for the current field.

$this
bitAnd(int $value)

Apply a bitwise and operation on the current field.

bitOr(int $value)

Apply a bitwise or operation on the current field.

bitsAllClear(int|array|Binary $value)

Matches documents where all of the bit positions given by the query are clear.

bitsAllSet(int|array|Binary $value)

Matches documents where all of the bit positions given by the query are set.

bitsAnyClear(int|array|Binary $value)

Matches documents where any of the bit positions given by the query are clear.

bitsAnySet(int|array|Binary $value)

Matches documents where any of the bit positions given by the query are set.

bitXor(int $value)

Apply a bitwise xor operation on the current field.

caseSensitive(bool $caseSensitive)

A boolean flag to enable or disable case sensitive search for $text criteria.

comment(string $comment)

Associates a comment to any expression taking a query predicate.

count()

Change the query type to count.

currentDate(string $type = 'date')

Sets the value of the current field to the current date, either as a date or a timestamp.

mixed
debug(string|null $name = null)

Return an array of information about the Builder state for debugging.

diacriticSensitive(bool $diacriticSensitive)

A boolean flag to enable or disable diacritic sensitive search for $text criteria.

distinct(string $field)

Change the query type to a distinct command.

eagerCursor(bool $bool = true)

Set whether the query should return its result as an EagerCursor.

elemMatch(array|Expr $expression)

Specify $elemMatch criteria for the current field.

equals(mixed $value)

Specify an equality match for the current field.

exclude($fieldName = null)

Set one or more fields to be excluded from the query projection.

exists(bool $bool)

Specify $exists criteria for the current field.

expr()

Create a new Expr instance that can be used as an expression with the Builder

field(string $field)

Set the current field to operate on.

finalize(string|Javascript $finalize)

Set the "finalize" option for a mapReduce or group command.

find(string|null $documentName = null)

Change the query type to find and optionally set and change the class being queried.

findAndRemove(string|null $documentName = null)

No description

findAndUpdate(string|null $documentName = null)

No description

geoIntersects(array|Geometry $geometry)

Add $geoIntersects criteria with a GeoJSON geometry to the query.

geoWithin(array|Geometry $geometry)

Add $geoWithin criteria with a GeoJSON geometry to the query.

geoWithinBox(float $x1, float $y1, float $x2, float $y2)

Add $geoWithin criteria with a $box shape to the query.

geoWithinCenter(float $x, float $y, float $radius)

Add $geoWithin criteria with a $center shape to the query.

geoWithinCenterSphere(float $x, float $y, float $radius)

Add $geoWithin criteria with a $centerSphere shape to the query.

geoWithinPolygon(array $point1, array $point2, array $point3, array ...$points)

Add $geoWithin criteria with a $polygon shape to the query.

getNewObj()

Return the expression's "new object".

getQuery(array $options = [])

Gets the Query executable.

getQueryArray()

Return the expression's query criteria.

getType()

Get the type of this query.

gt(mixed $value)

Specify $gt criteria for the current field.

gte(mixed $value)

Specify $gte criteria for the current field.

hint(array|string $index)

Set the index hint for the query.

hydrate(bool $bool = true)

No description

immortal(bool $bool = true)

Set the immortal cursor flag.

in(array $values)

Specify $in criteria for the current field.

inc(float|int $value)

Increment the current field.

includesReferenceTo(object $document)

No description

insert(string|null $documentName = null)

No description

language(string $language)

Set the $language option for $text criteria.

limit(int $limit)

Set the limit for the query.

lt(mixed $value)

Specify $lt criteria for the current field.

lte(mixed $value)

Specify $lte criteria for the current field.

map(string|Javascript $map)

Change the query type to a mapReduce command.

$this
mapReduce(string|Javascript $map, string|Javascript $reduce, array|string $out = ['inline' => true], array $options = [])

Change the query type to a mapReduce command.

mapReduceOptions(array $options)

Set additional options for a mapReduce command.

max(mixed $value)

Updates the value of the field to a specified value if the specified value is greater than the current value of the field.

maxTimeMS(int $ms)

Specifies a cumulative time limit in milliseconds for processing operations on a cursor.

min(mixed $value)

Updates the value of the field to a specified value if the specified value is less than the current value of the field.

mod(float|int $divisor, float|int $remainder = 0)

Specify $mod criteria for the current field.

mul(float|int $value)

Multiply the current field.

near(float|array|Point $x, float $y = null)

Add $near criteria to the query.

nearSphere(float|array|Point $x, float $y = null)

Add $nearSphere criteria to the query.

not(array|Expr $expression)

Negates an expression for the current field.

notEqual(mixed $value)

Specify $ne criteria for the current field.

notIn(array $values)

Specify $nin criteria for the current field.

out(array|string $out)

Set the "out" option for a mapReduce command.

popFirst()

Remove the first element from the current array field.

popLast()

Remove the last element from the current array field.

prime(bool|callable $primer = true)

Use a primer to eagerly load all references in the current field.

pull(mixed|Expr $valueOrExpression)

Remove all elements matching the given value or expression from the current array field.

pullAll(array $values)

Remove all elements matching any of the given values from the current array field.

push(mixed|Expr $valueOrExpression)

Append one or more values to the current array field.

range(mixed $start, mixed $end)

Specify $gte and $lt criteria for the current field.

readOnly(bool $bool = true)

No description

reduce(string|Javascript $reduce)

Set the "reduce" option for a mapReduce or group command.

references(object $document)

No description

refresh(bool $bool = true)

No description

remove(string|null $documentName = null)

No description

rename(string $name)

Rename the current field.

returnNew(bool $bool = true)

No description

select($fieldName = null)

Set one or more fields to be included in the query projection.

selectElemMatch(string $fieldName, $expression)

Select only matching embedded documents in an array field for the query projection.

selectMeta(string $fieldName, string $metaDataKeyword)

Select a metadata field for the query projection.

selectSlice(string $fieldName, int $countOrSkip, int|null $limit = null)

Select a slice of an array field for the query projection.

set($value, bool $atomic = true)

Set the current field to a value.

setNewObj(array $newObj)

Set the expression's "new object".

setOnInsert(mixed $value)

Set the current field to the value if the document is inserted in an upsert operation.

setReadPreference(ReadPreference $readPreference)

Set the read preference for the query.

setQueryArray(array $query)

Set the expression's query criteria.

size(int $size)

Specify $size criteria for the current field.

skip(int $skip)

Set the skip for the query cursor.

snapshot(bool $bool = true)

Set the snapshot cursor flag.

sort(array|string $fieldName, int|string $order = 1)

Set one or more field/order pairs on which to sort the query.

sortMeta(string $fieldName, string $metaDataKeyword)

Specify a projected metadata field on which to sort the query.

text(string $search)

Specify $text criteria for the current field.

type(int|string $type)

Specify $type criteria for the current field.

unsetField()

Unset the current field.

updateOne(string|null $documentName = null)

No description

updateMany(string|null $documentName = null)

No description

upsert(bool $bool = true)

Set the "upsert" option for an update or findAndUpdate query.

where(string|Javascript $javascript)

Specify a JavaScript expression to use for matching documents.

Details

__construct(DocumentManager $dm, $documentName = null)

Construct a Builder

Parameters

DocumentManager $dm
$documentName

__clone()

addAnd(array|Expr $expression, array|Expr ...$expressions)

Add one or more $and clauses to the current query.

You can create a new expression using the {@link Builder::expr()} method.

Parameters

array|Expr $expression
array|Expr ...$expressions

See also

Expr::addAnd
http://docs.mongodb.org/manual/reference/operator/and/

addNor(array|Expr $expression, array|Expr ...$expressions)

Add one or more $nor clauses to the current query.

You can create a new expression using the {@link Builder::expr()} method.

Parameters

array|Expr $expression
array|Expr ...$expressions

See also

Expr::addNor
http://docs.mongodb.org/manual/reference/operator/nor/

addOr(array|Expr $expression, array|Expr ...$expressions)

Add one or more $or clauses to the current query.

You can create a new expression using the {@link Builder::expr()} method.

Parameters

array|Expr $expression
array|Expr ...$expressions

See also

Expr::addOr
http://docs.mongodb.org/manual/reference/operator/or/

addToSet(mixed|Expr $valueOrExpression)

Append one or more values to the current array field only if they do not already exist in the array.

If the field does not exist, it will be set to an array containing the unique value(s) in the argument. If the field is not an array, the query will yield an error.

Multiple values may be specified by provided an Expr object and using {@link Expr::each()}.

all(array $values)

Specify $all criteria for the current field.

$this bitAnd(int $value)

Apply a bitwise and operation on the current field.

Parameters

int $value

Return Value

$this

See also

Expr::bitAnd
http://docs.mongodb.org/manual/reference/operator/update/bit/

bitOr(int $value)

Apply a bitwise or operation on the current field.

bitsAllClear(int|array|Binary $value)

Matches documents where all of the bit positions given by the query are clear.

bitsAllSet(int|array|Binary $value)

Matches documents where all of the bit positions given by the query are set.

bitsAnyClear(int|array|Binary $value)

Matches documents where any of the bit positions given by the query are clear.

bitsAnySet(int|array|Binary $value)

Matches documents where any of the bit positions given by the query are set.

bitXor(int $value)

Apply a bitwise xor operation on the current field.

caseSensitive(bool $caseSensitive)

A boolean flag to enable or disable case sensitive search for $text criteria.

This method must be called after text().

Parameters

bool $caseSensitive

Exceptions

BadMethodCallException If the query does not already have $text criteria.

See also

Expr::caseSensitive
http://docs.mongodb.org/manual/reference/operator/text/

comment(string $comment)

Associates a comment to any expression taking a query predicate.

count()

Change the query type to count.

currentDate(string $type = 'date')

Sets the value of the current field to the current date, either as a date or a timestamp.

mixed debug(string|null $name = null)

Return an array of information about the Builder state for debugging.

The $name parameter may be used to return a specific key from the internal $query array property. If omitted, the entire array will be returned.

Parameters

string|null $name

Return Value

mixed

diacriticSensitive(bool $diacriticSensitive)

A boolean flag to enable or disable diacritic sensitive search for $text criteria.

This method must be called after text().

Parameters

bool $diacriticSensitive

Exceptions

BadMethodCallException If the query does not already have $text criteria.

See also

Builder::diacriticSensitive
http://docs.mongodb.org/manual/reference/operator/text/

distinct(string $field)

Change the query type to a distinct command.

eagerCursor(bool $bool = true)

Set whether the query should return its result as an EagerCursor.

Parameters

bool $bool

elemMatch(array|Expr $expression)

Specify $elemMatch criteria for the current field.

You can create a new expression using the {@link Builder::expr()} method.

equals(mixed $value)

Specify an equality match for the current field.

Parameters

mixed $value

See also

Expr::equals

exclude($fieldName = null)

Set one or more fields to be excluded from the query projection.

If fields have been selected for inclusion, only the "_id" field may be excluded.

Parameters

$fieldName

exists(bool $bool)

Specify $exists criteria for the current field.

expr()

Create a new Expr instance that can be used as an expression with the Builder

field(string $field)

Set the current field to operate on.

Parameters

string $field

finalize(string|Javascript $finalize)

Set the "finalize" option for a mapReduce or group command.

Parameters

string|Javascript $finalize

Exceptions

BadMethodCallException If the query is not a mapReduce or group command.

find(string|null $documentName = null)

Change the query type to find and optionally set and change the class being queried.

Parameters

string|null $documentName

findAndRemove(string|null $documentName = null)

Parameters

string|null $documentName

findAndUpdate(string|null $documentName = null)

Parameters

string|null $documentName

geoIntersects(array|Geometry $geometry)

Add $geoIntersects criteria with a GeoJSON geometry to the query.

The geometry parameter GeoJSON object or an array corresponding to the geometry's JSON representation.

geoWithin(array|Geometry $geometry)

Add $geoWithin criteria with a GeoJSON geometry to the query.

The geometry parameter GeoJSON object or an array corresponding to the geometry's JSON representation.

geoWithinBox(float $x1, float $y1, float $x2, float $y2)

Add $geoWithin criteria with a $box shape to the query.

A rectangular polygon will be constructed from a pair of coordinates corresponding to the bottom left and top right corners.

Note: the $box operator only supports legacy coordinate pairs and 2d indexes. This cannot be used with 2dsphere indexes and GeoJSON shapes.

Parameters

float $x1
float $y1
float $x2
float $y2

See also

Expr::geoWithinBox
http://docs.mongodb.org/manual/reference/operator/box/

geoWithinCenter(float $x, float $y, float $radius)

Add $geoWithin criteria with a $center shape to the query.

Note: the $center operator only supports legacy coordinate pairs and 2d indexes. This cannot be used with 2dsphere indexes and GeoJSON shapes.

Parameters

float $x
float $y
float $radius

See also

Expr::geoWithinCenter
http://docs.mongodb.org/manual/reference/operator/center/

geoWithinCenterSphere(float $x, float $y, float $radius)

Add $geoWithin criteria with a $centerSphere shape to the query.

Note: the $centerSphere operator supports both 2d and 2dsphere indexes.

geoWithinPolygon(array $point1, array $point2, array $point3, array ...$points)

Add $geoWithin criteria with a $polygon shape to the query.

Point coordinates are in x, y order (easting, northing for projected coordinates, longitude, latitude for geographic coordinates).

The last point coordinate is implicitly connected with the first.

Note: the $polygon operator only supports legacy coordinate pairs and 2d indexes. This cannot be used with 2dsphere indexes and GeoJSON shapes.

Parameters

array $point1 First point of the polygon
array $point2 Second point of the polygon
array $point3 Third point of the polygon
array ...$points Additional points of the polygon

See also

Expr::geoWithinPolygon
http://docs.mongodb.org/manual/reference/operator/polygon/

getNewObj()

Return the expression's "new object".

See also

Expr::getNewObj

getQuery(array $options = [])

Gets the Query executable.

Parameters

array $options

getQueryArray()

Return the expression's query criteria.

See also

Expr::getQuery

getType()

Get the type of this query.

gt(mixed $value)

Specify $gt criteria for the current field.

gte(mixed $value)

Specify $gte criteria for the current field.

hint(array|string $index)

Set the index hint for the query.

Parameters

array|string $index

hydrate(bool $bool = true)

Parameters

bool $bool

immortal(bool $bool = true)

Set the immortal cursor flag.

Parameters

bool $bool

in(array $values)

Specify $in criteria for the current field.

inc(float|int $value)

Increment the current field.

If the field does not exist, it will be set to this value.

includesReferenceTo(object $document)

Parameters

object $document

insert(string|null $documentName = null)

Parameters

string|null $documentName

language(string $language)

Set the $language option for $text criteria.

This method must be called after text().

limit(int $limit)

Set the limit for the query.

This is only relevant for find queries and geoNear and mapReduce commands.

Parameters

int $limit

See also

Query::prepareCursor()

lt(mixed $value)

Specify $lt criteria for the current field.

lte(mixed $value)

Specify $lte criteria for the current field.

map(string|Javascript $map)

Change the query type to a mapReduce command.

The "reduce" option is not specified when calling this method; it must be set with the {@link Builder::reduce()} method.

The "out" option defaults to inline, like {@link Builder::mapReduce()}.

Parameters

string|Javascript $map

See also

http://docs.mongodb.org/manual/reference/command/mapReduce/

$this mapReduce(string|Javascript $map, string|Javascript $reduce, array|string $out = ['inline' => true], array $options = [])

Change the query type to a mapReduce command.

Parameters

string|Javascript $map
string|Javascript $reduce
array|string $out
array $options

Return Value

$this

See also

http://docs.mongodb.org/manual/reference/command/mapReduce/

mapReduceOptions(array $options)

Set additional options for a mapReduce command.

Parameters

array $options

Exceptions

BadMethodCallException If the query is not a mapReduce command.

max(mixed $value)

Updates the value of the field to a specified value if the specified value is greater than the current value of the field.

maxTimeMS(int $ms)

Specifies a cumulative time limit in milliseconds for processing operations on a cursor.

Parameters

int $ms

min(mixed $value)

Updates the value of the field to a specified value if the specified value is less than the current value of the field.

mod(float|int $divisor, float|int $remainder = 0)

Specify $mod criteria for the current field.

Parameters

float|int $divisor
float|int $remainder

See also

Expr::mod
http://docs.mongodb.org/manual/reference/operator/mod/

mul(float|int $value)

Multiply the current field.

If the field does not exist, it will be set to 0.

near(float|array|Point $x, float $y = null)

Add $near criteria to the query.

A GeoJSON point may be provided as the first and only argument for 2dsphere queries. This single parameter may be a GeoJSON point object or an array corresponding to the point's JSON representation.

Parameters

float|array|Point $x
float $y

See also

Expr::near
http://docs.mongodb.org/manual/reference/operator/near/

nearSphere(float|array|Point $x, float $y = null)

Add $nearSphere criteria to the query.

A GeoJSON point may be provided as the first and only argument for 2dsphere queries. This single parameter may be a GeoJSON point object or an array corresponding to the point's JSON representation.

Parameters

float|array|Point $x
float $y

See also

Expr::nearSphere
http://docs.mongodb.org/manual/reference/operator/nearSphere/

not(array|Expr $expression)

Negates an expression for the current field.

You can create a new expression using the {@link Builder::expr()} method.

notEqual(mixed $value)

Specify $ne criteria for the current field.

notIn(array $values)

Specify $nin criteria for the current field.

out(array|string $out)

Set the "out" option for a mapReduce command.

Parameters

array|string $out

Exceptions

BadMethodCallException If the query is not a mapReduce command.

popFirst()

Remove the first element from the current array field.

popLast()

Remove the last element from the current array field.

prime(bool|callable $primer = true)

Use a primer to eagerly load all references in the current field.

If $primer is true or a callable is provided, referenced documents for this field will loaded into UnitOfWork immediately after the query is executed. This will avoid multiple queries due to lazy initialization of Proxy objects.

If $primer is false, no priming will take place. That is also the default behavior.

If a custom callable is used, its signature should conform to the default Closure defined in {@link ReferencePrimer::__construct()}.

Parameters

bool|callable $primer

Exceptions

InvalidArgumentException If $primer is not boolean or callable.

pull(mixed|Expr $valueOrExpression)

Remove all elements matching the given value or expression from the current array field.

Parameters

mixed|Expr $valueOrExpression

See also

Expr::pull
http://docs.mongodb.org/manual/reference/operator/pull/

pullAll(array $values)

Remove all elements matching any of the given values from the current array field.

push(mixed|Expr $valueOrExpression)

Append one or more values to the current array field.

If the field does not exist, it will be set to an array containing the value(s) in the argument. If the field is not an array, the query will yield an error.

Multiple values may be specified by providing an Expr object and using {@link Expr::each()}. {@link Expr::slice()} and {@link Expr::sort()} may also be used to limit and order array elements, respectively.

range(mixed $start, mixed $end)

Specify $gte and $lt criteria for the current field.

This method is shorthand for specifying $gte criteria on the lower bound and $lt criteria on the upper bound. The upper bound is not inclusive.

Parameters

mixed $start
mixed $end

See also

Expr::range

readOnly(bool $bool = true)

Parameters

bool $bool

reduce(string|Javascript $reduce)

Set the "reduce" option for a mapReduce or group command.

Parameters

string|Javascript $reduce

Exceptions

BadMethodCallException If the query is not a mapReduce or group command.

references(object $document)

Parameters

object $document

refresh(bool $bool = true)

Parameters

bool $bool

remove(string|null $documentName = null)

Parameters

string|null $documentName

rename(string $name)

Rename the current field.

returnNew(bool $bool = true)

Parameters

bool $bool

select($fieldName = null)

Set one or more fields to be included in the query projection.

Parameters

$fieldName

selectElemMatch(string $fieldName, $expression)

Select only matching embedded documents in an array field for the query projection.

Parameters

string $fieldName
$expression

See also

http://docs.mongodb.org/manual/reference/projection/elemMatch/

selectMeta(string $fieldName, string $metaDataKeyword)

Select a metadata field for the query projection.

Parameters

string $fieldName
string $metaDataKeyword

See also

http://docs.mongodb.org/master/reference/operator/projection/meta/

selectSlice(string $fieldName, int $countOrSkip, int|null $limit = null)

Select a slice of an array field for the query projection.

The $countOrSkip parameter has two very different meanings, depending on whether or not $limit is provided. See the MongoDB documentation for more information.

Parameters

string $fieldName
int $countOrSkip
int|null $limit

See also

http://docs.mongodb.org/manual/reference/projection/slice/

set($value, bool $atomic = true)

Set the current field to a value.

This is only relevant for insert, update, or findAndUpdate queries. For update and findAndUpdate queries, the $atomic parameter will determine whether or not a $set operator is used.

Parameters

$value
bool $atomic

See also

Expr::set
http://docs.mongodb.org/manual/reference/operator/set/

setNewObj(array $newObj)

Set the expression's "new object".

Parameters

array $newObj

See also

Expr::setNewObj

setOnInsert(mixed $value)

Set the current field to the value if the document is inserted in an upsert operation.

If an update operation with upsert: true results in an insert of a document, then $setOnInsert assigns the specified values to the fields in the document. If the update operation does not result in an insert, $setOnInsert does nothing.

setReadPreference(ReadPreference $readPreference)

Set the read preference for the query.

This is only relevant for read-only queries and commands.

Parameters

ReadPreference $readPreference

See also

http://docs.mongodb.org/manual/core/read-preference/

setQueryArray(array $query)

Set the expression's query criteria.

Parameters

array $query

See also

Expr::setQuery

size(int $size)

Specify $size criteria for the current field.

skip(int $skip)

Set the skip for the query cursor.

This is only relevant for find queries, or mapReduce queries that store results in an output collecton and return a cursor.

Parameters

int $skip

See also

Query::prepareCursor()

snapshot(bool $bool = true)

Set the snapshot cursor flag.

Parameters

bool $bool

sort(array|string $fieldName, int|string $order = 1)

Set one or more field/order pairs on which to sort the query.

If sorting by multiple fields, the first argument should be an array of field name (key) and order (value) pairs.

Parameters

array|string $fieldName Field name or array of field/order pairs
int|string $order Field order (if one field is specified)

sortMeta(string $fieldName, string $metaDataKeyword)

Specify a projected metadata field on which to sort the query.

Sort order is not configurable for metadata fields. Sorting by a metadata field requires the same field and $meta expression to exist in the projection document. This method will call {@link Builder::selectMeta()} if the field is not already set in the projection.

Parameters

string $fieldName
string $metaDataKeyword

See also

http://docs.mongodb.org/master/reference/operator/projection/meta/#sort

text(string $search)

Specify $text criteria for the current field.

The $language option may be set with {@link Builder::language()}.

type(int|string $type)

Specify $type criteria for the current field.

unsetField()

Unset the current field.

The field will be removed from the document (not set to null).

updateOne(string|null $documentName = null)

Parameters

string|null $documentName

updateMany(string|null $documentName = null)

Parameters

string|null $documentName

upsert(bool $bool = true)

Set the "upsert" option for an update or findAndUpdate query.

Parameters

bool $bool

where(string|Javascript $javascript)

Specify a JavaScript expression to use for matching documents.

Parameters

string|Javascript $javascript

See also

Expr::where
http://docs.mongodb.org/manual/reference/operator/where/