From 13d9a87041ee11fbffc2846d5c643344c9bc5d58 Mon Sep 17 00:00:00 2001 From: Kristina Chodorow Date: Tue, 16 Mar 2010 15:15:54 +0000 Subject: [PATCH] added safe options git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@296280 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mongo/book.xml | 6 ++ reference/mongo/connecting.xml | 57 ++++++++++++++++ .../mongo/mongocollection/batchinsert.xml | 59 ++++++++++++++++- reference/mongo/mongocollection/insert.xml | 45 +++++++++++-- reference/mongo/mongocollection/remove.xml | 66 +++++++++++++++++-- reference/mongo/mongocollection/save.xml | 55 +++++++++++++++- reference/mongo/mongocollection/update.xml | 27 +++++++- reference/mongo/mongocursor/getquery.xml | 10 +-- reference/mongo/mongogridfs/storebytes.xml | 29 ++++++++ reference/mongo/mongogridfs/storefile.xml | 29 ++++++++ reference/mongo/versions.xml | 2 +- 11 files changed, 364 insertions(+), 21 deletions(-) diff --git a/reference/mongo/book.xml b/reference/mongo/book.xml index 7ecbefc965..c9cddefaa9 100644 --- a/reference/mongo/book.xml +++ b/reference/mongo/book.xml @@ -5,6 +5,12 @@ Mongo Mongo + + + This extension allows you to connect to MongoDB through PHP. + + + &reference.mongo.manual; &reference.mongo.core; &reference.mongo.types; diff --git a/reference/mongo/connecting.xml b/reference/mongo/connecting.xml index 2f7247846f..1f4fe1c143 100644 --- a/reference/mongo/connecting.xml +++ b/reference/mongo/connecting.xml @@ -108,4 +108,61 @@ $m = new Mongo("mongodb://localhost:27017,localhost:27018"); +
+ Persistent Connections + + + Creating new connection to the database is very slow. To minimize the number + of connections that you need to make, you can use persistent connections. A + persistent connection is saved by PHP, so you can use the same connection for + multiple requests. + + + + For example, this simple program connects to the database 1000 times: + + + + +]]> + + + + It takes approximately 18 seconds to execute. If we change it to use a + persistent connection: + + + + "x")); +} + +?> +]]> + + + + ...it takes less than .02 seconds to execute, as it only makes one database + connection. + + + + Persistent connections need an identifier string (which is "x" in the above + example) to uniquely identify them. For a persistent connection to be used, + the hostname, port, persist string, and username and password (if given) must + match an existing persistent connection. Otherwise, a new connection will be + created with this identifying information. + +
+ diff --git a/reference/mongo/mongocollection/batchinsert.xml b/reference/mongo/mongocollection/batchinsert.xml index 0716cda71b..5064047c91 100644 --- a/reference/mongo/mongocollection/batchinsert.xml +++ b/reference/mongo/mongocollection/batchinsert.xml @@ -10,8 +10,9 @@ &reftitle.description; - public booleanMongoCollection::batchInsert + public mixedMongoCollection::batchInsert arraya + arrayoptionsarray() @@ -29,6 +30,26 @@ + + + options + + + + Options for the inserts. + + + + "safe" + + + Check that the inserts succeeded. + + + + + + @@ -36,7 +57,41 @@ &reftitle.returnvalues; - Returns if the arrays were saved. + If "safe" is set, returns an associative array with the status of the inserts + ("ok") and any error that may have occured ("err"). Otherwise, returns + &true; if the batch insert was successfully sent, &false; otherwise. + + + + + &reftitle.errors; + + Throws MongoCursorException if the "safe" option is + set and the insert fails. + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 1.0.5 + + Added "options" parameter. + + + + + diff --git a/reference/mongo/mongocollection/insert.xml b/reference/mongo/mongocollection/insert.xml index d85dfcabc9..64115e3f6b 100644 --- a/reference/mongo/mongocollection/insert.xml +++ b/reference/mongo/mongocollection/insert.xml @@ -12,7 +12,7 @@ public mixedMongoCollection::insert arraya - booleansafefalse + arrayoptionsarray() @@ -32,14 +32,24 @@ - safe + options - If the database should check that the insert was successful. + Options for the insert. + + + + "safe" + + + Check that the insert succeeded. + + + - + @@ -56,7 +66,32 @@ &reftitle.errors; - Throws MongoCursorException if safe is set and the insert fails. (Version 1.0.1+) + Throws MongoCursorException if the "safe" option is set and the insert fails. (Version 1.0.1+) + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 1.0.5 + + Changed second parameter to an array of options. Pre-1.0.5, the + second parameter was a boolean indicating the "safe" option. + + + + + diff --git a/reference/mongo/mongocollection/remove.xml b/reference/mongo/mongocollection/remove.xml index 7c2dceea9e..f077e8a2a3 100644 --- a/reference/mongo/mongocollection/remove.xml +++ b/reference/mongo/mongocollection/remove.xml @@ -10,9 +10,9 @@ &reftitle.description; - public booleanMongoCollection::remove + public mixedMongoCollection::remove arraycriteria - booleanjustOne&false; + arrayoptionsarray() @@ -32,11 +32,29 @@ - justOne + options - Remove at most one record matching this criteria. + Options for remove. + + + + "justOne" + + + Remove at most one record matching this criteria. + + + + + "safe" + + + Check that the remove succeeded and how many items were removed. + + + @@ -47,7 +65,43 @@ &reftitle.returnvalues; - Returns if the command was executed successfully. + If "safe" is set, returns an associative array with the status of the remove + ("ok"), the number of items removed ("n"), and any error that may have + occured ("err"). Otherwise, returns &true; if the remove was successfully + sent, &false; otherwise. + + + + + &reftitle.errors; + + Throws MongoCursorException if the "safe" option is set and the remove fails. + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 1.0.5 + + Changed second parameter to an array of options. Pre-1.0.5, the + second parameter was a boolean indicating the "justOne" option and + there was no safe option. + + + + + @@ -68,7 +122,7 @@ $halflife = $remaining/2; // remove half of it while ($halflife > 0) { - $uranium->remove(array('type' => 94), true); + $uranium->remove(array('type' => 94), array("justOne" => true)); $halflife--; } diff --git a/reference/mongo/mongocollection/save.xml b/reference/mongo/mongocollection/save.xml index 787d8b4c66..167c3c24ec 100644 --- a/reference/mongo/mongocollection/save.xml +++ b/reference/mongo/mongocollection/save.xml @@ -10,8 +10,9 @@ &reftitle.description; - public booleanMongoCollection::save + public mixedMongoCollection::save arraya + arrayoptionsarray() If the object is from the database, update the existing database object, otherwise @@ -32,6 +33,26 @@ Array to save. + + + + options + + + + Options for the save. + + + + "safe" + + + Check that the save succeeded. + + + + + @@ -44,6 +65,38 @@ + + &reftitle.errors; + + Throws MongoCursorException if the "safe" option is + set and the save fails. + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 1.0.5 + + Added "options" parameter. + + + + + + + + &reftitle.examples; diff --git a/reference/mongo/mongocollection/update.xml b/reference/mongo/mongocollection/update.xml index a6b153f958..4dcfa8a2eb 100644 --- a/reference/mongo/mongocollection/update.xml +++ b/reference/mongo/mongocollection/update.xml @@ -13,7 +13,7 @@ public booleanMongoCollection::update arraycriteria arraynewobj - arrayoptions&null; + arrayoptionsarray() @@ -74,6 +74,14 @@ may change its default behavior at some point in the future. + + + "safe" + + + Check that the update succeeded. + + @@ -81,12 +89,22 @@ + &reftitle.returnvalues; Returns if the update was successfully sent to the database. + + + &reftitle.errors; + + Throws MongoCursorException if the "safe" option is + set and the update fails. + + + &reftitle.changelog; @@ -106,11 +124,18 @@ second parameter was an optional boolean value specifying an upsert. + + 1.0.5 + + Added "safe" option. + + + &reftitle.examples; diff --git a/reference/mongo/mongocursor/getquery.xml b/reference/mongo/mongocursor/getquery.xml index 4d203739ce..2323d7a669 100644 --- a/reference/mongo/mongocursor/getquery.xml +++ b/reference/mongo/mongocursor/getquery.xml @@ -1,16 +1,16 @@ - + - MongoCursor::getQuery + MongoCursor::info Gets the query, fields, limit, and skip for this cursor &reftitle.description; - public arrayMongoCursor::getQuery + public arrayMongoCursor::info @@ -33,14 +33,14 @@ &reftitle.examples; - <function>MongoCursor::getQuery</function> example + <function>MongoCursor::info</function> example foo->bar->find(array("x" => 4), array("y" => false)); -var_dump($cursor->getQuery()); +var_dump($cursor->info()); ?> ]]> diff --git a/reference/mongo/mongogridfs/storebytes.xml b/reference/mongo/mongogridfs/storebytes.xml index 4c0868df82..f9ef854f9d 100644 --- a/reference/mongo/mongogridfs/storebytes.xml +++ b/reference/mongo/mongogridfs/storebytes.xml @@ -13,6 +13,7 @@ public mixedMongoGridFS::storeBytes stringbytes arrayextraarray() + arrayoptionsarray() @@ -40,6 +41,26 @@ + + + options + + + + Options for the store. + + + + "safe" + + + Check that this store succeeded. + + + + + + @@ -51,6 +72,14 @@ + + &reftitle.errors; + + Throws MongoCursorException if the "safe" option is + set and the insert fails. + + +