MongoCursor::addOption

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

&reftitle.description; public `MongoCursor` `MongoCursor::addOption` `string` `key` `mixed` `value`

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.

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.
&reftitle.parameters;

`key`

- Fieldname to add.

`value`

- Value to add.

&reftitle.returnvalues;

Returns this cursor.

&reftitle.errors;

Throws `MongoCursorException` if this cursor has started iterating.

&reftitle.examples;

### `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));

    ?>