From 00e3977ca47c1b456c02811c4db704c11b00205d Mon Sep 17 00:00:00 2001 From: Kristina Chodorow Date: Tue, 15 Dec 2009 16:17:41 +0000 Subject: [PATCH] added more in-depth gridfs description git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@292177 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mongo/mongogridfs.xml | 148 ++++++++++++++++++++++++++++++-- 1 file changed, 140 insertions(+), 8 deletions(-) diff --git a/reference/mongo/mongogridfs.xml b/reference/mongo/mongogridfs.xml index 9e3cbc797f..829c633b68 100644 --- a/reference/mongo/mongogridfs.xml +++ b/reference/mongo/mongogridfs.xml @@ -16,14 +16,69 @@ - MongoGridFS extends - MongoCollection, so any of the methods - in MongoCollection can be used to - manipulate metadata. For example: + 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 document 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: + + 123456789, "filename" => "foo.txt", "chunkSize" => 3, "length" => 12) +]]> + + and the chunks documents look like: + + 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")); +]]> + + Of course, the default chunk size is thousands of bytes, but that makes an unweildy example. + + + +
+ The <classname>MongoGridFS</classname> 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: + + +getGridFS(); +$grid->update(array("filename" => "foo"), $newObj)); // update on the files collection + +?> +]]> + + + + + + Another example of manipulating metadata: + + update(array("_id" => $id), array('$inc' => array("downloads" => 1))); ?> ]]> - - + + + + + + You can also access the chunks collection from an instance of + MongoGridFS: + + +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, MongoGridFS::remove + 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: + + +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: + + +storeBytes($bytes, array("whatever" => "metadata", "you" => "want"); + +?> +]]> + + + + + + Querying a MongoGridFS collection returns a + MongoGridFSCursor, which behaves like a normal + MongoCursor except that it returns + MongoGridFSFiles instead of associative arrays. + + + + MongoGridFSFiles can be written back to disc using + MongoGridFSFile::write or retrieved in memory using + MongoGridFSFile::getBytes. 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. +