From d9a4e178e99ae902ed333478d886b40b36b48e5b Mon Sep 17 00:00:00 2001 From: Kristina Chodorow Date: Fri, 11 Dec 2009 17:15:46 +0000 Subject: [PATCH] updated connection doc for 1.0.2, added MongoId::getTimestamp git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@291996 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mongo/mongo.xml | 70 +++++- reference/mongo/mongo/construct.xml | 227 ++++++++++++++----- reference/mongo/mongo/pairconnect.xml | 9 +- reference/mongo/mongo/pairpersistconnect.xml | 9 +- reference/mongo/mongo/persistconnect.xml | 8 +- reference/mongo/mongoid/gettimestamp.xml | 55 +++++ 6 files changed, 310 insertions(+), 68 deletions(-) create mode 100644 reference/mongo/mongoid/gettimestamp.xml diff --git a/reference/mongo/mongo.xml b/reference/mongo/mongo.xml index 87bf7b8e46..1dc44d5408 100644 --- a/reference/mongo/mongo.xml +++ b/reference/mongo/mongo.xml @@ -14,8 +14,8 @@ The connection point between MongoDB and PHP. - This class is used to initiate a connection and for database server commands. - A typical use is: + This class is used to initiate a connection and for database server commands. + A typical use is: selectDatabase(); // get a database object ]]> + + + This class has two static fields: Mongo::$connections and + Mongo::$pconnections which track the number of open + connections and persistent connections, respectively. + Mongo::$connections is inclusive, it basically counts all + open sockets, including persistent connections. + + + An example of how different types of connections affect these variables: + + "foo")); + +/* + * Mongo::$connections is 2 + * Mongo::$pconnections is 1 + */ + +// reuse persistent connection +$m3 = new Mongo("localhost", array("persist" => "foo")); + +/* + * Mongo::$connections is 2 + * Mongo::$pconnections is 1 + */ + +?> +]]> + + + + See Mongo::__construct for more information about + creating connections. + @@ -64,6 +114,22 @@ $db = $m->selectDatabase(); // get a database object 27017 + Static Fields + + public + static + int + connections + 0 + + + public + static + int + pconnections + 0 + + Fields public diff --git a/reference/mongo/mongo/construct.xml b/reference/mongo/mongo/construct.xml index ac09b631f3..ff51ac273b 100644 --- a/reference/mongo/mongo/construct.xml +++ b/reference/mongo/mongo/construct.xml @@ -11,19 +11,33 @@ &reftitle.description; Mongo::__construct - stringserver&null; - booleanconnect&true; - booleanpersistent&false; - booleanpaired&false; + stringserver"mongodb://localhost:27017" + arrayoptionsarray("connect" => &true;) - If no parameters are passed, this connects to "localhost:27017" and returns. + 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). - If you elect not to connect immediately ($connect is - &false;), you will need to call connect, - persistConnect, pairConnect, or - pairPersistConnect before doing any database operations. + As of version 1.0.2, server can have a special form: + mongodb://[username:password@]host1[:port1][,host2[:port2:],...]. + Breaking this down, it starts with mongodb://, to indicate + it is in this form. If username and password + are specified, the constructor will attempt to authenticate the connection + with the admin 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. + + + 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. @@ -31,7 +45,7 @@ false); // throws a MongoException, as $mongo has not been fully initialized yet $mongo->selectDB("foo")->command(array("distinct" => "bar", "key" => "age")); @@ -62,32 +76,38 @@ $mongo->selectDB("foo")->command(array("distinct" => "bar", "key" => "age")); - connect + options - If the constructor should connect to the database now. If this is - &false;, the constructor will return without connecting to the database. - - - - - - persistent - - - - If the connection should be persistent. - - - - - - paired - - - - If the connection should be paired. + 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. + + + @@ -105,7 +125,78 @@ $mongo->selectDB("foo")->command(array("distinct" => "bar", "key" => "age")); &reftitle.errors; - Throws MongoConnectionException if it tries and fails to connect to the database. + 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. + + + + + &reftitle.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. + + + + + + + + + @@ -122,16 +213,14 @@ $mongo->selectDB("foo")->command(array("distinct" => "bar", "key" => "age")); pairConnect(); +$m1 = new Mongo("mongodb://www.example1.com,www.example2.com"); // if the database servers are not running on the default port (27017), // you'll need to specify the port -$m2 = new Mongo("www.example1.com:12345,www.example.com:54321", false); -$m2->pairConnect(); +$m2 = new Mongo("mongodb://www.example1.com:12345,www.example.com:54321"); -// you can also do a paired connection in one line of code -$m3 = new Mongo("www.example1.com,www.example.com", true, false, true); +// you can connect to more that two, as well +$m3 = new Mongo("mongodb://localhost:27017,localhost:27018,localhost:27019"); ?> ]]> @@ -145,41 +234,63 @@ $m3 = new Mongo("www.example1.com,www.example.com", true, false, true); reuse connections, as creating a connection is a time-intensive process. - A persistent connection is identified by the server string and optional - "username" and "password" strings. These strings are arbitrary and should - not be sensitive (i.e., a real password). They are merely indended as - unique identifiers for a connection. + A persistent connection is identified by the server string and and id + string. "")); // uses the same connection as $m1 -$m2 = new Mongo("localhost", false); -$m2->persistConnect(); +$m2 = new Mongo("mongodb://localhost", array("persist" => "")); // creates a new connection -$m3 = new Mongo("127.0.0.1", false); -$m3->persistConnect(); +$m3 = new Mongo("mongodb://127.0.0.1", array("persist" => "")); // creates a new connection -$m4 = new Mongo("127.0.0.1:27017", false); -$m4->persistConnect(); +$m4 = new Mongo("mongodb://127.0.0.1:27017", array("persist" => "")); // creates a new connection -$m5 = new Mongo("localhost", false); -$m5->persistConnect("foo"); +$m5 = new Mongo("mongodb://localhost", array("persist" => "foo")); // uses the $m5 connection -$m6 = new Mongo("localhost", false); -$m6->persistConnect("foo"); +$m6 = new Mongo("mongodb://localhost", array("persist" => "foo")); -// creates a new connection -$m7 = new Mongo("localhost", false); -$m7->persistConnect("foo", "bar"); +?> +]]> + + + + <function>Mongo::__construct</function> 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: + + + ]]> diff --git a/reference/mongo/mongo/pairconnect.xml b/reference/mongo/mongo/pairconnect.xml index 161b15bd64..883d200f9b 100644 --- a/reference/mongo/mongo/pairconnect.xml +++ b/reference/mongo/mongo/pairconnect.xml @@ -4,7 +4,7 @@ Mongo::pairConnect - Connects to paired database server + Connects to paired database server [deprecated] @@ -14,8 +14,8 @@ - To successfully create a paired connection, $this->server must be a string - of the form "server1,server2". + Pass a string of the form "mongodb://server1,server2" to the constructor + instead of using this method. @@ -34,7 +34,8 @@ &reftitle.errors; - Throws MongoConnectionException if it fails to connect to the databases. + Throws MongoConnectionException if it fails to connect + to the databases. diff --git a/reference/mongo/mongo/pairpersistconnect.xml b/reference/mongo/mongo/pairpersistconnect.xml index 9557d60b34..43759dbf8a 100644 --- a/reference/mongo/mongo/pairpersistconnect.xml +++ b/reference/mongo/mongo/pairpersistconnect.xml @@ -4,7 +4,7 @@ Mongo::pairPersistConnect - Creates a persistent connection with paired database servers + Creates a persistent connection with paired database servers [deprecated] @@ -14,6 +14,10 @@ stringusername"" stringpassword"" + + Pass "mongodb://server1,server2" and array("persist" => $id) + to the constructor instead of using this method. + @@ -54,7 +58,8 @@ &reftitle.errors; - Throws MongoConnectionException if it fails to connect to the databases. + Throws MongoConnectionException if it fails to + connect to the databases. diff --git a/reference/mongo/mongo/persistconnect.xml b/reference/mongo/mongo/persistconnect.xml index ef4e2dd6de..e4b76ee40a 100644 --- a/reference/mongo/mongo/persistconnect.xml +++ b/reference/mongo/mongo/persistconnect.xml @@ -4,7 +4,7 @@ Mongo::persistConnect - Creates a persistent connection with a database server + Creates a persistent connection with a database server [deprecated] @@ -14,6 +14,9 @@ stringusername"" stringpassword"" + + Pass array("persist" => $id) to the constructor instead of using this method. + @@ -54,7 +57,8 @@ &reftitle.errors; - Throws MongoConnectionException if it fails to connect to the databases. + Throws MongoConnectionException if it fails to connect + to the databases. diff --git a/reference/mongo/mongoid/gettimestamp.xml b/reference/mongo/mongoid/gettimestamp.xml new file mode 100644 index 0000000000..c0ebb772b9 --- /dev/null +++ b/reference/mongo/mongoid/gettimestamp.xml @@ -0,0 +1,55 @@ + + + + + + MongoId::getTimestamp + Gets the number of seconds since the epoch that this id was created + + + + &reftitle.description; + + public intMongoId::getTimestamp + + + + This returns the same thing as running time() when the id is created. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the number of seconds since the epoch that this id was created. There are only + four bytes of timestamp stored, so MongoDate is a better choice + for storing exact or wide-ranging times. + + + + +