# MongoCursor::addOption

(PECL mongo >=1.0.4)

MongoCursor::addOption — Adds a top-level key/value pair to a query

### Description

public MongoCursor::addOption ( string `$key` , mixed `$value` ) : MongoCursor

This is an advanced function and should not be used unless you know what you're doing.

A query can optionally be nested in a "query" field if other options, such as a sort or hint, are given. For instance, adding a sort causes the query to become a subfield of a bigger query object, like:

`<?php
$query = array("query" => $query, "orderby" => $sort);
?>`

This method is for adding a top-level field to a query. It makes the query a subobject (if it isn't already) and adds the key/value pair of your chosing to the top level.

Warning

It cannot be used to add extra criteria to a query on the fly. For instance, this will not work:

`<?php
// NOT CORRECT
$cursor = $users->find()->addOption("name", "joe")->addOption("age", 20);
?>`
This does not query for a user named "joe" with an age of 20.

### Parameters

`key`

  Fieldname to add.

`value`

  Value to add.

### Return Values

Returns this cursor.

### Errors/Exceptions

Throws MongoCursorException if this cursor has started iterating.

### Examples

Example #1 Adding a comment with MongoCursor::addOption() example

MongoDB supports special options to be send to the server. The shell uses the `_addSpecial` option to send a `$comment` to the server. This comment will show up in the profiling log (for slow queries f.e.). In the PHP driver, you use the MongoCursor::addOption() method.

`<?php
$m = new MongoClient;
$c = $m->demo->demo;
$cursor = $c->find();
$cursor->addOption('$comment', "This comment will show up in the profiling log");
foreach ($cursor as $document) { /* empty */ }
?>`

The above example will output something similar to:

    {
        "op" : "query",
        "ns" : "demo.demo",
        "query" : {
            "$query" : {

            },
            "$comment" : "This comment will show up in the profiling log"
        },
        "cursorid" : 168463566447,
        "ntoreturn" : 0,
        "ntoskip" : 0,
        "nscanned" : 101,
        "nscannedObjects" : 101,
        "keyUpdates" : 0,
        "numYield" : 0,
    …

Example #2 MongoCursor::addOption() example

Using MongoCursor::skip() to skip over millions of results can become slow. One way around this is to use `$min` or `$max` options for the query. These can be handy, but they require an index on exactly the fields being searched for. This is an example of how to use `$min` as an alternative to MongoCursor::skip().

`<?php
// make sure we have an index
$c->ensureIndex(array("ts" => 1));
// you may have to modify this to run in a reasonable amount of time on slow
// machines (should take about 30 seconds on a good machine)
for ($i = 0; $i < 30000000; $i++) {
$c->insert(array("ts" => new MongoDate(), "i" => $i));
}
$now = strtotime("now");
// find documents inserted in the last 2 seconds
$cursor = $c->find()->addOption('$min', array("ts" => $now-2));
?>`