diff --git a/reference/mongo/connecting.xml b/reference/mongo/connecting.xml index 2afc542e4e..dd0af269f7 100644 --- a/reference/mongo/connecting.xml +++ b/reference/mongo/connecting.xml @@ -208,6 +208,12 @@ for ($i=0; $i<1000; $i++) { Most of the reasons that they are not recommended for relational databases are irrelevant to MongoDB. + + Persistent connections will become the default connection type in 1.0.12. To + create a non-persistent connection, you will need to pass + "persist" => false to + Mongo::__construct. +
diff --git a/reference/mongo/mongo.xml b/reference/mongo/mongo.xml index 020ea651b0..317b7c4b79 100644 --- a/reference/mongo/mongo.xml +++ b/reference/mongo/mongo.xml @@ -75,17 +75,23 @@ $db = $m->foo; // get the database named "foo" connected &false; + + public + string + status + &null; + protected string server - localhost:27017 + &null; protected boolean persistent - &false; + &null; @@ -133,6 +139,22 @@ $db = $m->foo; // get the database named "foo"
+
+ Fields + + + 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; diff --git a/reference/mongo/mongocollection/ensureindex.xml b/reference/mongo/mongocollection/ensureindex.xml index fc2bb80283..d84416b1d0 100644 --- a/reference/mongo/mongocollection/ensureindex.xml +++ b/reference/mongo/mongocollection/ensureindex.xml @@ -85,6 +85,18 @@ for checking if the index creation succeeded. The driver will throw a MongoCursorException if index creation failed. + + If you are using replication and the master has changed, using "safe" + will make the driver disconnect from the master, throw and exception, + and attempt to find a new master on the next operation (your + application must decide whether or not to retry the operation on the + new master). + + + If you do not use "safe" with a replica set and + the master changes, there will be no way for the driver to know about + the change so it will continuously and silently fail to write. + @@ -130,6 +142,14 @@ second parameter was an optional boolean value specifying a unique index. + 1.0.11 + + "safe" will trigger master failover, if necessary. + + + MongoException will be thrown if index name + (either generated or set) is longer than 128 bytes. + @@ -137,6 +157,23 @@ + + &reftitle.errors; + + Throws MongoException if the index name is longer than + 128 bytes. (Version 1.0.11+) + + + Throws MongoCursorException if the "safe" option is + set and the index creation fails. + + + Throws MongoCursorTimeoutException if the "safe" + option is set to a value greater than one and the database cannot replicate + the operation in MongoCollection::$wtimeout milliseconds. + + + &reftitle.examples; diff --git a/reference/mongo/mongocollection/insert.xml b/reference/mongo/mongocollection/insert.xml index 6785547a01..bbd7a9eae9 100644 --- a/reference/mongo/mongocollection/insert.xml +++ b/reference/mongo/mongocollection/insert.xml @@ -54,6 +54,18 @@ MongoCursorException if the insert did not succeed. + + If you are using replication and the master has changed, using "safe" + will make the driver disconnect from the master, throw and exception, + and attempt to find a new master on the next operation (your + application must decide whether or not to retry the operation on the + new master). + + + If you do not use "safe" with a replica set and + the master changes, there will be no way for the driver to know about + the change so it will continuously and silently fail to write. + If safe is an integer, will replicate the insert to that many machines before returning success (or throw an @@ -127,6 +139,12 @@ before) and added "fsync" option. + + 1.0.11 + + Disconnects on "not master" errors if "safe" is set. + + diff --git a/reference/mongo/mongocollection/remove.xml b/reference/mongo/mongocollection/remove.xml index 71823f209b..12a3681d7a 100644 --- a/reference/mongo/mongocollection/remove.xml +++ b/reference/mongo/mongocollection/remove.xml @@ -57,6 +57,18 @@ MongoCursorException if the update did not succeed. + + If you are using replication and the master has changed, using "safe" + will make the driver disconnect from the master, throw and exception, + and attempt to find a new master on the next operation (your + application must decide whether or not to retry the operation on the + new master). + + + If you do not use "safe" with a replica set and + the master changes, there will be no way for the driver to know about + the change so it will continuously and silently fail to write. + If safe is an integer, will replicate the update to that many machines before returning success (or throw an @@ -132,6 +144,12 @@ there was no safe option. + + 1.0.11 + + Disconnects on "not master" errors if "safe" is set. + + diff --git a/reference/mongo/mongocollection/save.xml b/reference/mongo/mongocollection/save.xml index aec3a2b23e..fb48ed6123 100644 --- a/reference/mongo/mongocollection/save.xml +++ b/reference/mongo/mongocollection/save.xml @@ -53,6 +53,18 @@ MongoCursorException if the insert did not succeed. + + If you are using replication and the master has changed, using "safe" + will make the driver disconnect from the master, throw and exception, + and attempt to find a new master on the next operation (your + application must decide whether or not to retry the operation on the + new master). + + + If you do not use "safe" with a replica set and + the master changes, there will be no way for the driver to know about + the change so it will continuously and silently fail to write. + If safe is an integer, will replicate the insert to that many machines before returning success (or throw an @@ -125,6 +137,12 @@ before) and added "fsync" option. + + 1.0.11 + + Disconnects on "not master" errors if "safe" is set. + + diff --git a/reference/mongo/mongocollection/update.xml b/reference/mongo/mongocollection/update.xml index 6e5d7f6007..af532d8dda 100644 --- a/reference/mongo/mongocollection/update.xml +++ b/reference/mongo/mongocollection/update.xml @@ -85,6 +85,18 @@ MongoCursorException if the update did not succeed. + + If you are using replication and the master has changed, using "safe" + will make the driver disconnect from the master, throw and exception, + and attempt to find a new master on the next operation (your + application must decide whether or not to retry the operation on the + new master). + + + If you do not use "safe" with a replica set and + the master changes, there will be no way for the driver to know about + the change so it will continuously and silently fail to write. + If safe is an integer, will replicate the update to that many machines before returning success (or throw an @@ -162,6 +174,12 @@ before) and added "fsync" option. + + 1.0.11 + + Disconnects on "not master" errors if "safe" is set. + + diff --git a/reference/mongo/mongocursor.xml b/reference/mongo/mongocursor.xml index 2080ad873d..1e270c164e 100644 --- a/reference/mongo/mongocursor.xml +++ b/reference/mongo/mongocursor.xml @@ -27,10 +27,7 @@ When the client attempts to get a result (by calling MongoCursor::next, directly or indirectly), the cursor moves into the post-query stage. At this point, the query has been executed - by the database and cannot be modified anymore. At this point, the only - functions available are the Iterator functions, - MongoCursor::hasNext, and - MongoCursor::getNext. + by the database and cannot be modified anymore. diff --git a/reference/mongo/mongocursor/batchsize.xml b/reference/mongo/mongocursor/batchsize.xml new file mode 100644 index 0000000000..259d305f46 --- /dev/null +++ b/reference/mongo/mongocursor/batchsize.xml @@ -0,0 +1,110 @@ + + + + + + MongoCursor::limit + Sets the number of results returned per result set + + + + &reftitle.description; + + public MongoCursorMongoCursor::batchSize + intnum + + + This cannot override MongoDB's limit on the amount of data it will return to + the client (i.e., if you set batch size to 1,000,000,000, MongoDB will still + only return 4-16MB of results). + + + To ensure consistent behavior, the rules of batchSize and limit behavior a + little complex but work "as expected". The rules are: hard limits override + soft limits with preference given to MongoCursor::limit + over MongoCursor::batchSize. After that, whichever is + set and lower than the other will take precedence. Some examples: + + +limit(-20)->batch(10); + +// one batch, at most 10 items +$cursor->limit(20)->batch(-10); + +// first batch: at most 10 items +$cursor->limit(10); + +// first batch: at most 10 items +$cursor->limit(10)->batch(20); + +// first batch: at most 10 items +$cursor->limit(20)->batch(10); + + +$cursor->limit(30)->batchSize(7) +// if we iterate through 28 items, the next call to getNext() will contact the +// database and request a batch of 2 documents + +?> +]]> + + + + + &reftitle.parameters; + + + + + num + + + + The number of results to return in the next batch. + + + + + + + + + &reftitle.returnvalues; + + Returns this cursor. + + + + + &reftitle.errors; + + Throws MongoCursorException if this cursor has + started iterating. This will change in 1.0.12, as this should be able to be + called at any time. + + + + + diff --git a/reference/mongo/mongocursorexception.xml b/reference/mongo/mongocursorexception.xml index f9d85e19ba..4f448133fb 100644 --- a/reference/mongo/mongocursorexception.xml +++ b/reference/mongo/mongocursorexception.xml @@ -35,9 +35,10 @@ Reset the cursor and try again. + - Various send errors + Get next batch send errors Code: 1 @@ -47,6 +48,7 @@ still up and the network is okay. + cursor not found @@ -63,24 +65,35 @@ this). + - Various database errors + Couldn't get response header. Code: 4 + + + - The database errored out on the query. The error message should be fairly - self-explanatory, but you can check the database log for details. + cursor->buf.pos is null + + + Code: 3 + + + This may indicate you are out of hard driver space or some other + extraordinary circumstance. + couldn't get response header - Code: 3 + Code: 4 The driver could not fetch a reply header from the database, so it gave @@ -88,6 +101,7 @@ try the query again. + no db response @@ -101,16 +115,7 @@ response, this means the database didn't give one. - - - no db response - - - Code: 5 - - - - + bad response length: %d, max: %d, did the db assert? @@ -125,9 +130,10 @@ 4Mb). A response of less than 0 often means a database assertion occured. + - incomplete header/response + incomplete header Code: 7 @@ -137,6 +143,59 @@ but broke off in the middle. Probably indicates a network problem. + + + + incomplete response + + + Code: 8 + + + Highly unusual. Occurs if the database response started out correctly, + but broke off in the middle. Probably indicates a network problem. + + + + + + couldn't find a response + + + Code: 9 + + + If the response was cached and now cannot be located. + + + + + + error getting socket + + + Code: 10 + + + The socket was closed or encountered an error. The driver should + automatically reconnect (if possible) on the next operation. + + + + + + couldn't find reply, please try again + + + Code: 11 + + + The driver saves any database responses it cannot immediately match with a + request. This exception occurs if the driver has already passed your + request's response and cannot find your response in its cache. + + + error getting database response: errstr @@ -149,40 +208,47 @@ subsystem. On Windows, the error message is prefixed with "WSA". + - error getting database response: <various> + Timeout error - Code: 8 + Code: 13 - Something went wrong at the socket layer. This will return the error - message from the C socket library. + If there was an error while waiting for a query to complete. + - couldn't find a response + couldn't send query: <various> - Code: 9 + Code: 14 - If the response was cached and now cannot be located. - - - - - various - - - Code: 10 - - - No code given by the database. + C socket error on send. + +
+ + +
+ Errors passed through by the database + + Database errors should always trigger MongoCursorExceptions on queries. + Error messages and codes are sent directly from the database and you should + be able to see matching errors in the database log. + + + + A few common database errors are listed below: + + + E11000 duplicate key error index: foo.bar.$X dup key: { /* ... */ } @@ -194,6 +260,21 @@ Database error for duplicate keys. + + + + not master + + + Codes: 10107, 13435, and 10058 + + + Not master errors, piped through by the database. Each of these will + cause the driver to disconnect and attempt to find a new master. The + actual error you get on failover may not be a "not master" error, + depending on when the change in master occurs. + +
diff --git a/reference/mongo/mongoexception.xml b/reference/mongo/mongoexception.xml index 2803893df6..ae981105ba 100644 --- a/reference/mongo/mongoexception.xml +++ b/reference/mongo/mongoexception.xml @@ -22,9 +22,160 @@ + - non-utf8 string + The MongoSomething object has not been correctly initialized by its constructor + + + Code: 0 + + + Probably your Mongo object is not connected to a database server. + + + + + + zero-length keys are not allowed, did you use $ with double quotes? + + + Code: 1 + + + You tried to save "" as a key. You generally should not do this. "" can + mess up subobject access and is used by MongoDB internally. However, if + you really want, you can set + mongo.allow_empty_keys + to true in your php.ini file to override this sanity check. If you + override this, it is highly recommended that you set error checking to + strict to avoid string interpolation errors. + + + + + + '.' not allowed in key: <key> + + + Code: 2 + + + You attempted to write a key with '.' in it, which is prohibited. + + + + + + insert too large: <size>, max: <max> + + + Code: 3 + + + You're attempting to send too much data to the database at once: the + database will only accept inserts up to a certain size (currently 16 MB). + + + + + + no elements in doc + + + Code: 4 + + + You're attempting to save a document with no fields. + + + + + + size of BSON doc is <size> bytes, max <max>MB + + + Code: 5 + + + You're attempting to save a document that is larger than MongoDB can save. + + + + + + no documents given + + + Code: 6 + + + You're attempting to batch insert an empty array of documents. + + + + + + MongoCollection::group takes an array, object, or MongoCode key + + + Code: 7 + + + Wrong type parameter send to MongoCollection::group. + + + + + + field names must be strings + + + Code: 8 + + + You should format field selectors as + array("field1" => 1, "field2" => 1, ..., "fieldN" => 1). + + + + + + invalid regex + + + Code: 8 + + + The regex passed to MongoRegex is not of the + correct form. + + + + + + MongoDBRef::get: $ref field must be a string + + + Code: 10 + + + + + + MongoDBRef::get: $db field must be a string + + + Code: 11 + + + + + + non-utf8 string: <str> + + + Code: 12 This error occurs if you attempt to send a non-utf8 string to the @@ -32,22 +183,37 @@ options for the transition option of quieting this exception. + - invalid regex + mutex error: <err> - The regex you passed in does not match the form /regex/flags. + Code: 13 + + + The driver uses mutexes for synchronizing requests and responses in + multithreaded environments. This is a fairly serious error and may not + have a stack trace. It's unusual and should be reported to maintainers + with any system information and steps to reproduce that you can provide. + - The MongoSomething object has not been correctly initialized by its constructor + index name to long: <len>, max <max> characters - Probably your Mongo object is not connected to a database server. + Code: 14 + + + Indexes with names longer than 128 characters cannot be created. If you + get this error, you should use + MongoCollection::ensureIndex's "name" option to + create a shorter name for your index. + diff --git a/reference/mongo/mongoid.xml b/reference/mongo/mongoid.xml index d41a44c922..5208c2634f 100644 --- a/reference/mongo/mongoid.xml +++ b/reference/mongo/mongoid.xml @@ -60,6 +60,13 @@ C:7:"MongoId":24:{4af9f23d8ead0e1d32000000} + + + public + string + $id + &null; + &Methods; @@ -68,6 +75,20 @@ C:7:"MongoId":24:{4af9f23d8ead0e1d32000000} +
+ Fields + + + $id + + + This field contains the string representation of this object. + + + + +
+
&reftitle.seealso; diff --git a/reference/mongo/mongoid/getinc.xml b/reference/mongo/mongoid/getinc.xml new file mode 100644 index 0000000000..279eb97928 --- /dev/null +++ b/reference/mongo/mongoid/getinc.xml @@ -0,0 +1,50 @@ + + + + + + MongoId::getPID + Gets the incremented value to create this id + + + + &reftitle.description; + + public intMongoId::getInc + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the incremented value used to create this MongoId. + + + + + diff --git a/reference/mongo/mongoid/getpid.xml b/reference/mongo/mongoid/getpid.xml new file mode 100644 index 0000000000..53dcbc37d0 --- /dev/null +++ b/reference/mongo/mongoid/getpid.xml @@ -0,0 +1,50 @@ + + + + + + MongoId::getPID + Gets the process id used to create this + + + + &reftitle.description; + + public intMongoId::getPID + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the PID used to create this MongoId. + + + + + diff --git a/reference/mongo/types.xml b/reference/mongo/types.xml index 6ecfa46baa..b530ccbb9f 100644 --- a/reference/mongo/types.xml +++ b/reference/mongo/types.xml @@ -7,6 +7,39 @@ +
+ Change in number handling + + + The default behavior for numbers will be changing in version 1.1.0. For + most programmers, this will make the driver's numeric handling smoother and + more natural, but it may require updating application code to work. + + + + The backwards-breaking changes will be related to the serialization and + deserialization of integers. You can test how these changes will affect + your code by specifying the .ini changes now: mongo.native_int and + mongo.long_as_object will default to &true;. + + + Serialization: by default pre-1.1.0, all PHP integers are serialized as + 32-bit integers, even on 64-bit machines. This means that large numbers get + silently truncated. In 1.1.0, 64-bit machines will, by default, save + integers as 64-bit integers. 32-bit machines will continue to save integers + as 32-bit integers (you can also use the MongoInt32 + and MongoInt64 classes to use 32-bit int on a 64-bit + machine or visa versa). + + + Deserialization: by default pre-1.1.0, 64-bit integers will be deserialized + as doubles. This is not a perfect mapped and means they will be resaved as + the wrong type (double instead of 64-bit integer). In 1.1.0, 64-bit + integers will be returned as MongoInt64's on 32-bit + machines. + +
+
MongoDB allows programmers to save and query for data expressed in all of the diff --git a/reference/mongo/versions.xml b/reference/mongo/versions.xml index 02b6c2fa20..2a5f4af323 100644 --- a/reference/mongo/versions.xml +++ b/reference/mongo/versions.xml @@ -88,6 +88,7 @@ + @@ -118,6 +119,8 @@ + +