Mongo::__construct

(PECL mongo >=0.9.0)

Mongo::__constructCreates a new database connection object

Description

Mongo::__construct ([ string $server = "mongodb://localhost:27017" [, array $options = array("connect" => TRUE) ]] )

If no parameters are passed, this connects to "localhost:27017" (or whatever was specified in php.ini for mongo.default_host and mongo.default_port).

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.

Finally, if you specified a username and password, you may specify a database to authenticate with. If db is not specified, "admin" will be used.

If you elect not to connect immediately (you pass the option array("connect" => false)), you will need to call Mongo::connect() before doing any database operations.

<?php

$mongo 
= new Mongo("mongodb://localhost", array("connect" => false));

// throws a MongoException, as $mongo has not been fully initialized yet
$mongo->selectDB("foo")->command(array("distinct" => "bar""key" => "age"));

// okay
$mongo->connect();
$mongo->selectDB("foo")->command(array("distinct" => "bar""key" => "age"));

?>

Parameters

server

The server name.

options

An array of options for the connection. Currently available options include:

  • "connect"

    If the constructor should connect before returning. Default is TRUE.

  • "persist"

    If the connection should be persistent. If set, the connection will be persistent. The string representation of the value is used as an id for the connection, so two instances of Mongo that are initialized with array("persist" => "foobar") will share the same database connection, whereas an instance initialized with array("persist" => "barbaz") will use a different database connection.

  • "timeout"

    For how long the driver should try to connect to the database (in milliseconds).

  • "replicaSet"

    If this hosts listed are seeds of a replica set. If they are, the master will be determined by using the ismaster database command on the seeds, so the driver may end up connecting to a server that was not even listed. See the replica set example below for details.

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.

Changelog

Version Description
1.0.2 Changed constructor to take an array of options. Pre-1.0.2, the constructor took the following parameters:
server

The server name.

connect

Optional boolean parameter specifying if the constructor should connect to the database before returning. Defaults to TRUE.

persistent

If the connection should be persistent.

paired

If the connection should be paired.

1.0.9 Added the replicaSet option.

Examples

Example #1 Mongo::__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 master could be any one of these servers.

<?php

// pass a comma-separated list of server names to the constructor
$m1 = new Mongo("mongodb://sf2.example.com,ny1.example.com", array("replicaSet" => true));

// you only need to pass a single seed, the driver will derive the full list and
// find the master from this seed
$m2 = new Mongo("mongodb://ny1.example.com", array("replicaSet" => true));

?>

If the current master fails, the driver will figure out which secondary server became the new master 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 Mongo("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 MongoDB("mongodb:///tmp/mongodb-27017.sock,localhost:27017");

?>

Example #3 Mongo::__construct() persistent connection example

A persistent connection will last for more than one request (usually... milage may vary depending on server). It can save significant time to reuse connections, as creating a connection is a time-intensive process.

A persistent connection is identified by the server string and and id string.

<?php

// creates a persistent connection
$m1 = new Mongo("mongodb://localhost", array("persist" => ""));

// uses the same connection as $m1
$m2 = new Mongo("mongodb://localhost", array("persist" => ""));

// creates a new connection
$m3 = new Mongo("mongodb://127.0.0.1", array("persist" => ""));

// creates a new connection
$m4 = new Mongo("mongodb://127.0.0.1:27017", array("persist" => ""));

// creates a new connection
$m5 = new Mongo("mongodb://localhost", array("persist" => "foo"));

// uses the $m5 connection
$m6 = new Mongo("mongodb://localhost", array("persist" => "foo"));

?>

Example #4 Mongo::__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 Mongo("mongodb://testUser:testPass@localhost");

?>

Copyright © 2010-2024 Platon Technologies, s.r.o.           Home | Man pages | tLDP | Documents | Utilities | About
Design by styleshout