MongoGridFSCursor

class MongoGridFSCursor extends MongoCursor implements Traversable, Iterator (View source)

Properties

static bool $slaveOkay
static int $timeout from  MongoCursor
protected MongoGridFS|null $gridfs

Methods

__construct(MongoGridFS $gridfs, MongoClient $connection, string $ns, array $query, array $fields)

Create a new cursor

MongoCursor
awaitData(bool $wait = true)

(PECL mongo >= 1.2.11)
Sets whether this cursor will wait for a while for a tailable cursor to return more data

from  MongoCursor
bool
hasNext()

Checks if there are any more elements in this cursor

from  MongoCursor
array
getNext()

Return the next file to which this cursor points, and advance the cursor

array
getReadPreference()

(PECL mongo >= 1.3.3)

from  MongoCursor
MongoCursor
limit(int $num)

Limits the number of results returned

from  MongoCursor
MongoCursor
partial(bool $okay = true)

(PECL mongo >= 1.2.0)

from  MongoCursor
MongoCursor
setFlag(int $flag, bool $set = true)

(PECL mongo >= 1.2.1)

from  MongoCursor
MongoCursor
setReadPreference(string $read_preference, array $tags)

(PECL mongo >= 1.3.3)

from  MongoCursor
MongoCursor
skip(int $num)

Skips a number of results

from  MongoCursor
MongoCursor
slaveOkay(bool $okay = true)

Sets whether this query can be done on a slave This method will override the static class variable slaveOkay.

from  MongoCursor
MongoCursor
tailable(bool $tail = true)

Sets whether this cursor will be left open after fetching the last results

from  MongoCursor
MongoCursor
immortal(bool $liveForever = true)

Sets whether this cursor will timeout

from  MongoCursor
MongoCursor
timeout(int $ms)

Sets a client-side timeout for this query

from  MongoCursor
bool
dead()

Checks if there are documents that have not been sent yet from the database for this cursor

from  MongoCursor
MongoCursor
snapshot()

Use snapshot mode for the query

from  MongoCursor
MongoCursor
sort(array $fields)

Sorts the results by given fields

from  MongoCursor
MongoCursor
hint(mixed $key_pattern)

Gives the database a hint about the query

from  MongoCursor
MongoCursor
addOption(string $key, mixed $value)

Adds a top-level key/value pair to a query

from  MongoCursor
void
doQuery()

Execute the query

from  MongoCursor
mixed
current()

Returns the current file

mixed
key()

Returns the current result's filename

void
next()

Advances the cursor to the next result

from  MongoCursor
void
rewind()

Returns the cursor to the beginning of the result set

from  MongoCursor
bool
valid()

Checks if the cursor is reading a valid result.

from  MongoCursor
void
reset()

Clears the cursor

from  MongoCursor
array
explain()

Return an explanation of the query, often useful for optimization and debugging

from  MongoCursor
int
count(bool $all = false)

Counts the number of results for this query

from  MongoCursor
MongoCursor
fields(array $f)

Sets the fields for a query

from  MongoCursor
array
info()

Gets the query, fields, limit, and skip for this cursor

from  MongoCursor
MongoCursor
batchSize(int $batchSize)

PECL mongo >= 1.0.11 Limits the number of elements returned in one batch.

from  MongoCursor
MongoCursor
maxTimeMS(int $ms)

(PECL mongo >= 1.5.0) Sets a server-side timeout for this query

from  MongoCursor

Details

at line 1893
__construct(MongoGridFS $gridfs, MongoClient $connection, string $ns, array $query, array $fields)

Create a new cursor

Parameters

MongoGridFS $gridfs

Related GridFS collection
MongoClient $connection

Database connection.
string $ns

Full name of database and collection.
array $query

Database query.
array $fields

Fields to return.

in MongoCursor at line 1324
MongoCursor awaitData(bool $wait = true)

(PECL mongo >= 1.2.11)
Sets whether this cursor will wait for a while for a tailable cursor to return more data

Parameters

bool $wait

[optional]

If the cursor should wait for more data to become available.

Return Value

MongoCursor

Returns this cursor.

in MongoCursor at line 1333
bool hasNext()

Checks if there are any more elements in this cursor

Return Value

bool

Returns true if there is another element

Exceptions

MongoConnectionException
MongoCursorTimeoutException

at line 1900
array getNext()

Return the next file to which this cursor points, and advance the cursor

Return Value

array

Returns the next object

in MongoCursor at line 1350
array getReadPreference()

(PECL mongo >= 1.3.3)

Return Value

array

This function returns an array describing the read preference. The array contains the values type for the string read preference mode (corresponding to the https://secure.php.net/manual/en/class.mongoclient.php MongoClient constants), and tagsets containing a list of all tag set criteria. If no tag sets were specified, tagsets will not be present in the array.

in MongoCursor at line 1359
MongoCursor limit(int $num)

Limits the number of results returned

Parameters

int $num

The number of results to return.

Return Value

MongoCursor

Returns this cursor

Exceptions

MongoCursorException

in MongoCursor at line 1367
MongoCursor partial(bool $okay = true)

(PECL mongo >= 1.2.0)

Parameters

bool $okay

[optional]

If receiving partial results is okay.

Return Value

MongoCursor

Returns this cursor.

in MongoCursor at line 1381
MongoCursor setFlag(int $flag, bool $set = true)

(PECL mongo >= 1.2.1)

Parameters

int $flag

Which flag to set. You can not set flag 6 (EXHAUST) as the driver does not know how to handle them. You will get a warning if you try to use this flag. For available flags, please refer to the wire protocol https://www.mongodb.org/display/DOCS/Mongo+Wire+Protocol#MongoWireProtocol-OPQUERY documentation.

bool $set

[optional]

Whether the flag should be set (TRUE) or unset (FALSE).

Return Value

MongoCursor

in MongoCursor at line 1390
MongoCursor setReadPreference(string $read_preference, array $tags)

(PECL mongo >= 1.3.3)

Parameters

string $read_preference

The read preference mode: MongoClient::RP_PRIMARY, MongoClient::RP_PRIMARY_PREFERRED, MongoClient::RP_SECONDARY, MongoClient::RP_SECONDARY_PREFERRED, or MongoClient::RP_NEAREST.
array $tags

[optional]

The read preference mode: MongoClient::RP_PRIMARY, MongoClient::RP_PRIMARY_PREFERRED, MongoClient::RP_SECONDARY, MongoClient::RP_SECONDARY_PREFERRED, or MongoClient::RP_NEAREST.

Return Value

MongoCursor

Returns this cursor.

in MongoCursor at line 1399
MongoCursor skip(int $num)

Skips a number of results

Parameters

int $num

The number of results to skip.

Return Value

MongoCursor

Returns this cursor

Exceptions

MongoCursorException

in MongoCursor at line 1409
MongoCursor slaveOkay(bool $okay = true)

Sets whether this query can be done on a slave This method will override the static class variable slaveOkay.

Parameters

bool $okay

If it is okay to query the slave.

Return Value

MongoCursor

Returns this cursor

Exceptions

MongoCursorException

in MongoCursor at line 1417
MongoCursor tailable(bool $tail = true)

Sets whether this cursor will be left open after fetching the last results

Parameters

bool $tail

If the cursor should be tailable.

Return Value

MongoCursor

Returns this cursor

in MongoCursor at line 1426
MongoCursor immortal(bool $liveForever = true)

Sets whether this cursor will timeout

Parameters

bool $liveForever

If the cursor should be immortal.

Return Value

MongoCursor

Returns this cursor

Exceptions

MongoCursorException

in MongoCursor at line 1435
MongoCursor timeout(int $ms)

Sets a client-side timeout for this query

Parameters

int $ms

The number of milliseconds for the cursor to wait for a response. By default, the cursor will wait forever.

Return Value

MongoCursor

Returns this cursor

Exceptions

MongoCursorTimeoutException

in MongoCursor at line 1442
bool dead()

Checks if there are documents that have not been sent yet from the database for this cursor

Return Value

bool

Returns if there are more results that have not been sent to the client, yet.

in MongoCursor at line 1450
MongoCursor snapshot()

Use snapshot mode for the query

Return Value

MongoCursor

Returns this cursor

Exceptions

MongoCursorException

in MongoCursor at line 1459
MongoCursor sort(array $fields)

Sorts the results by given fields

Parameters

array $fields

An array of fields by which to sort. Each element in the array has as key the field name, and as value either 1 for ascending sort, or -1 for descending sort

Return Value

MongoCursor

Returns the same cursor that this method was called on

Exceptions

MongoCursorException

in MongoCursor at line 1468
MongoCursor hint(mixed $key_pattern)

Gives the database a hint about the query

Parameters

mixed $key_pattern

Indexes to use for the query.

Return Value

MongoCursor

Returns this cursor

Exceptions

MongoCursorException

in MongoCursor at line 1478
MongoCursor addOption(string $key, mixed $value)

Adds a top-level key/value pair to a query

Parameters

string $key

Fieldname to add.
mixed $value

Value to add.

Return Value

MongoCursor

Returns this cursor

Exceptions

MongoCursorException

in MongoCursor at line 1486
protected void doQuery()

Execute the query

Return Value

void

Exceptions

MongoConnectionException

at line 1907
mixed current()

Returns the current file

Return Value

mixed

Can return any type.

at line 1914
mixed key()

Returns the current result's filename

Return Value

mixed

TKey on success, or null on failure.

in MongoCursor at line 1509
void next()

Advances the cursor to the next result

Return Value

void

Any returned value is ignored.

Exceptions

MongoConnectionException
MongoCursorTimeoutException

in MongoCursor at line 1517
void rewind()

Returns the cursor to the beginning of the result set

Return Value

void

Any returned value is ignored.

Exceptions

MongoConnectionException
MongoCursorTimeoutException

in MongoCursor at line 1524
bool valid()

Checks if the cursor is reading a valid result.

Return Value

bool

The return value will be casted to boolean and then evaluated. Returns true on success or false on failure.

in MongoCursor at line 1531
void reset()

Clears the cursor

Return Value

void

in MongoCursor at line 1538
array explain()

Return an explanation of the query, often useful for optimization and debugging

Return Value

array

Returns an explanation of the query.

in MongoCursor at line 1546
int count(bool $all = false)

Counts the number of results for this query

Parameters

bool $all

Send cursor limit and skip information to the count function, if applicable.

Return Value

int

The number of documents returned by this cursor's query.

in MongoCursor at line 1555
MongoCursor fields(array $f)

Sets the fields for a query

Parameters

array $f

Fields to return (or not return).

Return Value

MongoCursor

Exceptions

MongoCursorException

in MongoCursor at line 1562
array info()

Gets the query, fields, limit, and skip for this cursor

Return Value

array

The query, fields, limit, and skip for this cursor as an associative array.

in MongoCursor at line 1600
MongoCursor batchSize(int $batchSize)

PECL mongo >= 1.0.11 Limits the number of elements returned in one batch.

A cursor typically fetches a batch of result objects and store them locally. This method sets the batchSize value to configure the amount of documents retrieved from the server in one data packet. However, it will never return more documents than fit in the max batch size limit (usually 4MB).

Parameters

int $batchSize

The number of results to return per batch. Each batch requires a round-trip to the server.

If batchSize is 2 or more, it represents the size of each batch of objects retrieved. It can be adjusted to optimize performance and limit data transfer.

If batchSize is 1 or negative, it will limit of number returned documents to the absolute value of batchSize, and the cursor will be closed. For example if batchSize is -10, then the server will return a maximum of 10 documents and as many as can fit in 4MB, then close the cursor.

Warning

A batchSize of 1 is special, and means the same as -1, i.e. a value of 1 makes the cursor only capable of returning one document.

Note that this feature is different from MongoCursor::limit() in that documents must fit within a maximum size, and it removes the need to send a request to close the cursor server-side. The batch size can be changed even after a cursor is iterated, in which case the setting will apply on the next batch retrieval.

This cannot override MongoDB's limit on the amount of data it will return to the client (i.e., if you set batch size to 1,000,000,000, MongoDB will still only return 4-16MB of results per batch).

To ensure consistent behavior, the rules of MongoCursor::batchSize() and MongoCursor::limit() behave a little complex but work "as expected". The rules are: hard limits override soft limits with preference given to MongoCursor::limit() over MongoCursor::batchSize(). After that, whichever is set and lower than the other will take precedence. See below. section for some examples.

Return Value

MongoCursor

Returns this cursor.

in MongoCursor at line 1612
MongoCursor maxTimeMS(int $ms)

(PECL mongo >= 1.5.0) Sets a server-side timeout for this query

Parameters

int $ms

Specifies a cumulative time limit in milliseconds to be allowed by the server for processing operations on the cursor.

Return Value

MongoCursor

This cursor.