|
|
MongoClient::__construct
Creates a new database connection object
Note:
This extension that defines this method
is deprecated. Instead, the MongoDB extension should be used.
Alternatives to this method include:
- MongoDB\Driver\Manager::__construct
Description
public MongoClient::__construct
([ string $server = "mongodb://localhost:27017"
[, array $options = array("connect" => TRUE)
[, array $driver_options
]]] )
server should have the form:
mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
The connection string always starts with mongodb://, to
indicate it is a connection string in this form.
If username and password
are specified, the constructor will attempt to authenticate the connection
with the database before returning. Username and password are optional
and must be followed by an @, if specified.
At least one host must be given (port optional, always defaulting to 27017)
and as many hosts as desired may be connected to. Host names are
comma-separated and the constructor will return successfully if it connected
to at least one host. If it could not connect to any of the hosts, it will
throw a MongoConnectionException. Please see the
Replica Sets section for
information on how to connect to Replica Sets.
If you specified a username and password, you may specify a database to
authenticate with. If db is not specified, "admin" will
be used.
An optional query string may be used to specify extra options. The same
options are supported through the options array as
well, and are therefore redescribed there. See the examples below on
how to set those options.
One part of the options governs how the driver reads from secondary nodes
in a replica set environment. Extra information on how these read
preferences work is available as well through the read preferences documentation page.
Parameters
-
server
-
The server name.
-
options
-
An array of options for the connection. Currently available options
include:
-
"authMechanism"
Available mechanisms are:
-
"authSource"
Should be set to the database name where the user is defined it.
-
"connect"
If the constructor should connect before returning. Default is
TRUE. When set to FALSE the driver will
automatically connect to the server whenever
it is necessary to do a query. Alternatively, you can run
MongoClient::connect manually.
Warning
This option is not supported through the connection string.
-
"connectTimeoutMS"
How long a connection can take to be opened before timing out in
milliseconds. Defaults to 60000 (60 seconds).
If -1 is specified, no connection timeout will be
applied and PHP will use
default_socket_timeout.
-
"db"
The database to authenticate against can be specified here, instead of
including it in the host list. This overrides a database given in the
host list.
-
"fsync"
When "fsync" is set, all write operations will
block until the database has flushed the changes to disk. This makes
the write operations slower, but it guarantees that writes have
succeeded and that the operations can be recovered in case of total
system failure.
If the MongoDB server has journaling enabled, this option is identical
to "journal". If journaling is not enabled, this
option ensures that write operations will be synced to database files
on disk.
Note:
If journaling is enabled, users are strongly encouraged to use the
"journal" option instead of
"fsync". Do not use "fsync" and
"journal" simultaneously, as that will result in
an error.
-
"journal"
When "journal" is set, all write operations will
block until the database has flushed the changes to the journal on
disk. This makes the write operations slower, but it guarantees that
writes have succeeded and that the operations can be recovered in case
of total system failure.
Note:
If this option is used and journaling is disabled, MongoDB 2.6+ will
raise an error and the write will fail; older server versions will
simply ignore the option.
-
"gssapiServiceName"
Sets the » Kerberos service principal. Only applicable when authMechanism=GSSAPI. Defaults to "mongodb".
-
"password"
The password can be specified here, instead of including it in the
host list. This is especially useful if a password has a "@" in it.
This overrides a password set in the host list.
-
"readPreference"
Specifies the read preference type. Read preferences provide you
with control from which secondaries data can be read from.
Allowed values are: MongoClient::RP_PRIMARY,
MongoClient::RP_PRIMARY_PREFERRED,
MongoClient::RP_SECONDARY,
MongoClient::RP_SECONDARY_PREFERRED and
MongoClient::RP_NEAREST.
See the documentation on read
preferences for more information.
-
"readPreferenceTags"
Specifies the read preference tags as an array of strings. Tags can be
used in combination with the readPreference option
to further control which secondaries data might be read from.
See the documentation on read
preferences for more information.
-
"replicaSet"
The name of the replica set to connect to. If this is given, the
primary will be automatically be determined. This means that the
driver may end up connecting to a server that was not even listed.
See the replica set example below for details.
-
"secondaryAcceptableLatencyMS"
When reading from a secondary (using ReadPreferences), do not read from secondaries known to be more then
secondaryAcceptableLatencyMS away from us. Defaults to 15
-
"socketTimeoutMS"
How long a socket operation (read or write) can take before timing out
in milliseconds. Defaults to 30000 (30 seconds).
If -1 is specified, socket operations may block
indefinitely. This option may also be set on a per-operation basis
using MongoCursor::timeout for queries or the
"socketTimeoutMS" option for write methods.
Note:
This is a client-side timeout. If a write operation times out, there
is no way to know if the server actually handled the write or not, as
a MongoCursorTimeoutException will be thrown
in lieu of returning a write result.
-
"ssl"
A boolean to specify whether you want to enable SSL for the
connections to MongoDB. Extra options such as certificates
can be set with SSL context options.
-
"username"
The username can be specified here, instead of including it in the
host list. This is especially useful if a username has a ":" in it.
This overrides a username set in the host list.
-
"w"
The w option specifies the
Write Concern for the driver,
which determines how long the driver blocks when writing. The
default value is 1.
This option is applicable when connecting to both single servers and
replica sets. A positive value controls how many
nodes must acknowledge the write instruction before the driver
continues. A value of 1 would require the single
server or primary (in a replica set) to acknowledge the write
operation. A value of 3 would cause the driver to
block until the write has been applied to the primary as well as two
secondary servers (in a replica set).
A string value is used to control which tag sets are taken into
account for write concerns. "majority" is special
and ensures that the write operation has been applied to the majority
(more than 50%) of the participating nodes.
-
"wTimeoutMS"
This option specifies the time limit, in milliseconds, for
write concern
acknowledgement. It is only applicable for write operations where
"w" is greater than 1, as the
timeout pertains to replication. If the write concern is not satisfied
within the time limit, a MongoCursorException
will be thrown. A value of 0 may be specified to
block indefinitely. The default value is 10000
(ten seconds).
The following options are deprecated and should no longer be used:
-
"slaveOkay"
Deprecated. Please use the read
preference options.
-
"timeout"
Deprecated alias for "connectTimeoutMS".
-
"wTimeout"
Deprecated alias for "wTimeoutMS".
-
driver_options
-
An array of options for the MongoDB driver. Options include setting
connection context options for SSL
or logging callbacks.
Return Values
Returns a new database connection object.
Errors/Exceptions
Throws MongoConnectionException if it tries and fails
to connect to the database for all hostnames given. It will also throw a
MongoConnnectionException if an invalid username or
password is given. See MongoConnectionException
documentation for common exceptions and their causes.
Examples
Example #1 MongoClient::__construct replica set example
This example shows how to connect the driver to a replica set. It assumes
that there is a set of three servers: sf1.example.com, sf2.example.com, and
ny1.example.com. The primary could be any one of these servers.
<?php
// pass a comma-separated list of server names to the constructor
// Note that we don't need to pass in all the members of the replicaset, the driver
// will derive the full list.
$m1 = new MongoClient("mongodb://sf2.example.com,ny1.example.com", array("replicaSet" => "myReplSet"));
?>
If the current primary fails, the driver will figure out which secondary
server became the new primary and automatically start using that connection.
Automatic failover will not work correctly if replicaSet
is not specified.
At least one seed in the seed list must be up for the driver to connect to
the replica set.
If you include seeds from two separate replica sets, behavior is undefined.
See the
» core documentation on
replica sets for more information.
Example #2 Connecting to a domain socket
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.
In version 1.5.0, the MongoDB server automatically opens a socket at
/tmp/mongodb-<port>.sock. You can connect to this by specifying the
path in your connection string:
<?php
// MongoDB server running locally on port 20000
$m = new MongoClient("mongodb:///tmp/mongodb-20000.sock");
?>
You can combine this with any other connections you'd like:
<?php
// try to connect to the domain socket, fall back to localhost connection
$m = new MongoClient("mongodb:///tmp/mongodb-27017.sock,localhost:27017");
?>
Example #3 MongoClient::__construct authentication example
A user must exist in the admin database before attempting to use
authentication. You can create one with the Mongo shell by running:
> use admin
switched to db admin
> db.addUser("testUser", "testPass");
{
"_id" : ObjectId("4b21272fd9ab21611d19095c"),
"user" : "testUser",
"pwd" : "03b9b27e0abf1865e2f6fcbd9845dd59"
}
>
After creating a user with, in this case, username "testUser" and password
"testPass", you can create an authenticated connection:
<?php
$m = new MongoClient("mongodb://testUser:testPass@localhost");
?>
Example #4 MongoClient::__construct read preference example
<?php
// Prefer the nearest server in the "east" data center
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
?>
See the read preferences
section of this manual for further information.
Example #5 MongoClient::__construct options example
Options can be passed both through the query string in the connection
string, or as an array passed as second argument to the constructor.
Here we set the journal option to true and readPreference to secondary
preferred as default for all write operations:
<?php
$m = new MongoClient("mongodb://localhost/?journal=true&readPreference=secondary");
?>
And now we do the same, but as an options array:
<?php
$options = array(
'journal' => true,
'readPreference' => 'secondary',
);
$m = new MongoClient("mongodb://localhost/", $options);
?>
Example #6 MongoClient::__construct read preference example
<?php
// Prefer the nearest server in the "east" data center
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
?>
See the read preferences
section of this manual for further information.
|