mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-27 14:28:56 +00:00
74dfdc51ec
These were previously removed in r329063, but should stick around for the link checker script. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@329065 c90b9560-bf6c-de11-be94-00142212c4b1
292 lines
8.5 KiB
XML
292 lines
8.5 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
|
|
<phpdoc:classref xml:id="class.mongogridfs" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<title>The MongoGridFS class</title>
|
|
<titleabbrev>MongoGridFS</titleabbrev>
|
|
|
|
<partintro>
|
|
|
|
<!-- {{{ Mongogridfs intro -->
|
|
<section xml:id="mongogridfs.intro">
|
|
&reftitle.intro;
|
|
<para>
|
|
Utilities for storing and retrieving files from the database.
|
|
</para>
|
|
|
|
<para>
|
|
GridFS is a storage specification all supported drivers implement.
|
|
Basically, it defines two collections: <literal>files</literal>, for file
|
|
metadata, and <literal>chunks</literal>, 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.
|
|
</para>
|
|
|
|
<para>
|
|
Each document in the files collection contains the filename, upload date,
|
|
and md5 hash. It also contains a unique <literal>_id</literal> 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
|
|
<literal>files_id</literal> field that matches its file's
|
|
<literal>_id</literal>, and the position of this chunk in the overall file.
|
|
</para>
|
|
|
|
<para>
|
|
For example, the files document is something like:
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
array("_id" => 123456789, "filename" => "foo.txt", "chunkSize" => 3, "length" => 12);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
and the chunks documents look like:
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?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"));
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
Of course, the default chunk size is thousands of bytes, but that makes an unwieldy example.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Inter-Language Compatibility</title>
|
|
<para>
|
|
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:
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$grid->storeFile("somefile.txt", array("date" => new MongoDate()));
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
use something like:
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$grid->storeFile("somefile.txt", array("metadata" => array("date" => new MongoDate())));
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>The <classname>MongoGridFS</classname> Family</title>
|
|
|
|
<para>
|
|
<classname>MongoGridFS</classname> represents the files and chunks
|
|
collections. <classname>MongoGridFS</classname> extends MongoCollection,
|
|
and an instance of <classname>MongoGridFS</classname> has access to all of
|
|
<classname>MongoCollection</classname> methods, which act on the files
|
|
collection:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$grid = $db->getGridFS();
|
|
$grid->update(array("filename" => "foo"), $newObj); // update on the files collection
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<para>
|
|
Another example of manipulating metadata:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?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)));
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<para>
|
|
You can also access the chunks collection from an instance of
|
|
<classname>MongoGridFS</classname>:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$chunks = $grid->chunks; // $chunks is a normal MongoCollection
|
|
$chunks->insert(array("x" => 4));
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
There are some methods for <classname>MongoGridFS</classname> with the same
|
|
name as <classname>MongoCollection</classname> methods, that behave
|
|
slightly differently. For example, <function>MongoGridFS::remove</function>
|
|
will remove any objects that match the criteria from the files collection
|
|
and their content from the chunks collection.
|
|
</para>
|
|
|
|
<para>
|
|
To store something new in GridFS, there are a couple options. If you have
|
|
a filename, you can say:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$grid->storeFile($filename, array("whatever" => "metadata", "you" => "want"));
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<para>
|
|
If you have a string of bytes that isn't a file, you can also store that
|
|
using <function>MongoGridFS::storeBytes</function>:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$grid->storeBytes($bytes, array("whatever" => "metadata", "you" => "want"));
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<para>
|
|
Querying a <classname>MongoGridFS</classname> collection returns a
|
|
<classname>MongoGridFSCursor</classname>, which behaves like a normal
|
|
<classname>MongoCursor</classname> except that it returns
|
|
<classname>MongoGridFSFiles</classname> instead of associative arrays.
|
|
</para>
|
|
|
|
<para>
|
|
<classname>MongoGridFSFiles</classname> can be written back to disc using
|
|
<function>MongoGridFSFile::write</function> or retrieved in memory using
|
|
<function>MongoGridFSFile::getBytes</function>. There is currently no
|
|
method that automatically streams chunks, but it would be fairly easy to
|
|
write by querying the <literal>$grid->chunks</literal> collection.
|
|
</para>
|
|
|
|
<para>
|
|
<classname>MongoGridFSFile</classname> objects contain a field file which
|
|
contains any file metadata.
|
|
</para>
|
|
</section>
|
|
<!-- }}} -->
|
|
|
|
<section xml:id="mongogridfs.synopsis">
|
|
&reftitle.classsynopsis;
|
|
|
|
<!-- {{{ Synopsis -->
|
|
<classsynopsis>
|
|
<ooclass><classname>MongoGridFS</classname></ooclass>
|
|
|
|
<!-- {{{ Class synopsis -->
|
|
<classsynopsisinfo>
|
|
<ooclass>
|
|
<modifier>extends</modifier>
|
|
<classname>MongoCollection</classname>
|
|
</ooclass>
|
|
</classsynopsisinfo>
|
|
<!-- }}} -->
|
|
|
|
<classsynopsisinfo role="comment">Fields</classsynopsisinfo>
|
|
<fieldsynopsis>
|
|
<modifier>public</modifier>
|
|
<type>MongoCollection</type>
|
|
<varname>chunks</varname>
|
|
<initializer>&null;</initializer>
|
|
</fieldsynopsis>
|
|
<fieldsynopsis>
|
|
<modifier>protected</modifier>
|
|
<type>string</type>
|
|
<varname>filesName</varname>
|
|
<initializer>&null;</initializer>
|
|
</fieldsynopsis>
|
|
<fieldsynopsis>
|
|
<modifier>protected</modifier>
|
|
<type>string</type>
|
|
<varname>chunksName</varname>
|
|
<initializer>&null;</initializer>
|
|
</fieldsynopsis>
|
|
|
|
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
|
|
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongogridfs')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
|
|
</classsynopsis>
|
|
<!-- }}} -->
|
|
|
|
</section>
|
|
|
|
<section>
|
|
&reftitle.seealso;
|
|
<simplelist>
|
|
<member>MongoDB core docs on <link xlink:href="&url.mongodb.docs.gridfs;">GridFS</link></member>
|
|
<member>LightCube Solutions blog post on <link xlink:href="&url.mongodb.gridfs.fileupload;">saving user uploads</link></member>
|
|
<member>LightCube Solutions blog post on <link xlink:href="&url.mongodb.gridfs.metadata;">adding metadata to files</link></member>
|
|
</simplelist>
|
|
</section>
|
|
</partintro>
|
|
|
|
&reference.mongo.entities.mongogridfs;
|
|
|
|
</phpdoc:classref>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|