MongoClient
PHP Manual

Mongo::__construct

(PECL mongo >=0.9.0)

Mongo::__construct — 新しいデータベース接続オブジェクトを作成する

このメソッドを定義している拡張モジュールは非推奨です。 かわりに MongoDB 拡張モジュールを使うべきです。 このメソッドの代替として、以下が使えます。

説明

public MongoClient::__construct ([ string $server = "mongodb://localhost:27017" [, array $options = array("connect" => TRUE) [, array $driver_options ]]] )

パラメータを省略した場合は、"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

接続オプションの配列。現在使用できるオプションは次のとおりです。

  • "authMechanism"

    以下の機構が選べます。

    認証機構 説明 利用可能
    MONGODB-CR チャレンジレスポンス方式を使った認証。デフォルトです。 すべてのバージョンの MongoDB
    X509 X509 証明書による認証。 MongoDB 2.6。OpenSSL が有効な場合のみ。
    PLAIN 暗号化されていないユーザー名とパスワードによる認証。SSL 接続上でのみ使うこと。サードパーティの LDAP サーバー経由での MongoDB へのログインの際に利用する。 MongoDB Enterprise 2.4。CyrusSASL2 を使うようにドライバをコンパイルしておく必要がある。
    GSSAPI ケルベロス認証 MongoDB Enterprise 2.4。CyrusSASL2 を使うようにドライバをコンパイルしておく必要がある。

  • "authSource"

    ユーザーが定義されているデータベース名を設定します。

  • "connect"

    コンストラクタで接続を行うか。デフォルトは TRUE。FALSE にすると、ドライバが 自動的に サーバーと接続するようになります。 クエリの実行に接続が必要かどうかは関係ありません。 それ以外に、手動で Mongo::connect() を実行する方法もあります。

    警告

    このオプションは、接続文字列で使うことはできません。

  • "connectTimeoutMS"

    接続を開こうとしてタイムアウトになるまでの時間の長さ（ミリ秒単位）。 デフォルトは 60000 (60 秒) です。

    -1 を指定すると、接続タイムアウトを適用せず、PHP は default_socket_timeout を利用します。

  • "db"

    ホスト名に含めるかわりに、認証対象のデータベースをここで指定することができます。 ホスト名で設定したデータベースを上書きします。

  • "fsync"

    "fsync" を設定すると、データベース上のすべての書き込み操作は、 その書き込みがディスクに同期されるまでは成功とみなさないようになります。 書き込み処理の速度は大幅に低下しますが、書き込みがきちんと成功してディスクに書き出されたことを保証できます。

    MongoDB のジャーナリングを有効にしている (デフォルト) 場合、このオプションは "journal" と同じ意味になります。 ジャーナリングが無効になっている場合は、このオプションは、 書き込み操作がディスク上のデータベースファイルに同期されることを保証します。

    注意: ジャーナリングを有効にしている場合は、"fsync" ではなく "journal" を使うことを強く推奨します。 "fsync" と "journal" を同時に使わないようにしましょう。 同時に使うとエラーが発生します。

  • "journal"

    "journal" を設定すると、データベース上のすべての書き込み操作が、 データベースがジャーナルへの変更をディスクにフラッシュするまでブロックされます。 書き込み処理の速度は多少低下しますが、書き込みがきちんと成功して、 万一システムに障害が発生したとしても復旧可能なことを保証できます。

    注意: ジャーナリングが無効になっている場合にこのオプションを使うと、 MongoDB 2.6+ ではエラーが発生して書き込みが失敗します。 それより前のバージョンでは、単純にこのオプションを無視します。

  • "gssapiServiceName"

    » Kerberos サービスプリンシパル を設定します。authMechanism=GSSAPI の場合にのみ用いられるもので、デフォルトは "mongodb" です。

  • "password"

    ホスト名に含めるかわりに、パスワードをここで指定することができます。 パスワードに "@" を含む場合などに特に便利です。 ホスト名で設定したパスワードを上書きします。

  • "readPreference"

    優先読み込みの型を指定します。優先読み込みを使うと、 どのセカンダリからデータを読み込めるのかを制御できるようになります。

    指定できる値は primary、 primaryPreferred、 secondary、secondaryPreferred および nearest です。

    詳細な情報は、優先読み込みのドキュメントを参照ください。

  • "readPreferenceTags"

    優先読み込みのタグを指定します。タグを readPreference と組み合わせて使うと、 どのセカンダリからデータを読み込めるのかをより細かく制御できるようになります。

    詳細な情報は、優先読み込みのドキュメントを参照ください。

  • "replicaSet"

    接続先のレプリカセットの名前。指定した場合は、プライマリが自動的に決まります。 つまり、ドライバは、リストに上がっていないサーバーに接続することになるかもしれません。 詳細は、以下のレプリカセットの例を参照ください。

  • "secondaryAcceptableLatencyMS"

    セカンダリから (優先読み込みを使って) 読み込むときに、 secondaryAcceptableLatencyMS 以上はなれているセカンダリからは読み込みません。 デフォルトは 15 です。

  • "socketTimeoutMS"

    ソケットの操作 (読み書き) がタイムアウトになるまでの時間の長さ。 ミリ秒単位で、デフォルトは 30000 (30 秒) です。

    -1 を設定すると、ソケットの操作を永遠にブロックします。 このオプションは、操作単位以外でも設定できます。 クエリごとに設定するには MongoCursor::timeout()、 書き込みメソッドごとに設定するには "socketTimeoutMS" オプションを使います。

    注意: これはクライアント側のタイムアウトです。書き込み操作がタイムアウトに達してしまうと、 サーバーが実際に書き込みを受信したかどうかを知るすべがなくなります。そして、 書き込みの結果を返す代わりに MongoCursorTimeoutException をスローします。

  • "ssl"

    boolean です。MongoDB への接続で SSL を有効にするかどうかを指定します。 証明書のような追加オプションは SSL コンテキストオプション で設定します。

  • "username"

    ホスト名に含めるかわりに、ユーザー名をここで指定することができます。 ユーザー名に ":" を含む場合などに特に便利です。 ホスト名で設定したユーザー名を上書きします。

  • "w"

    w オプションは、ドライバの Write Concern、 つまりドライバがレプリカセットへの書き込みをどれくらいブロックするかを制御します。

    正の整数は、レプリカセット内のいくつの ノードが書き込み指示を受け取ったらドライバが処理を続行するのかを指定します。 値を 3 にすると、 書き込みがレプリカセット内であと 2 台に適用されてからプライマリにも適用します。

    文字列を指定すると、どのタグセットを書き込み時に考慮するのかを指定したことになります。 "majority" は特別な値で、 参加しているノードの過半数に書き込み操作が適用された時点でプライマリにも適用します。

  • "wTimeoutMS"

    このオプションは、 書き込み確認 を待つ制限時間をミリ秒単位で指定します。 これが書き込み操作に適用されるのは、 "w" が 1 より大きい場合のみです。 というのも、タイムアウトはレプリケーションに関する機能だからです。 この時間内に書き込み確認ができなかった場合は MongoCursorException をスローします。 0 を指定すると、永遠にブロックし続けます。 デフォルト値は 10000 (10 秒) です。

以下のオプションは廃止予定です。使ってはいけません。

  • "slaveOkay"

    非推奨です。優先読み込み のオプションを使いましょう。

  • "timeout"

    "connectTimeoutMS" へのエイリアス。非推奨です。

  • "wTimeout"

    "wTimeoutMS" へのエイリアス。非推奨です。

driver_options

MongoDB ドライバーへのオプションの配列。SSL 用の接続コンテキストのオプションや、 ログ出力用のコールバックも含みます。

  • "context"

    新しい接続をアタッチするストリームコンテキスト。このオプションで、SSL 証明書の設定などができます。 詳細は SSL コンテキストオプション を参照ください。 詳しい使いかたは SSL 接続のチュートリアルを参照ください。

返り値

新しいデータベース接続オブジェクトを返します。

エラー / 例外

指定したすべてのホスト名へのデータベースへの接続に失敗した場合に MongoConnectionException をスローします。 指定したユーザー名やパスワードが間違っている場合にも MongoConnnectionException をスローします。 一般的な例外とその原因については MongoConnectionException のドキュメントを参照ください。

例

例1 MongoClient::__construct() でのレプリカセットの例

この例は、レプリカセットに接続する方法を示します。 このでは、次の三つのサーバー sf1.example.com、sf2.example.com および ny1.example.com があるものと仮定します。 プライマリは、これらのうちのいずれかひとつとなります。

<?php

// カンマ区切りのサーバー名をコンストラクタに渡します
// レプリカセットの全メンバーを渡す必要はないことに注意しましょう。
// ドライバが完全なリストを取得します
$m1 = new MongoClient("mongodb://sf2.example.com,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 MongoClient("mongodb:///tmp/mongodb-20000.sock");

?>

これは、その他の接続とも組み合わせることができます。

<?php

// まずドメインソケットに接続し、失敗したときにはローカルホストへの接続を使います
$m = new MongoClient("mongodb:///tmp/mongodb-27017.sock,localhost:27017");

?>

例3 MongoClient::__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 MongoClient("mongodb://testUser:testPass@localhost");

?>

例4 MongoClient::__construct() での優先読み込みの例

<?php

// "east" データセンターにある最も近いサーバーを優先します
$uri  = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
?>

詳細な情報は、このマニュアルの 優先読み込み のページを参照ください。

例5 MongoClient::__construct() でのオプションの例

オプションは、接続文字列のクエリ文字列で渡すだけでなく、 コンストラクタの二番目の引数で渡すこともできます。

この例では、journal オプションを true、そして readPreference を secondary にする設定を、すべての書き込み操作のデフォルトとします。

<?php
$m = new MongoClient("mongodb://localhost/?journal=true&readPreference=secondary");
?>

同じ設定を、このようにすることもできます。

<?php
$options = array(
    'journal' => true,
    'readPreference' => 'secondary',
);
$m = new MongoClient("mongodb://localhost/", $options);
?>

例6 MongoClient::__construct() での優先読み込みの例

<?php

// "east" データセンターにある最も近いサーバーを優先します
$uri  = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
?>

詳細な情報は、このマニュアルの 優先読み込み のページを参照ください。

変更履歴

バージョン 説明
1.5.0

"authMechanism"、"gssapiServiceName" および "secondaryAcceptableLatencyMS" が追加されました。

1.4.0

"ssl" オプションが追加されました。これは SSL 接続 をサポートするものです。

"wTimeoutMS" オプションが追加されました。これは "wTimeout" の代替です。

"slaveOkay" や "timeout" を使うと E_DEPRECATED が発生します。

1.5.0

"authSource" が追加されました。

1.3.4

"connectTimeoutMS" および "socketTimeoutMS" オプションが追加されました。

1.3.0

"readPreference"、 "readPreferenceTags"、"w" および "wTimeout" オプションが追加されました。

1.2.0

"username" および "password" オプションが追加されました。

"persist" オプションが削除されました。すべての接続は持続的な接続となります。 今でも使うことはできますが、何の影響も及ぼしません。

"persist"

持続的な接続を行うかどうか。これを設定すると、接続が持続的なものとなります。 文字列の値を接続 ID として使うので、 array("persist" => "foobar") で初期化した Mongo のインスタンスがふたつあれば、 それは同じデータベース接続をあらわします。一方、 array("persist" => "barbaz") で初期化したインスタンスは別のデータベース接続を使います。

"replicaSet" オプションは、boolean ではなく文字列を受け取るようになりました。

1.0.9 "replicaSet" オプションが追加されました。
1.0.2

コンストラクタがオプションの配列を受け取るようになりました。 以前のバージョンでは、コンストラクタは以下のパラメータを受け取っていました。

server

サーバー名。

connect

オプションの boolean パラメータで、 コンストラクタがデータベースに接続するかどうかを示します。 デフォルトは TRUE です。

persistent

持続的な接続を行うかどうか。

paired

ペア接続を行うかどうか。

MongoClient
PHP Manual