(PECL mongo >=0.9.0)
Mongo::__construct — 新しいデータベース接続オブジェクトを作成する
$server = "mongodb://localhost:27017"
[, array $options = array("connect" => TRUE)
]] )パラメータを省略した場合は、"localhost:27017" (あるいは php.ini の mongo.default_host と mongo.default_port で設定した場所) に接続します。
server は次のような形式にしなければなりません。
mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
接続文字列は常に mongodb:// で始まります。 この部分が、接続文字列であることを表しています。
username と password を指定すれば、コンストラクタが接続を確立する際にデータベースへの認証を試みます。 ユーザー名とパスワードはオプションで、もし指定するならその後に @ を続けなければなりません。
少なくともひとつのホストを指定しなければなりません (ポートはオプションで、デフォルトは常に 27017 となります)。 そのあとに、接続させたいホストをいくつでも続けることができます。 ホスト名はカンマ区切りで並べ、少なくともひとつのホストへの接続が成功すれば コンストラクタは正常な結果を返します。 どのホストにも接続できなかった場合は MongoConnectionException をスローします。
ユーザー名とパスワードを指定したときには、認証先のデータベースも指定することになるでしょう。 db を省略した場合は "admin" を使います。
オプションのクエリ文字列を使って、追加オプションを指定できます。
同じオプションを options 配列でもサポートしているので、
そちらでももう一度説明します。
オプションの設定によっては、レプリカセット環境でセカンダリノードから読み込むときの方法に影響するものもあります。 読み込みの優先順位に関する動きについての詳しい説明は 優先読み込み のページを参照ください。
server
サーバー名。
options
接続オプションの配列。現在使用できるオプションは次のとおりです。
"connect"
コンストラクタで接続を行うか。デフォルトは
TRUE。FALSE にすると、ドライバが
自動的に サーバーと接続するようになります。
クエリの実行に接続が必要かどうかは関係ありません。
それ以外に、手動で
Mongo::connect() を実行する方法もあります。
このオプションは、接続文字列で使うことはできません。
"db"
ホスト名に含めるかわりに、認証対象のデータベースをここで指定することができます。 ホスト名で設定したデータベースを上書きします。
"password"
ホスト名に含めるかわりに、パスワードをここで指定することができます。 パスワードに "@" を含む場合などに特に便利です。 ホスト名で設定したパスワードを上書きします。
"readPreference"
優先読み込みの型を指定します。優先読み込みを使うと、 どのセカンダリからデータを読み込めるのかを制御できるようになります。
指定できる値は primary、 primaryPreferred、 secondary、secondaryPreferred および nearest です。
詳細な情報は、優先読み込みのドキュメントを参照ください。
"readPreferenceTags"
優先読み込みのタグを指定します。タグを readPreference と組み合わせて使うと、 どのセカンダリからデータを読み込めるのかをより細かく制御できるようになります。
詳細な情報は、優先読み込みのドキュメントを参照ください。
"replicaSet"
接続先のレプリカセットの名前。指定した場合は、プライマリが自動的に決まります。 つまり、ドライバは、リストに上がっていないサーバーに接続することになるかもしれません。 詳細は、以下のレプリカセットの例を参照ください。
"timeout"
ドライバがデータベースへの接続を試みる時間の長さ (ミリ秒単位)。
"username"
ホスト名に含めるかわりに、ユーザー名をここで指定することができます。 ユーザー名に ":" を含む場合などに特に便利です。 ホスト名で設定したユーザー名を上書きします。
"w"
w オプションは、ドライバの Write Concern、 つまりドライバがレプリカセットへの書き込みをどれくらいブロックするかを制御します。
正の整数は、レプリカセット内のいくつの ノードが書き込み指示を受け取ったらドライバが処理を続行するのかを指定します。 値を 3 にすると、 書き込みがレプリカセット内であと 2 台に適用されてからプライマリにも適用します。
文字列を指定すると、どのタグセットを書き込み時に考慮するのかを指定したことになります。 "majority" は特別な値で、 参加しているノードの過半数に書き込み操作が適用された時点でプライマリにも適用します。
"wTimeout"
このオプションは "w" と組み合わせて使います。 書き込み操作がうまくいくまでサーバーが何ミリ秒待つのかを制御します。 これよりも長い時間がかかると、サーバーからドライバに対して「長すぎる」 という通知を出し、ドライバが MongoCursorException をスローします。
新しいデータベース接続オブジェクトを返します。
指定したすべてのホスト名へのデータベースへの接続に失敗した場合に MongoConnectionException をスローします。 指定したユーザー名やパスワードが間違っている場合にも MongoConnnectionException をスローします。 一般的な例外とその原因については MongoConnectionException のドキュメントを参照ください。
| バージョン | 説明 |
|---|---|
| 1.3.0 |
"readPreference"、 "readPreferenceTags"、"w" および "wTimeout" オプションが追加されました。 |
| 1.2.0 |
"username" および "password" オプションが追加されました。 "persist" オプションが削除されました。すべての接続は持続的な接続となります。 今でも使うことはできますが、何の影響も及ぼしません。
"replicaSet" オプションは、boolean ではなく文字列を受け取るようになりました。 |
| 1.0.9 | "replicaSet" オプションが追加されました。 |
| 1.0.2 |
コンストラクタがオプションの配列を受け取るようになりました。 以前のバージョンでは、コンストラクタは以下のパラメータを受け取っていました。
|
例1 Mongo::__construct() でのレプリカセットの例
この例は、レプリカセットに接続する方法を示します。 このでは、次の三つのサーバー sf1.example.com、sf2.example.com および ny1.example.com があるものと仮定します。 プライマリは、これらのうちのいずれかひとつとなります。
<?php
// カンマ区切りのサーバー名をコンストラクタに渡します
$m1 = new Mongo("mongodb://sf2.example.com,ny1.example.com", array("replicaSet" => "myReplSet"));
// ひとつのシードを渡すだけで、ドライバがそこから完全なリストを取得して
// シードからプライマリを探します
$m2 = new Mongo("mongodb://ny1.example.com", array("replicaSet" => "myReplSet"));
?>
現在のプライマリで処理に失敗した場合、 セカンダリサーバーのうちのどれを新しいプライマリにするかをドライバが判断し、 自動的にその接続を開始させます。この自動フェイルオーバー機能は、 replicaSet を指定しなければ正しく動作しません。
シードリストの中の少なくともひとつのシードに接続できなければ、 ドライバからレプリカセットに接続することはできません。
二つの別のレプリカセットからのシードを指定した場合の挙動は未定義です。
レプリカセットに関する詳細な情報は » コアドキュメント を参照ください。
例2 ドメインソケットへの接続
バージョン 1.0.9 以降では、ローカルで実行している MongoDB への接続に UNIX ドメインソケットを使えるようになりました。これは、 ネットワーク経由で接続するよりもわずかに高速です。
バージョン 1.5.0 では、MongoDB サーバーは自動的に /tmp/mongodb-<port>.sock でソケットをオープンします。 ここに接続するには、接続文字列でこのパスを指定します。
<?php
// MongoDB サーバーが、ローカルのポート 20000 で起動しています
$m = new Mongo("mongodb:///tmp/mongodb-20000.sock");
?>
これは、その他の接続とも組み合わせることができます。
<?php
// まずドメインソケットに接続し、失敗したときにはローカルホストへの接続を使います
$m = new MongoDB("mongodb:///tmp/mongodb-27017.sock,localhost:27017");
?>
例3 Mongo::__construct() での認証の例
認証を使うには、admin データベースにユーザーが存在しなければなりません。 Mongo シェルでユーザーを作るには、次のようにします。
> use admin
switched to db admin
> db.addUser("testUser", "testPass");
{
"_id" : ObjectId("4b21272fd9ab21611d19095c"),
"user" : "testUser",
"pwd" : "03b9b27e0abf1865e2f6fcbd9845dd59"
}
>
ユーザーを作ったら、このユーザー名 "testUser" とパスワード "testPass" で次のようにして認証させることができます。
<?php
$m = new Mongo("mongodb://testUser:testPass@localhost");
?>
例4 Mongo::__construct() での優先読み込みの例
<?php
// "east" データセンターにある最も近いサーバーを優先します
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new Mongo($uri, array('replicaSet' => 'rs'));
詳細な情報は、このマニュアルの 優先読み込み のページを参照ください。