diff --git a/reference/mongo/book.xml b/reference/mongo/book.xml index 5515453479..ea3320e8ce 100644 --- a/reference/mongo/book.xml +++ b/reference/mongo/book.xml @@ -18,7 +18,7 @@ &ChangelogListingTitle; &ChangelogListingDescription; - + diff --git a/reference/mongo/core.xml b/reference/mongo/core.xml index 541e84e95f..94f0701ebf 100644 --- a/reference/mongo/core.xml +++ b/reference/mongo/core.xml @@ -11,6 +11,7 @@ &reference.mongo.mongo; + &reference.mongo.mongoclient; &reference.mongo.mongodb; &reference.mongo.mongocollection; &reference.mongo.mongocursor; diff --git a/reference/mongo/mongo.xml b/reference/mongo/mongo.xml index 6afcde4a56..897309a3a5 100644 --- a/reference/mongo/mongo.xml +++ b/reference/mongo/mongo.xml @@ -3,7 +3,7 @@ - The Mongo class + The Mongo class [deprecated] Mongo @@ -14,23 +14,23 @@ A connection between PHP and MongoDB. - This class is used to create and manage connections. A typical use is: - -foo; // get the database named "foo" - -?> -]]> - + This class extends MongoClient and provides access to + several deprecated methods. - See Mongo::__construct and the section on - connecting for more information - about creating connections. + For backwards compatibility, it also defaults the "w" + option of its constructor argument to 0, which does not + require write operations to be acknowledged by the server. See + MongoClient::__construct for more information. + + + + This class has been DEPRECATED as of version + 1.3.0. Relying on this feature is highly discouraged. Please use + MongoClient instead. + + @@ -46,213 +46,24 @@ $db = $m->foo; // get the database named "foo" Mongo + + + extends + MongoClient + - &Constants; - - const - string - Mongo::VERSION - - - const - string - Mongo::DEFAULT_HOST - "localhost" - - - const - int - Mongo::DEFAULT_PORT - 27017 - - - const - int - Mongo::RP_PRIMARY - 0 - - - const - int - Mongo::RP_PRIMARY_PREFERRED - 1 - - - const - int - Mongo::RP_SECONDARY - 2 - - - const - int - Mongo::RP_SECONDARY_PREFERRED - 3 - - - const - int - Mongo::RP_NEAREST - 4 - - - Fields - - public - boolean - connected - &false; - - - public - string - status - &null; - - - protected - string - server - &null; - - - protected - boolean - persistent - &null; - - - &Methods; + + &InheritedMethods; + - -
- &reftitle.constants; -
- Mongo Constants - - - Mongo::VERSION - - - PHP driver version. May be suffixed with "+" or "-" if it is in-between - versions. - - - - - Mongo::DEFAULT_HOST - "localhost" - - - Host to connect to if no host is given. - - - - - Mongo::DEFAULT_PORT - 27017 - - - Port to connect to if no port is given. - - - - - Mongo::RP_PRIMARY - 0 - - - Read preference for the - primary replica set member. - - - - - Mongo::RP_PRIMARY_PREFERRED - 1 - - - Read preference for - preferring the primary replica set member. - - - - - Mongo::RP_SECONDARY - 2 - - - Read preference for a - secondary replica set member. - - - - - Mongo::RP_SECONDARY_PREFERRED - 3 - - - Read preference for - preferring a secondary replica set member. - - - - - Mongo::RP_NEAREST - 4 - - - Read preference for the - nearest replica set member. - - - - -
-
- -
- Fields - - - status - - - This property will be set to &true; if we have a open connection - the database based on the ReadPreference and tagsets (for ReplicaSet - connections), &false; otherwise. - This property does not take authentication into account. - - - - - status - - - If this is a persistent connection, if the connection was created for - this object or is being reused. If this is not a persistent connection, - this field should be &null;. - - - - -
- -
- &reftitle.seealso; - - MongoDB core docs on connecting. - -
- diff --git a/reference/mongo/mongoclient.xml b/reference/mongo/mongoclient.xml new file mode 100644 index 0000000000..1a1c967ea2 --- /dev/null +++ b/reference/mongo/mongoclient.xml @@ -0,0 +1,281 @@ + + + + + + The MongoClient class + MongoClient + + + +
+ &reftitle.intro; + + A connection between PHP and MongoDB. + + + This class is used to create and manage connections. A typical use is: + +foo; // get the database named "foo" + +?> +]]> + + + + See MongoClient::__construct and the section on + connecting for more information + about creating connections. + +
+ + +
+ &reftitle.classsynopsis; + + + + MongoClient + + + + + MongoClient + + + + + &Constants; + + const + string + MongoClient::VERSION + + + const + string + MongoClient::DEFAULT_HOST + "localhost" + + + const + int + MongoClient::DEFAULT_PORT + 27017 + + + const + int + MongoClient::RP_PRIMARY + 0 + + + const + int + MongoClient::RP_PRIMARY_PREFERRED + 1 + + + const + int + MongoClient::RP_SECONDARY + 2 + + + const + int + MongoClient::RP_SECONDARY_PREFERRED + 3 + + + const + int + MongoClient::RP_NEAREST + 4 + + + &Properties; + + public + boolean + connected + &false; + + + public + string + status + &null; + + + protected + string + server + &null; + + + protected + boolean + persistent + &null; + + + &Methods; + + + + +
+ + +
+ &reftitle.constants; +
+ MongoClient Constants + + + MongoClient::VERSION + + + PHP driver version. May be suffixed with "+" or "-" if it is in-between + versions. + + + + + MongoClient::DEFAULT_HOST + "localhost" + + + Host to connect to if no host is given. + + + + + MongoClient::DEFAULT_PORT + 27017 + + + Port to connect to if no port is given. + + + + + MongoClient::RP_PRIMARY + 0 + + + Read preference for the + primary replica set member. + + + + + MongoClient::RP_PRIMARY_PREFERRED + 1 + + + Read preference for + preferring the primary replica set member. + + + + + MongoClient::RP_SECONDARY + 2 + + + Read preference for a + secondary replica set member. + + + + + MongoClient::RP_SECONDARY_PREFERRED + 3 + + + Read preference for + preferring a secondary replica set member. + + + + + MongoClient::RP_NEAREST + 4 + + + Read preference for the + nearest replica set member. + + + + +
+
+ +
+ Fields + + + connected + + + This property will be set to &true; if we have a open connection + the database based on the ReadPreference and tagsets (for ReplicaSet + connections), &false; otherwise. This property does not take + authentication into account. + + + + + status + + + If this is a persistent connection, if the connection was created for + this object or is being reused. If this is not a persistent connection, + this field should be &null;. + + + + +
+ +
+ &reftitle.seealso; + + MongoDB core docs on connecting. + +
+ + + + + &reference.mongo.entities.mongoclient; + + + + diff --git a/reference/mongo/mongo/close.xml b/reference/mongo/mongoclient/close.xml similarity index 85% rename from reference/mongo/mongo/close.xml rename to reference/mongo/mongoclient/close.xml index 577902db75..5b4860c240 100644 --- a/reference/mongo/mongo/close.xml +++ b/reference/mongo/mongoclient/close.xml @@ -1,22 +1,23 @@ - + - Mongo::close + MongoClient::close Closes this connection &reftitle.description; - public boolMongo::close + public boolMongoClient::close boolean|stringconnection - The Mongo::close method forcefully closes a connection to the - database, even if persistent connections are being used. You do under - normal circumstance never have to do this. + The MongoClient::close method forcefully closes a + connection to the database, even if persistent connections are being used. + You should never have to do this under normal + circumstances. @@ -41,14 +42,14 @@ If connection is &true; then all connections as known by the connection manager will be closed. This can include connections that are not - referenced to in the connection string used to create the object that + referenced in the connection string used to create the object that you are calling close on. If connection is a string argument, then it will only close the connection identified by this hash. Hashes are identifiers for a connection and can be obtained by calling - Mongo::getConnections. + MongoClient::getConnections. @@ -73,7 +74,7 @@ getConnections(); @@ -143,7 +144,7 @@ Closing 'whisky:13001;X;4948': ok &reftitle.seealso; - Mongo::getConnections + MongoClient::getConnections diff --git a/reference/mongo/mongo/connect.xml b/reference/mongo/mongoclient/connect.xml similarity index 85% rename from reference/mongo/mongo/connect.xml rename to reference/mongo/mongoclient/connect.xml index 110cfb2daa..4c4d502bda 100644 --- a/reference/mongo/mongo/connect.xml +++ b/reference/mongo/mongoclient/connect.xml @@ -1,16 +1,16 @@ - + - Mongo::connect + MongoClient::connect Connects to a database server &reftitle.description; - public boolMongo::connect + public boolMongoClient::connect diff --git a/reference/mongo/mongo/construct.xml b/reference/mongo/mongoclient/construct.xml similarity index 82% rename from reference/mongo/mongo/construct.xml rename to reference/mongo/mongoclient/construct.xml index 99c543ff79..5e65104687 100644 --- a/reference/mongo/mongo/construct.xml +++ b/reference/mongo/mongoclient/construct.xml @@ -1,16 +1,16 @@ - + - Mongo::__construct + MongoClient::__construct Creates a new database connection object &reftitle.description; - public Mongo::__construct + public MongoClient::__construct stringserver"mongodb://localhost:27017" arrayoptionsarray("connect" => &true;) @@ -56,7 +56,7 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db One part of the options governs how the driver reads from secondary nodes - in a replicaset environment. Extra information on how these read + in a replica set environment. Extra information on how these read preferences work is available as well through the read preferences documentation page. @@ -94,7 +94,7 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db &true;. When set to &false; the driver will automatically connection to the server whenever it is necessary to do a query. Alternatively, you can run - Mongo::connect manually. + MongoClient::connect manually. @@ -156,14 +156,15 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db with control from which secondaries data can be read from. - Allows values are: primary, - primaryPreferred, - secondary, secondaryPreferred - and nearest. + 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. + preferences for more information. @@ -171,13 +172,13 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db "readPreferenceTags" - Specifies the read preference tags. Tags can be used in combination - with the readPreference option to further control - which secondaries data might be read from. + 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. + preferences for more information. @@ -215,42 +216,42 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db "w" - The w options controls until how long the driver - blocks with regards to writing to replicaset members. + The w option specifies the write concern for the + driver, which determines how long the driver blocks when writing. The + default value is 1. - A positive integer value controls how many - nodes in the replicaset have received the write instruction before - the driver continues. A value of 3 would mean - that the write has been applied to the primary as well as two other - replicaset members. + 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 makes sure that the write operation has been applied to the - majority (more than 50%) of the participating nodes. + and ensures that the write operation has been applied to the majority + (more than 50%) of the participating nodes. See the core documentation on replica sets for more information. - - Please note that setting "w" implicitly sets - fireAndForget to false. - "wTimeout" - This option is used in combination with the "w" option. It controls - how many milliseconds the server waits for the write concern to be - satisfied. If it takes longer then the server signals to the driver - that it took too long and the driver will throw a - MongoCursorException exception. + This option is used in combination with the "w" + option. It controls how many milliseconds the server waits for the + write concern to be satisfied. If it takes longer then the server + signals to the driver that it took too long and the driver will throw + a MongoCursorException exception. @@ -293,7 +294,7 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db 1.3.0 - Added the "fireAndForget", + Added the "readPreference", "readPreferenceTags", "w" and "wTimeout" options. @@ -319,7 +320,7 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db 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 + MongoClient 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 @@ -399,7 +400,7 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db &reftitle.examples; - <function>Mongo::__construct</function> replica set example + <function>MongoClient::__construct</function> 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 @@ -410,11 +411,11 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db "myReplSet")); +$m1 = new MongoClient("mongodb://sf2.example.com,ny1.example.com", array("replicaSet" => "myReplSet")); // 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" => "myReplSet")); +$m2 = new MongoClient("mongodb://ny1.example.com", array("replicaSet" => "myReplSet")); ?> ]]> @@ -454,7 +455,7 @@ $m2 = new Mongo("mongodb://ny1.example.com", array("replicaSet" => "myReplSet")) ]]> @@ -467,14 +468,14 @@ $m = new Mongo("mongodb:///tmp/mongodb-20000.sock"); ]]> - <function>Mongo::__construct</function> authentication example + <function>MongoClient::__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: @@ -500,14 +501,14 @@ switched to db admin ]]> - <function>Mongo::__construct</function> read preference example + <function>MongoClient::__construct</function> read preference example 'rs')); +$m = new MongoClient($uri, array('replicaSet' => 'rs')); ]]> diff --git a/reference/mongo/mongo/dropdb.xml b/reference/mongo/mongoclient/dropdb.xml similarity index 82% rename from reference/mongo/mongo/dropdb.xml rename to reference/mongo/mongoclient/dropdb.xml index e34dc72cd6..aaf0b71aa7 100644 --- a/reference/mongo/mongo/dropdb.xml +++ b/reference/mongo/mongoclient/dropdb.xml @@ -1,16 +1,16 @@ - + - Mongo::dropDB + MongoClient::dropDB Drops a database [deprecated] &reftitle.description; - public arrayMongo::dropDB + public arrayMongoClient::dropDB mixeddb @@ -33,10 +33,10 @@ - The database to drop. Can be a MongoDB object or the name of the database. + The database to drop. Can be a MongoDB object or the name of the database. - + diff --git a/reference/mongo/mongo/get.xml b/reference/mongo/mongoclient/get.xml similarity index 76% rename from reference/mongo/mongo/get.xml rename to reference/mongo/mongoclient/get.xml index 6a58cfe27d..baff43a15f 100644 --- a/reference/mongo/mongo/get.xml +++ b/reference/mongo/mongoclient/get.xml @@ -1,27 +1,27 @@ - + - Mongo::__get + MongoClient::__get Gets a database &reftitle.description; - public MongoDBMongo::__get + public MongoDBMongoClient::__get stringdbname - This is the cleanest way of getting a database. If the database name has any - special characters, Mongo::selectDB will need to be - used. However, in most cases, this should be sufficient. + This is the cleanest way of getting a database. If the database name has any + special characters, MongoClient::selectDB will need to + be used; however, this should be sufficient for most cases. selectDB("foo"); @@ -46,13 +46,13 @@ $db = $mongo->foo; The database name. - + - &reftitle.returnvalues; + &reftitle.returnvalues; Returns a new db object. diff --git a/reference/mongo/mongo/gethosts.xml b/reference/mongo/mongoclient/gethosts.xml similarity index 87% rename from reference/mongo/mongo/gethosts.xml rename to reference/mongo/mongoclient/gethosts.xml index db0f0e2bb8..ec14db63f2 100644 --- a/reference/mongo/mongo/gethosts.xml +++ b/reference/mongo/mongoclient/gethosts.xml @@ -1,21 +1,21 @@ - + - Mongo::getHosts - Updates status for all hosts associated with this + MongoClient::getHosts + Updates status for all associated hosts &reftitle.description; - public arrayMongo::getHosts + public arrayMongoClient::getHosts - This method is only useful with a connection to a replica set. It returns + This method is only useful with a connection to a replica set. It returns the status of all of the hosts in the set. Without a replica set, it will just return an array with one element containing the host that you are connected to. @@ -35,7 +35,7 @@ &reftitle.returnvalues; - Returns an array of information about the hosts in the set. Includes each + Returns an array of information about the hosts in the set. Includes each host's hostname, its health (1 is healthy), its state (1 is primary, 2 is secondary, 0 is anything else), the amount of time it took to ping the server, and when the last ping occurred. For example, on a three-member @@ -43,7 +43,7 @@ array(4) { ["host"]=> @@ -132,7 +132,7 @@ array(2) { &reftitle.seealso; - Mongo::getConnections + MongoClient::getConnections diff --git a/reference/mongo/mongo/getreadpreference.xml b/reference/mongo/mongoclient/getreadpreference.xml similarity index 85% rename from reference/mongo/mongo/getreadpreference.xml rename to reference/mongo/mongoclient/getreadpreference.xml index 0f5e30eea4..82e3c743cf 100644 --- a/reference/mongo/mongo/getreadpreference.xml +++ b/reference/mongo/mongoclient/getreadpreference.xml @@ -1,16 +1,16 @@ - + - Mongo::getReadPreference + MongoClient::getReadPreference Get the read preference for this connection &reftitle.description; - public arrayMongo::getReadPreference + public arrayMongoClient::getReadPreference @@ -35,13 +35,13 @@ &reftitle.examples; - <methodname>Mongo::getReadPreference</methodname> return value example + <methodname>MongoClient::getReadPreference</methodname> return value example setReadPreference(Mongo::RP_SECONDARY, array( +$m = new MongoClient(); +$m->setReadPreference(MongoClient::RP_SECONDARY, array( array('dc' => 'east', 'use' => 'reporting'), array('dc' => 'west'), array(), diff --git a/reference/mongo/mongo/listdbs.xml b/reference/mongo/mongoclient/listdbs.xml similarity index 83% rename from reference/mongo/mongo/listdbs.xml rename to reference/mongo/mongoclient/listdbs.xml index 69f7cdd1bb..7b103e381f 100644 --- a/reference/mongo/mongo/listdbs.xml +++ b/reference/mongo/mongoclient/listdbs.xml @@ -1,16 +1,16 @@ - + - Mongo::listDBs + MongoClient::listDBs Lists all of the databases available. &reftitle.description; - public arrayMongo::listDBs + public arrayMongoClient::listDBs @@ -23,19 +23,19 @@ &reftitle.returnvalues; - Returns an associative array containing three fields. The first field is - databases, which in turn contains an array. Each element - of the array is an associative array corresponding to a database, giving the - database's name, size, and if it's empty. The other two fields are + Returns an associative array containing three fields. The first field is + databases, which in turn contains an array. Each element + of the array is an associative array corresponding to a database, giving th + database's name, size, and if it's empty. The other two fields are totalSize (in bytes) and ok, which is 1 if this method ran successfully. - + &reftitle.examples; - <methodname>Mongo::listDBs</methodname> example + <methodname>MongoClient::listDBs</methodname> example Example demonstrating how to use listDBs and the returned data structure. @@ -43,7 +43,7 @@ listDBs(); print_r($dbs); @@ -61,7 +61,7 @@ Array ( [name] => doctrine [sizeOnDisk] => 218103808 - [empty] => + [empty] => ) ) diff --git a/reference/mongo/mongo/selectcollection.xml b/reference/mongo/mongoclient/selectcollection.xml similarity index 83% rename from reference/mongo/mongo/selectcollection.xml rename to reference/mongo/mongoclient/selectcollection.xml index 7b3b45c0ea..3aa0831ce7 100644 --- a/reference/mongo/mongo/selectcollection.xml +++ b/reference/mongo/mongoclient/selectcollection.xml @@ -1,16 +1,16 @@ - + - Mongo::selectCollection + MongoClient::selectCollection Gets a database collection &reftitle.description; - public MongoCollectionMongo::selectCollection + public MongoCollectionMongoClient::selectCollection stringdb stringcollection @@ -29,7 +29,7 @@ The database name. - + collection @@ -39,13 +39,13 @@ The collection name. - + - &reftitle.returnvalues; + &reftitle.returnvalues; Returns a new collection object. @@ -61,11 +61,11 @@ &reftitle.examples; - <function>Mongo::selectCollection</function> example + <function>MongoClient::selectCollection</function> example selectCollection("foo", "bar.baz"); // which is equivalent to diff --git a/reference/mongo/mongo/selectdb.xml b/reference/mongo/mongoclient/selectdb.xml similarity index 84% rename from reference/mongo/mongo/selectdb.xml rename to reference/mongo/mongoclient/selectdb.xml index 9f8884bd5a..94c3a7dbef 100644 --- a/reference/mongo/mongo/selectdb.xml +++ b/reference/mongo/mongoclient/selectdb.xml @@ -1,16 +1,16 @@ - + - Mongo::selectDB + MongoClient::selectDB Gets a database &reftitle.description; - public MongoDBMongo::selectDB + public MongoDBMongoClient::selectDB stringname @@ -28,13 +28,13 @@ The database name. - + - &reftitle.returnvalues; + &reftitle.returnvalues; Returns a new db object. diff --git a/reference/mongo/mongo/setreadpreference.xml b/reference/mongo/mongoclient/setreadpreference.xml similarity index 81% rename from reference/mongo/mongo/setreadpreference.xml rename to reference/mongo/mongoclient/setreadpreference.xml index a1402f5e66..f3f1cb213c 100644 --- a/reference/mongo/mongo/setreadpreference.xml +++ b/reference/mongo/mongoclient/setreadpreference.xml @@ -1,16 +1,16 @@ - + - Mongo::setReadPreference + MongoClient::setReadPreference Set the read preference for this connection &reftitle.description; - public boolMongo::setReadPreference + public boolMongoClient::setReadPreference intread_preference arraytags @@ -29,16 +29,16 @@ &reftitle.examples; - <methodname>Mongo::setReadPreference</methodname> tag set array syntax example + <methodname>MongoClient::setReadPreference</methodname> tag set array syntax example setReadPreference(Mongo::RP_NEAREST, array( +$m->setReadPreference(MongoClient::RP_NEAREST, array( array('dc' => 'east', 'use' => 'reporting'), array('dc' => 'west'), )); diff --git a/reference/mongo/mongo/tostring.xml b/reference/mongo/mongoclient/tostring.xml similarity index 83% rename from reference/mongo/mongo/tostring.xml rename to reference/mongo/mongoclient/tostring.xml index cca938c8b8..08191e3e1f 100644 --- a/reference/mongo/mongo/tostring.xml +++ b/reference/mongo/mongoclient/tostring.xml @@ -1,16 +1,16 @@ - + - Mongo::__toString + MongoClient::__toString String representation of this connection &reftitle.description; - public stringMongo::__toString + public stringMongoClient::__toString