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

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