mongocollection.findone(3) [php man page]
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
MONGOGRIDFS(3) 1 MONGOGRIDFS(3)
The MongoGridFS class
INTRODUCTION
Utilities for storing and retrieving files from the database.
GridFS is a storage specification all supported drivers implement. Basically, it defines two collections: files, for file metadata, and
chunks, for file content. If the file is large, it will automatically be split into smaller chunks and each chunk will be saved as a docu-
ment in the chunks collection.
Each document in the files collection contains the filename, upload date, and md5 hash. It also contains a unique _id field, which can be
used to query the chunks collection for the file's content. Each document in the chunks collection contains a chunk of binary data, a
files_id field that matches its file's _id, and the position of this chunk in the overall file.
For example, the files document is something like:
<?php
array("_id" => 123456789, "filename" => "foo.txt", "chunkSize" => 3, "length" => 12);
?>
<?php
array("files_id" => 123456789, "n" => 0, "data" => new MongoBinData("abc"));
array("files_id" => 123456789, "n" => 1, "data" => new MongoBinData("def"));
array("files_id" => 123456789, "n" => 2, "data" => new MongoBinData("ghi"));
array("files_id" => 123456789, "n" => 3, "data" => new MongoBinData("jkl"));
?>
INTER-LANGUAGE COMPATIBILITY
You should be able to use any files created by MongoGridFS with any other drivers, and vice versa. However, some drivers expect that all
metadata associated with a file be in a "metadata" field. If you're going to be using other languages, it's a good idea to wrap info you
might want them to see in a "metadata" field. For example, instead of:
<?php
$grid->storeFile("somefile.txt", array("date" => new MongoDate()));
?>
use something like:
<?php
$grid->storeFile("somefile.txt", array("metadata" => array("date" => new MongoDate())));
?>
THE MongoGridFS"; FAMILY"
MongoGridFS represents the files and chunks collections. MongoGridFS extends MongoCollection, and an instance of MongoGridFS has access to
all of MongoCollection methods, which act on the files collection:
<?php
$grid = $db->getGridFS();
$grid->update(array("filename" => "foo"), $newObj); // update on the files collection
?>
Another example of manipulating metadata:
<?php
// save a file
$id = $grid->storeFile("game.tgz");
$game = $grid->findOne();
// add a downloads counter
$game->file['downloads'] = 0;
$grid->save($game->file);
// increment the counter
$grid->update(array("_id" => $id), array('$inc' => array("downloads" => 1)));
?>
You can also access the chunks collection from an instance of MongoGridFS:
<?php
$chunks = $grid->chunks; // $chunks is a normal MongoCollection
$chunks->insert(array("x" => 4));
?>
There are some methods for MongoGridFS with the same name as MongoCollection methods, that behave slightly differently. For example, Mon-
goGridFS.remove(3) will remove any objects that match the criteria from the files collection and their content from the chunks collection.
To store something new in GridFS, there are a couple options. If you have a filename, you can say:
<?php
$grid->storeFile($filename, array("whatever" => "metadata", "you" => "want"));
?>
If you have a string of bytes that isn't a file, you can also store that using MongoGridFS.storeBytes(3):
<?php
$grid->storeBytes($bytes, array("whatever" => "metadata", "you" => "want"));
?>
Querying a MongoGridFS collection returns a MongoGridFSCursor, which behaves like a normal MongoCursor except that it returns MongoGridFS-
Files instead of associative arrays.
MongoGridFSFiles can be written back to disc using MongoGridFSFile.write(3) or retrieved in memory using MongoGridFSFile.getBytes(3). There
is currently no method that automatically streams chunks, but it would be fairly easy to write by querying the $grid->chunks collection.
MongoGridFSFile objects contain a field file which contains any file metadata.
CLASS SYNOPSIS
MongoGridFS
extends
MongoCollection
Fields
o public MongoCollection$chunks NULL
o protected string$filesName NULL
o protected string$chunksName NULL
Methods
o public MongoGridFS::__construct (MongoDB $db, [string $prefix = "fs"], [mixed $chunks = "fs"])
o public bool MongoGridFS::delete (mixed $id)
o public array MongoGridFS::drop (void )
o public MongoGridFSCursor MongoGridFS::find ([array $query = array()], [array $fields = array()])
o public MongoGridFSFile MongoGridFS::findOne ([mixed $query = array()], [mixed $fields = array()])
o public MongoGridFSFile MongoGridFS::get (mixed $id)
o public mixed MongoGridFS::put (string $filename, [array $metadata = array()])
o public bool MongoGridFS::remove ([array $criteria = array()], [array $options = array()])
o public mixed MongoGridFS::storeBytes (string $bytes, [array $metadata = array()], [array $options = array()])
o public mixed MongoGridFS::storeFile (string $filename, [array $metadata = array()], [array $options = array()])
o public mixed MongoGridFS::storeUpload (string $name, [array $metadata])
SEE ALSO
oMongoDB core docs on GridFS
oLightCube Solutions blog post on saving user uploads
oLightCube Solutions blog post on adding metadata to files
PHP Documentation Group MONGOGRIDFS(3)