(PECL mongo >=1.3.0)
MongoClient::__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
,驱动会在有查询必要时
自动 连接到服务器。
另外,你也可以用
MongoClient::connect() 手动运行。
这个选项不支持通过连接字符串来设置。
"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" 选项,所有的连接都是持久的。它仍旧能够使用,但是不起作用。
"replicaSet" 选项现在支持一个字符串,而不是布尔值。 |
1.0.9 | 添加了 "replicaSet" 选项。 |
1.0.2 |
修改构造器支持选修数组。在 1.0.2 之前,构造器接受以下参数:
|
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'));
更多信息参见本手册中读取选项一节。