# MongoGridFS クラス

(PECL mongo >=0.9.0)

## はじめに

データベースにファイルを格納したり、データベースからファイルを取得したりするためのユーティリティです。

GridFS はストレージの仕様で、すべてのドライバがこれを実装しています。 基本的に、これはふたつのコレクションを定義しています。 ファイルのメタデータ用の files、 そしてファイルの中身用の chunks です。 大きなファイルの場合は自動的に小さなチャンクに分割し、 各チャンクが chunks コレクションのドキュメントとして保存されます。

files コレクション内の各ドキュメントには、ファイル名とアップロードした日付、 そして md5 ハッシュが含まれています。 また、一意な _id フィールドも持っており、 これを使ってそのファイルの中身がある chunks コレクションを探すことができます。 chunks コレクション内の各ドキュメントには、バイナリデータのチャンクの他に そのファイルの _id フィールドにマッチする files_id フィールドが含まれ、さらに ファイル全体の中でそのチャンクがどの位置にあるのかという情報も含まれます。

files ドキュメントの内容は、たとえばこのようになります。

`<?php
array("_id" => 123456789, "filename" => "foo.txt", "chunkSize" => 3, "length" => 12);
?>`
そして chunks ドキュメントはこのようになります。
`<?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"));
?>`
もちろん、デフォルトのチャンクサイズはもっと大きなものになります。 ただそれでは例が見づらくなるのでこのようにしました。

## 言語間の互換性

MongoGridFS で作ったファイルは他のどのドライバでも使えなければなりませんし、 逆もまたそうです。しかし中には、ファイルに関連するすべてのメタデータが "metadata" フィールドにあるという前提で動くドライバもあります。 他の言語を使う可能性があるのなら、見せたい情報を "metadata" フィールドに入れておくといいでしょう。たとえば、

`<?php
$grid->storeFile("somefile.txt", array("date" => new MongoDate()));
?>`

こう書くかわりに、下のようにするのです。

`<?php
$grid->storeFile("somefile.txt", array("metadata" => array("date" => new MongoDate())));
?>`

## MongoGridFS ファミリー

MongoGridFS は files コレクションと chunks コレクションを表します。MongoGridFS は MongoCollection を継承しており、MongoGridFS のインスタンスは MongoCollection のすべてのメソッドにアクセスできます。 これは files コレクションに対する操作となります。

`<?php
$grid = $db->getGridFS();
$grid->update(array("filename" => "foo"), $newObj); // files コレクションを更新します
?>`

メタデータを操作する別の例を示します。

`<?php
// ファイルを保存します
$id = $grid->storeFile("game.tgz");
$game = $grid->findOne();
// ダウンロードカウンタを追加します
$game->file['downloads'] = 0;
$grid->save($game->file);
// カウンタをひとつ加算します
$grid->update(array("_id" => $id), array('$inc' => array("downloads" => 1)));
?>`

MongoGridFS のインスタンスから、 chunks コレクションにアクセスすることもできます。

`<?php
$chunks = $grid->chunks; // $chunks は通常の MongoCollection です
$chunks->insert(array("x" => 4));
?>`

MongoGridFS のメソッドの中には MongoCollection のメソッドと同じ名前のものもあります。 これらのメソッドの挙動は微妙に異なります。 たとえば MongoGridFS::remove() は、条件にマッチするすべてのオブジェクトを files コレクションから削除し、 対応する chunks コレクションの中身も同時に削除します。

新しい何かを GridFS に格納する際にはいくつかのオプションがあります。 ファイル名がわかる場合は、次のように書くことができます。

`<?php
$grid->storeFile($filename, array("whatever" => "metadata", "you" => "want"));
?>`

ファイルではない文字列やバイト列の場合は、 MongoGridFS::storeBytes() を使うこともできます。

`<?php
$grid->storeBytes($bytes, array("whatever" => "metadata", "you" => "want"));
?>`

MongoGridFS コレクションへの問い合わせ結果として返されるのは MongoGridFSCursor です。これは通常の MongoCursor とほぼ同様の動きをしますが、連想配列ではなく MongoGridFSFiles を返すという点が異なります。

MongoGridFSFiles をディスクに書き出すには MongoGridFSFile::write() を、メモリに取り込むには MongoGridFSFile::getBytes() を使います。 自動的にチャンクをつなげるメソッドは今のところありませんが、 $grid->chunks コレクションに問い合わせて自分でつなげるのはきわめて簡単です。

MongoGridFSFile オブジェクトには、 ファイルのメタデータを格納する file フィールドが含まれます。

## クラス概要

extends MongoCollection {
/* フィールド */
public MongoCollection $chunks = `NULL` ;
protected string $filesName = `NULL` ;
protected string $chunksName = `NULL` ;
/* メソッド */
public __construct ( MongoDB `$db` [, string `$prefix` = "fs" [, mixed `$chunks` = "fs" ]] )
public delete ( mixed `$id` ) : bool|array
public drop ( void ) : array
public find ([ array `$query` = array() [, array `$fields` = array() ]] ) : MongoGridFSCursor
public findOne ([ mixed `$query` = array() [, mixed `$fields` = array() ]] ) : MongoGridFSFile
public get ( mixed `$id` ) : MongoGridFSFile
public put ( string `$filename` [, array `$metadata` = array() [, array `$options` = array() ]] ) : mixed
public remove ([ array `$criteria` = array() [, array `$options` = array() ]] ) : bool|array
public storeBytes ( string `$bytes` [, array `$metadata` = array() [, array `$options` = array() ]] ) : mixed
public storeFile ( string|resource `$filename` [, array `$metadata` = array() [, array `$options` = array() ]] ) : mixed
public storeUpload ( string `$name` [, array `$metadata` ] ) : mixed
}

## 参考

- MongoDB コアドキュメントの » GridFS
- LightCube Solutions blog の記事 » ユーザーがアップロードした内容の保存
- LightCube Solutions blog の記事 » メタデータの追加

## 目次

- MongoGridFS::__construct — 新しいファイルコレクションを作成する
- MongoGridFS::delete — ファイルとそのチャンクをデータベースから削除する
- MongoGridFS::drop — ファイルコレクションおよびチャンクコレクションを削除する
- MongoGridFS::find — ファイルを問い合わせる
- MongoGridFS::findOne — 条件にマッチする単一のファイルを返す
- MongoGridFS::get — ファイルをデータベースから取得する
- MongoGridFS::put — ファイルをデータベースに格納する
- MongoGridFS::remove — ファイルとそのチャンクをデータベースから削除する
- MongoGridFS::storeBytes — バイト列をデータベースに格納する
- MongoGridFS::storeFile — ファイルをデータベースに格納する
- MongoGridFS::storeUpload — アップロードされたファイルをデータベースに格納する