チュートリアル

Introduction

This is the 10gen-supported PHP driver for MongoDB.

Here's a quick code sample that connects, inserts documents, queries for documents, iterates through query results, and disconnects from MongoDB. There are more details on each step in the tutorial below.


<?php

// connect
$m = new Mongo();

// select a database
$db = $m->comedy;

// select a collection (analogous to a relational database's table)
$collection = $db->cartoons;

// add a record
$obj = array( "title" => "Calvin and Hobbes", "author" => "Bill Watterson" );
$collection->insert($obj);

// add another record, with a different "shape"
$obj = array( "title" => "XKCD", "online" => true );
$collection->insert($obj);

// find everything in the collection
$cursor = $collection->find();

// iterate through the results
foreach ($cursor as $obj) {
    echo $obj["title"] . "\n";
}

?>

This would output:

Calvin and Hobbes
XKCD

接続の作成

データベースサーバに接続するには、次のいずれかの方法を使います。


<?php

$connection = new Mongo(); // localhost:27017 に接続します
$connection = new Mongo( "example.com" ); // リモートホスト (デフォルトのポート) に接続します
$connection = new Mongo( "example.com:65432" ); // リモートホストの指定したポートに接続します

?>

You do not have to explicitly disconnect from the database. When $connection goes out of scope, the connection will be closed automatically and any database resources it was using will be freed.

データベースの取得

データベースを選択するには次のようにします。


<?php

$db = $connection->dbname;

?>

データベースを事前に作っておく必要はありません。存在しないデータベースを選択すれば、新しいデータベースを作ることができます。 Typo には注意しましょう! 意図せずに新しいデータベースを作ってしまい、エラーで悩まされる原因になります。


<?php

$db = $connection->mybiglongdbname;
// 何かをします
$db = $connection->mybiglongdbnme;
// これは別のデータベースに接続してしまいます!

?>

コレクションの取得

コレクションの取得は、データベースの取得と同じ構文で行えます。


<?php

$db = $connection->baz;
$collection = $db->foobar;

// あるいは、もうすこし簡潔に
$collection = $connection->baz->foobar;

?>

ドキュメントの追加

連想配列は、データベース内のコレクションに保存できる基本的なオブジェクトです。何らかの "ドキュメント" はこのような形式になります。


<?php

$doc = array( "name" => "MongoDB",
   "type" => "database",
   "count" => 1,
   "info" => (object)array( "x" => 203, "y" => 102),
   "versions" => array("0.9.7", "0.9.8", "0.9.9")
);

?>

配列やオブジェクトをネストできることに注目しましょう。

ドキュメントを追加するには MongoCollection::insert() を使います。


<?php

$collection->insert( $doc );

?>

MongoCollection::findOne() によるドキュメントの検索

To show that the document we inserted in the previous step is there, we can do a simple MongoCollection::findOne() operation to get a single document from the collection. This method is useful when there only is one document matching the query or you are only interested in one result.


<?php

$obj = $collection->findOne();
var_dump( $obj );

?>

結果は、このようになります。

array(5) {
  ["_id"]=>
  object(MongoId)#6 (0) {
  }
  ["name"]
  string(7) "MongoDB"
  ["type"]=>
  string(8) "database"
  ["count"]=>
  int(1)
  ["info"]=>
  array (2) {
    ["x"]=>
    int(203)
    ["y"]=>
    int(102)
  }
  ["versions"]
  array(3) {
    [0]=>
    string(5) "0.9.7"
    [1]=>
    string(5) "0.9.8"
    [2]=>
    string(5) "0.9.9"
  }
}

Note the _id field has been added automatically to your document. _id is the "primary key" field that is automatically populate for almost all documents in MongoDB.

複数のドキュメントの追加

もう少し意味のある問い合わせをするために、複数のシンプルなドキュメントをコレクションに追加しましょう。これから追加するドキュメントは次のようなものです。


<?php

array( "i" => value );

?>

効率的に、ループで処理します。


<?php

for($i=0; $i<100; $i++) {
    $collection->insert( array( "i" => $i ) );
}

?>

先ほどと同じコレクションに、別のキーを持つ配列を追加していることに注目しましょう。 MongoDB が「スキーマフリー」であると言われるのは、こういう側面があるからです。

コレクション内のドキュメント数

これで 101 件のドキュメントを追加したことになります (先ほどのループで 100 件、そして最初の 1 件)。本当にそうなっているか、MongoCollection::count() メソッドで確認してみましょう。


<?php

echo $collection->count();

?>

結果は 101 と表示されます。

カーソルを使った全ドキュメントの取得

コレクション内のすべてのドキュメントを取得するには MongoCollection::find() を使います。 find() メソッドは MongoCursor オブジェクトを返し、これを使うとクエリにマッチしたドキュメントすべてに対する反復処理ができるようになります。では、すべてのドキュメントを取得して表示させてみましょう。


<?php

$cursor = $collection->find();
foreach ($cursor as $id => $value) {
    echo "$id: ";
    var_dump( $value );
}

?>

これは、コレクション内の全 101 ドキュメントを表示します。 $id はドキュメントの _id フィールドで、 $value はドキュメントそのものです。

問い合わせの条件の設定

クエリを作って MongoCollection::find() メソッドに渡せば、コレクション内のドキュメントのサブセットを取得することができます。たとえば、"i" フィールドの値が 71 であるドキュメントを探したいときは、このようにします。


<?php

$query = array( "i" => 71 );
$cursor = $collection->find( $query );

while( $cursor->hasNext() ) {
    var_dump( $cursor->getNext() );
}

?>

そうすると、ひとつのドキュメントだけが表示されます。

array(2) {
  ["_id"]=>
  object(MongoId)#6 (0) {
  }
  ["i"]=>
  int(71)
  ["_ns"]=>
  "testCollection"
}

クエリによる複数ドキュメントの取得

クエリを使って、コレクションからドキュメントのセットを取得することができます。たとえば、"i" > 50 であるすべてのドキュメントを取得したい場合は次のようにします。


<?php

$query = array( "i" => array( '$gt' => 50 ) ); // '$gt' と、シングルクォートで囲んでいることに注意しましょう
$cursor = $coll->find( $query );

while( $cursor->hasNext() ) {
    var_dump( $cursor->getNext() );
}

?>

これは、i > 50 であるドキュメントをすべて表示します。また、20 < i <= 30 のような範囲を指定することもできます。


<?php

$query = array( "i" => array( "\$gt" => 20, "\$lte" => 30 ) );
$cursor = $coll->find( $query );

while( $cursor->hasNext() ) {
    var_dump( $cursor->getNext() );
}

?>

"$" をエスケープするのをつい忘れてしまいがちになるときは、 '$' 以外の文字を特殊文字として使うようにすることもできます。キーの中にはあらわれないような特殊文字、たとえば ":" をひとつ選び、php.ini に次の行を追加します。

mongo.cmd = ":"

すると、先ほどの例を次のように書けるようになります。


<?php

$query = array( "i" => array( ":gt" => 20, ":lte" => 30 ) );

?>

これは、コードの中でも ini_set("mongo.cmd", ":") のように変更することができます。もちろん、単に $ を使うときはシングルクォートで囲むようにするだけでもかまいません。

インデックスの作成

MongoDB はインデックスをサポートしています。コレクションにインデックスを追加するのは簡単です。インデックスを作るには、対象となるフィールドと並び順を指定します。並び順は、昇順 (1) あるいは降順 (-1) のいずれかです。この例では、"i" フィールドの昇順でインデックスを作成しています。


<?php

$coll->ensureIndex( array( "i" => 1 ) );  // "i" にインデックスを作ります
$coll->ensureIndex( array( "i" => -1, "j" => 1 ) );  // "i" の降順、"j" の昇順でインデックスを作ります

?>