MongoClient
PHP Manual

Mongo::__construct

(PECL mongo >=0.9.0)

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

説明

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

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

  • "connect"

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

    警告

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

  • "connectTimeoutMS"

    接続を開こうとしてタイムアウトになるまでの時間の長さ（ミリ秒単位）。

  • "db"

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

  • "fsync"

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

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

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

  • "journal"

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

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

  • "password"

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

  • "readPreference"

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

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

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

  • "readPreferenceTags"

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

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

  • "replicaSet"

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

  • "socketTimeoutMS"

    ソケットの送受信がタイムアウトになるまでの時間の長さ。

    注意: これはクライアント側のタイムアウトです。 insert が "socketTimeoutMS" に達してしまうと、サーバーが実際に書き込みを受信したかどうかを知るすべがなくなります。

  • "ssl"

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

  • "username"

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

  • "w"

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

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

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

  • "wTimeoutMS"

    このオプションは "w" と組み合わせて使います。 書き込み操作がうまくいくまでサーバーが何ミリ秒待つのかを制御します。 これよりも長い時間がかかると、サーバーからドライバに対して「長すぎる」 という通知を出し、ドライバが MongoCursorException をスローします。

The following options are deprecated and should no longer be used:

  • "timeout"

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

  • "wTimeout"

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

driver_options

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

  • "context"

    コンテキストオプションを渡す方法。このオプションで、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'));
?>

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

例7 MongoClient::__construct() で SSL 証明書を使って接続する例

<?php
$ctx = stream_context_create( array(
    'ssl' => array(
        'local_cert' => '/vagrant/certs/client.pem',
        'cafile' => '/vagrant/certs/ca.pem',
    )
) );

$m = new MongoClient(
    "mongodb://mongod/?ssl=true", 
    array(), 
    array('context' => $ctx)
);
?>

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

変更履歴

バージョン 説明
1.4.0

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

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