MONGOCOLLECTION.FINDONE(3) 1 MONGOCOLLECTION.FINDONE(3)MongoCollection::findOne - Queries this collection, returning a single element
SYNOPSIS
public array MongoCollection::findOne ([array $query = array()], [array $fields = array()], [array $options = array()])
DESCRIPTION
As opposed to MongoCollection.find(3), this method will return only the first result from the result set, and not a MongoCursor that can
be iterated over.
PARAMETERS
o $query
- The fields for which to search. MongoDB's query language is quite extensive. The PHP driver will in almost all cases pass the
query straight through to the server, so reading the MongoDB core docs on find is a good idea.
Warning
Please make sure that for all special query operaters (starting with $) you use single quotes so that PHP doesn't try to
replace "$exists" with the value of the variable $exists.
o $fields
- Fields of the results to return. The array is in the format array('fieldname' => true, 'fieldname2' => true). The _id field is
always returned.
o $options
- This parameter is an associative array of the form array("name" => <value>, ...). Currently supported options are:
o "maxTimeMS"Specifies a cumulative time limit in milliseconds for processing the operation (does not include idle time). If
the operation is not completed within the timeout period, a MongoExecutionTimeoutException will be thrown.
RETURN VALUES
Returns record matching the search or NULL.
ERRORS /EXCEPTIONS
Throws MongoConnectionException if it cannot reach the database.
CHANGELOG
+--------+------------------------------------+
|Version | |
| | |
| | Description |
| | |
+--------+------------------------------------+
| 1.5.0 | |
| | |
| | Added optional $options argument. |
| | |
+--------+------------------------------------+
EXAMPLES
Example #1
MongoCollection::findOne document by its id.
This example demonstrates how to find a single document in a collection by its id.
<?php
$articles = $mongo->my_db->articles;
$article = $articles->findOne(array('_id' => new MongoId('47cc67093475061e3d9536d2')));
?>
Example #2
MongoCollection::findOne document by some condition.
This example demonstrates how to find a single document in a collection by some condition and limiting the returned fields.
<?php
$users = $mongo->my_db->users;
$user = $users->findOne(array('username' => 'jwage'), array('password'));
print_r($user);
?>
The above example will output something similar to:
Array
(
[_id] => MongoId Object
(
)
[password] => test
)
Notice how even though the document does have a username field, we limited the results to only contain the password field.
SEE ALSO MongoCollection.find(3), MongoCollection.insert(3), MongoDB core docs on find..
PHP Documentation Group MONGOCOLLECTION.FINDONE(3)
Check Out this Related Man Page
MONGOCOLLECTION.FINDANDMODIFY(3) 1 MONGOCOLLECTION.FINDANDMODIFY(3)MongoCollection::findAndModify - Update a document and return it
SYNOPSIS
public array MongoCollection::findAndModify (array $query, [array $update], [array $fields], [array $options])
DESCRIPTION
The findAndModify command atomically modifies and returns a single document. By default, the returned document does not include the modi-
fications made on the update. To return the document with the modifications made on the update, use the $new option.
PARAMETERS
o $query
- The query criteria to search for.
o $update
- The update criteria.
o $fields
- Optionally only return these fields.
o $options
- An array of options to apply, such as remove the match document from the DB and return it.
+----------------+---------------------------------------------------+
| Option | |
| | |
| | Description |
| | |
+----------------+---------------------------------------------------+
| $sort array | |
| | |
| | Determines which document the operation will |
| | modify if the query selects multiple documents. |
| | findAndModify will modify the first document in |
| | the sort order specified by this argument. |
| | |
|$remove boolean | |
| | |
| | Optional if $update field exists. When TRUE, |
| | removes the selected document. The default is |
| | FALSE. |
| | |
| $update array | |
| | |
| | Optional if $remove field exists. Performs an |
| | update of the selected document. |
| | |
| $new boolean | |
| | |
| | Optional. When TRUE, returns the modified docu- |
| | ment rather than the original. The findAndModify |
| | method ignores the $new option for remove opera- |
| | tions. The default is FALSE. |
| | |
|$upsert boolean | |
| | |
| | Optional. Used in conjunction with the $update |
| | field. When TRUE, the findAndModify command cre- |
| | ates a new document if the query returns no docu- |
| | ments. The default is false. In MongoDB 2.2, the |
| | findAndModify command returns NULL when upsert is |
| | TRUE. |
| | |
| | |
| | |
| | |
| | |
+----------------+---------------------------------------------------+
RETURN VALUES
Returns the original document, or the modified document when $new is set.
ERRORS /EXCEPTIONS
Throws MongoResultException on failure.
EXAMPLES
Example #1
MongoCollection::findAndModify example
<?php
$m = new Mongo;
$col = $m->selectDB("test")->jobs;
$col->insert(array(
"name" => "Next promo",
"inprogress" => false,
"priority" => 0,
"tasks" => array( "select product", "add inventory", "do placement"),
) );
$col->insert(array(
"name" => "Biz report",
"inprogress" => false,
"priority" => 1,
"tasks" => array( "run sales report", "email report" )
) );
$col->insert(array(
"name" => "Biz report",
"inprogress" => false,
"priority" => 2,
"tasks" => array( "run marketing report", "email report" )
),
array("w" => 1)
);
$retval = $col->findAndModify(
array("inprogress" => false, "name" => "Biz report"),
array('$set' => array('inprogress' => true, "started" => new MongoDate())),
null,
array(
"sort" => array("priority" => -1),
"new" => true,
)
);
var_dump($retval);
?>
The above example will output something similar to:
array(6) {
["_id"]=>
object(MongoId)#7(1) {
["$id"]=>
string(24) "5091b5b244415e8cc3000002"
}
["inprogress"]=>
bool(true)
["name"]=>
string(10) "Biz report"
["priority"]=>
int(2)
["started"]=>
object(MongoDate)#8(2) {
["sec"]=>
int(1351726514)
["usec"]=>
int(925000)
}
["tasks"]=>
array(2) {
[0]=>
string(20) "run marketing report"
[1]=>
string(12) "email report"
}
}
Example #2
MongoCollection::findAndModify error handling
<?php
$m = new Mongo;
$col = $m->selectDB("test")->jobs;
try {
$retval = $col->findAndModify(
array("inprogress" => false, "name" => "Next promo"),
array('$pop' => array("tasks" => -1)),
array("tasks" => array('$pop' => array("stuff"))),
array("new" => true)
);
} catch(MongoResultException $e) {
echo $e->getCode(), " : ", $e->getMessage(), "
";
var_dump($e->getDocument());
}
?>
The above example will output something similar to:
13097 : exception: Unsupported projection option: $pop
array(3) {
["errmsg"]=>
string(46) "exception: Unsupported projection option: $pop"
["code"]=>
int(13097)
["ok"]=>
float(0)
}
SEE ALSO The MongoDB findAndModify command docs.PHP Documentation Group MONGOCOLLECTION.FINDANDMODIFY(3)