Mongo is dead, long live MongoClient
This afternoon we published version 1.3.0 of the MongoDB PHP driver. Besides a number of bug fixes since RC2 and RC3, this new release also includes a new MongoClient
class. This new MongoClient class serves as a replacement for the Mongo
class. The old Mongo
class is now deprecated and will be removed in a future release, although we are keeping it in place for now because of backwards compatibility reasons. We have already removed it mostly from the documentation, and are working to update all our other material as well.
All of the other MongoDB drivers are making a similar change.
Now, you may be wondering why we are replacing Mongo
with MongoClient
across the board. The biggest reason is that the new class will have acknowledged writes on by defaultβor expressed in deprecated wording: MongoClient has safe mode on by default. We are moving away from the word safe though, mainly because the definition of the word has very little to do with its meaning in the MongoDB context. Your data is perfectly safe without safe mode on as well (in fact, that is what journaling is for). The safe option determined whether or not the driver would wait for the MongoDB server to acknowledge a write operation.
Together with the addition of the MongoClient
class we will deprecate the safe option to methods handling writes, such as MongoCollection::insert(), MongoCollection::update(), and others. We do provide a new way of controlling how the driver waits for the server to acknowledge writes (or not). The connection string now supports the w
option, which you can use as shown in the following examples:
-
Turning off acknowledged writes:
$m = new MongoClient('mongodb://localhost/?w=0');
-
Turning on acknowledged writes (the default):
$m = new MongoClient('mongodb://localhost/?w=1');
-
Turning on replica set acknowledged writes:
$m = new MongoClient('mongodb://localhost/?w=2');
Setting w
in the connection strings makes that the default write concern for any write operation. You can of course override this per write operation as well, by specifying the w
option:
<?php $m = new MongoClient('mongodb://localhost/'); /* By default writes are now acknowledged */ $m->demoDb->collection->insert( [ 'client' => 'awesome' ], // β document [ 'w' => 0 ] // β don't acknowledge writes for this insert ); ?>
If the server acknowledges that the write operation could not succeed, for example when you have a duplicate _id
key violation, then the driver will throw a MongoCursorException. The driver uses acknowledged writes by default with MongoClient
, which means you are required to handle the cases where the write did not succeed and the exception is thrown:
<?php $m = new MongoClient('mongodb://localhost/'); try { $m->demoDb->collection->insert( [ '_id' => 'awesome' ]); } catch ( MongoCursorException $e ) { echo $e->getCode(), ': ', $e->getMessage(), "\n"; } ?>
You can either retry the write yourself, or not, depending on the reason why the write did not succeed. In case of a duplicate key violation, you probably do not want to retry. In case a connection could not be made, you probably do want to retry (after a certain timeout).
So to repeat our major change: The new MongoClient class uses acknowledged writes by default.

Comments
Wouldn't this change have required a 2.0 release of the Driver instead as this is a Major change (assuming you guys are using semantic versioning)?
@Henrik: It's a major change, but it does not break backwards compatibility. At some point we will make such a release (when we remove Mongo
f.e.), and then call it 2.0
.
Yeah, it's a cool feature.
However, in your examples they require the acknowledge write flag to be set in the connection...
... So that means you can't define that in a 'query' basis?
Hugz.
@Ricardo: You can still set this per query as well:
<?php $m = new MongoClient(); // localhost, with acknowledged writes $c = $m->database->collection; // do not acknowledge writes: $c->insert( array( 'foo' => 'bar' ), array( 'w' => 0 ) ); // do acknowledge writes: $c->insert( array( 'foo' => 'bar' ), array( 'w' => 1 ) ); // or just, as it is inherited from the connection string: $c->insert( array( 'foo' => 'bar' ) ); ?>
cheers, Derick
Shortlink
This article has a short URL available: https://drck.me/mongoclient-9mq