MongoClient::__construct

(PECL mongo >=1.3.0)

MongoClient::__construct — 创建一个新的数据库连接对象

说明

public MongoClient::__construct ([ string $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，驱动会在有查询必要时 自动 连接到服务器。 另外，你也可以用 MongoClient::connect() 手动运行。

    Warning

    这个选项不支持通过连接字符串来设置。

  • "db"

    要验证的数据库能在这里指定，而不是在主机列表中包含它。 能够重载主机列表中指定的数据库。

  • "password"

    能在这里指定密码，而不是在主机列表中指定。 当密码里有一个 "@" 的时候尤其有用。 此参数会覆盖主机列表中设置的密码。

  • "readPreference"

    指定读取首选项类型。 读取首选项提供了对备份数据读取的控制。

    允许的值有： MongoClient::RP_PRIMARY、 MongoClient::RP_PRIMARY_PREFERRED、 MongoClient::RP_SECONDARY、 MongoClient::RP_SECONDARY_PREFERRED 和 MongoClient::RP_NEAREST。

    更多信息参见读取首选项文档。

  • "readPreferenceTags"

    以字符串的数组指定读取选项标签。 标签能够控制 readPreference 选项来进一步控制从备份节点数据的读取。

    更多信息参见读取首选项文档。

  • "replicaSet"

    要连接的集群名称。 如果指定了，活跃节点能够自动检测到。 这意味着驱动能够最终甚至能够连接到未列出的服务器。 更多细节参见集群的例子。

  • "connectTimeoutMS"

    打开连接超时的时间。

  • "timeout"

    "connectTimeoutMS" 废弃的别名。

  • "socketTimeoutMS"

    在套接字上发送或接收超时的时间。

    Note: 这是客户端的超时时间。如果一个 insert 达到了 socketTimeoutMS， 将无法得知服务器是否确实已写入。

  • "username"

    能在这里指定用户名，而不是在主机列表中指定。 当用户名包括一个「:」时尤其有用。 它会覆盖主机列表中的设置。

  • "w"

    选项 w 指定了驱动的 Write Concern，决定了驱动在写入时阻塞的时间。 默认值是 1。

    此选项适用于单台服务器或者是集群。 一个正数值控制了在驱动继续之前，有多少个节点必须应答写入的指令。 值 1 将让单台服务器或者活跃节点（在集群里）应答写入操作。 值 3 将阻塞驱动直至写入到活跃节点和其他两个备份节点服务器（在集群里）。

    一个字符串的值用于控制考虑 write concerns 的标签集。 "majority" 是特殊用于确保写入操作被应用于大多数（大于 50%）参与的节点。

  • "wTimeout"

    此选项用于和 "w" 参数组合使用。 它控制了服务器等待多少毫秒来满足 write concern。 如果超时了，驱动会抛出 MongoCursorException 异常。

返回值

返回一个新的数据库连接对象。

错误／异常

如果给出的主机都无法连接，将会抛出 MongoConnectionException 异常。 如果提供了无效的用户名和密码将会抛出一个 MongoConnnectionException。 参见 MongoConnectionException 相关文档获取异常发生的原因。

更新日志

版本 说明
1.3.4

添加了 "connectTimeoutMS" 和 "socketTimeoutMS" 选项。

1.3.0

添加了 "readPreference"、 "readPreferenceTags"、"w" 和 "wTimeout" 选项。

1.2.0

添加了 "username" 和 "password" 选项。

移除了 "persist" 选项，所有的连接都是持久的。它仍旧能够使用，但是不起作用。

"persist"

是否应该是持久连接。如果设置了，连接会是持久连接。 字符形式的值将会用于连接的 ID。所以两个以 array("persist" => "foobar") 初始化的 MongoClient 实例会共享一个数据库连接，以 array("persist" => "barbaz")初始化的实例则使用不同的数据库连接。

"replicaSet" 选项现在支持一个字符串，而不是布尔值。

1.0.9 添加了 "replicaSet" 选项。
1.0.2

修改构造器支持选修数组。在 1.0.2 之前，构造器接受以下参数：

server

服务器名。

connect

可选的 boolean 参数指定了构造器是否应该在返回前连接到数据库。默认为 TRUE。

persistent

连接是否应该是持久的。

paired

连接是否应该为 paired 模式。

范例

Example #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，自动容错移转将无法正常工作。

在驱动连接的集群种子列表里，起码要有一个种子是在线的。

如果你包含的种子位于两个独立的集群，后面的行为将不可预测。

更多关于集群的信息参见» 核心文档。

Example #2 连接到一个域套接字（domain socket）

在 1.0.9+ 版本中，你可以使用一个 UNIX 域套接字来连接到一个本地的 MongoDB 实例。 这可能会比使用网络连接稍微快一点。

在版本 1.5.0，MongoDB 服务器会自动打开 /tmp/mongodb-<port>.sock 上的套接字。 你可以在连接字符串中指定位置：

<?php

// MongoDB 服务器运行在本地 20000 端口上
$m = new MongoClient("mongodb:///tmp/mongodb-20000.sock");

?>

你也可以和其他想要的连接组合：

<?php

// 尝试连接到套接字，失败时使用 localhost 连接
$m = new MongoClient("mongodb:///tmp/mongodb-27017.sock,localhost:27017");

?>

Example #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");

?>

Example #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'));

更多信息参见本手册中读取选项一节。

User Contributed Notes

mike at eastghost dot com 09-Apr-2015 06:29
FOLLOW UP to comment on speed

Now using --
mongo 3.0.1 pre-compiled binaries
using mongo/php-1.6.6. driver from PECL
on php 5.6.0
on apache 2.4
on debian wheezy 7.8

Dropped in mongo 301 binaries
everything else unchanged
restarted apache

instantly started getting "No candidate servers found"
upgraded to mongo/php-1.6.6 driver on pecl
same result

of these four parms to \MongoClient()

A) 'mongodb:///tmp/mongodb-27017.sock'
B) #'mongodb://127.0.0.1:27017'
C) #'mongodb://localhost:27017'
D) #'mongodb://pri.eastghost.com:27017'

A) used to be 100x to 200x faster than B), C) and maybe 400x faster than D), as explained in comment below, but initially (after mongo 3.0.1 drop-in) A) stopped dead.  Tried B, instantly began working.  Went back to A), kept working.  Almost seems as if driver 1.6.6 can not populate candidate servers list when called via unix socket (/tmp/mongodb-27017.sock), but once the list is populated, calling via unix socket magically works fine.

While screwing around with this, all else unchanged, we're now noticing B) and C) seem to be as fast as A), and D) is only slightly slower (due to connect over WAN, instead of local LAN).  This behavior is as it theoretically should be: Maybe the once huge difference in the mongo php driver between unix sockets and localhost has been fixed?  Still testing -- will report back if any slowdown noticed.

see https://groups.google.com/forum/#!topic/mongodb-user/RTBDDMwywzA
mike at eastghost dot com 09-Oct-2013 04:56
HOLY MOLY, 100 to 200 times instant speed boost in one small change.

"In version 1.0.9+, you can use a UNIX domain socket to connect to an instance of MongoDB running locally. This should be slightly faster than using a network connection."

is an EXTREME understatement.  Just trying out stuff, playing around, etc., we changed from

MongoClient( 'mongodb://pri.eastghost.com:27017' etc)

to

MongoClient ( 'mongodb:///tmp/mongodb-27017.sock' etc)

and saw instant 100x-200x speed boost, all else untouched.
page times went from 700 - 1400 (as in 1.4 seconds)
to 7 as in milliseconds.

mongo driver 1.4.1
(for apache 2.6)
mike at eastghost dot com 06-Mar-2013 04:44
read somewhere that

$uri  = 'mongodb://rs1.example.com/?w=0';

(the w=0 parm) makes the MongoDB driver accept 'blind writes' without waiting for any confirmation of write success from server.