Database Reference
In-Depth Information
Modifying a Document Atomically
Like the
save()
and
update()
functions, the
findAndModify()
function can be invoked from the PHP driver.
Remember that you can use the
findAndModify()
function to modify a document atomically and return the results
after the update executes successfully. You use the
findAndModify()
function to update a single document—and
nothing more. You may recall that, by default, the document returned will
not
show the modifications made—
returning the document with the modifications made would require specifying an additional argument: the
new
parameter.
The
findAndModify
function takes four parameters;
query
,
update
,
fields
,
and
options
.
Some of these are
optional, depending on your actions. For example, when specifying the
update
criteria, the fields and options are
optional. However when you wish to use the
remove
option, the
update
and
fields
parameters need to be specified
(using
null
, for example). The following list details the available parameters:
query
: Specifies a filter for the query. If this parameter isn't specified, then all documents in
the collection will be seen as possible candidates, and the first document encountered will be
updated or removed.
•
update
: Specifies the information to update the document. Note that any of the modifier
operators specified previously can be used to accomplish this.
•
fields
: Specifies the fields you would like to see returned, rather than the entire document.
This parameter behaves identically to the
fields
parameter in the
find()
function. Note that
the
_id
field will always be returned, even if that field isn't included in your list of fields to return.
•
options
: Specifies the options to apply. The following options can be used:
•
sort
: Sorts the matching documents in a specified order.
•
remove
: If set to
true
, the first matching document will be removed.
•
update
: If set to
true
, an update will be performed on the selected document.
•
new
: If set to
true
, returns the updated document, rather than the selected document.
Note that this parameter is not set by default, which might be a bit confusing in some
circumstances.
•
upsert
: If set to
true
, performs an upsert.
•
Now let's look at a set of examples that illustrate how to use these parameters. The first example searches for a
contact with the last name
"Kitahara"
and adds an e-mail address to his contact card by combining an
update()
with the
$push
operator. The
new
parameter is not set in the following example, so the resulting output still displays
the
old
information:
// Connect to the database
$c = new MongoClient();
// Specify the database and collection in which to work
$collection = $c->contacts->people;
// Specify the search criteria
$criteria = array("Family Name" => "Kitahara");
// Specify the update criteria
$update = array('$push' => array("E-Mail" => "kitahara@mongo.db"));
// Perform a findAndModify()
$collection->findAndModify($criteria,$update);