<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision: 331653 $ -->
<refentry xml:id="mongocollection.update" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>MongoCollection::update</refname>
  <refpurpose>Update records based on a given criteria</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>bool|array</type><methodname>MongoCollection::update</methodname>
   <methodparam><type>array</type><parameter>criteria</parameter></methodparam>
   <methodparam><type>array</type><parameter>new_object</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
  </methodsynopsis>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term>
      <parameter>criteria</parameter>
     </term>
     <listitem>
      <para>
       Description of the objects to update.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <parameter>new_object</parameter>
     </term>
     <listitem>
      <para>
       The object with which to update the matching records.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      <parameter>options</parameter>
     </term>
     <listitem>
      <para>
       This parameter is an associative array of the form 
       <literal>array("optionname" => &lt;boolean&gt;, ...)</literal>. Currently 
       supported options are: 
       <itemizedlist>
        <listitem>
         <para>
          <literal>"upsert"</literal>
         </para>
         <para>
          If no document matches <parameter>$criteria</parameter>, a new
          document will be inserted.
         </para>
         <para>
          If a new document would be inserted and
          <parameter>$new_object</parameter> contains atomic modifiers
          (i.e. <literal>$</literal> operators), those operations will be
          applied to the <parameter>$criteria</parameter> parameter to create
          the new document. If <parameter>$new_object</parameter> does not
          contain atomic modifiers, it will be used as-is for the inserted
          document. See the upsert examples below for more information.
         </para>
        </listitem>
        <listitem>
         <para>
          <literal>"multiple"</literal>
         </para>
         <para>
          All documents matching $criteria will be updated.  
          <function>MongoCollection::update</function> has exactly the opposite 
          behavior of <function>MongoCollection::remove</function>: it updates 
          one document by default, not all matching documents.  <emphasis>It is 
          recommended that you always specify whether you want to update 
           multiple documents or a single document</emphasis>, as the database 
          may change its default behavior at some point in the future.
         </para>
        </listitem>
        &mongo.writes.parameters.fsync;
        &mongo.writes.parameters.journal;
<!--
        &mongo.writes.parameters.sockettimeoutms;
-->
        &mongo.writes.parameters.writeconcern;
        &mongo.writes.parameters.writeconcerntimeout;
        &mongo.writes.parameters.safe;
        &mongo.writes.parameters.timeout;
       </itemizedlist>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns an array containing the status of the update if the
   <literal>"w"</literal> option is set. Otherwise, returns &true;.
  </para>
  <para>
   Fields in the status array are described in the documentation for
   <function>MongoCollection::insert</function>.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  &mongo.errors.exceptions.writeconcern;
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
<!--
      <row>
       <entry>1.5.0</entry>
       <entry>Renamed the <literal>"timeout"</literal> option to
       <literal>"socketTimeoutMS"</literal>.</entry>
      </row>
-->
      <row>
       <entry>1.3.0</entry>
       <entry>
        The <parameter>options</parameter> parameter no longer accepts a boolean
        to signify an upsert. Instead, this now has to be done with
        <literal>array('upsert' => true)</literal>.
       </entry>
      </row>
      <row>
       <entry>1.2.11</entry>
       <entry>
        Emits <constant>E_DEPRECATED</constant> when
        <parameter>options</parameter> is <type>scalar</type>.
       </entry>
      </row>
      <row>
       <entry>1.2.0</entry>
       <entry>Added <literal>"timeout"</literal> option.</entry>
      </row>
      <row>
       <entry>1.0.11</entry>
       <entry>
        Disconnects on "not master" errors if <literal>"safe"</literal> is set.
       </entry>
      </row>
      <row>
       <entry>1.0.9</entry>
       <entry>
        <para>
         Added ability to pass integers to the <literal>"safe"</literal> option,
         which previously only accepted booleans.
        </para>
        <para>
         Added <literal>"fsync"</literal> option.
        </para>
        <para>
         The return type was changed to be an array containing error information
         if the <literal>"safe"</literal> option is used. Otherwise, a boolean
         is returned as before.
        </para>
       </entry>
      </row>
      <row>
       <entry>1.0.5</entry>
       <entry>Added <literal>"safe"</literal> option.</entry>
      </row>
      <row>
       <entry>1.0.1</entry>
       <entry>
        Changed <parameter>options</parameter> parameter from boolean to array.
        Pre-1.0.1, the second parameter was an optional boolean value specifying
        an upsert.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><function>MongoCollection::update</function></title>
   <para>
    Adding an address field to a document.
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$c->insert(array("firstname" => "Bob", "lastname" => "Jones" ));
$newdata = array('$set' => array("address" => "1 Smith Lane"));
$c->update(array("firstname" => "Bob"), $newdata);

var_dump($c->findOne(array("firstname" => "Bob")));

?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
array(4) {
  ["_id"]=>
  object(MongoId)#6 (0) {
  }
  ["firstname"]=>
  string(3) "Bob"
  ["lastname"]=>
  string(5) "Jones"
  ["address"]=>
  string(12) "1 Smith Lane"
}
]]>
   </screen>
  </example>
  <example>
   <title><function>MongoCollection::update</function> upsert examples</title>
   <para>
    Upserts can simplify code, as a single line can create the document if it
    does not exist (based on <parameter>$criteria</parameter>), or update an
    existing document if it matches.
   </para>
   <para>
    In the following example, <parameter>$new_object</parameter> contains an
    atomic modifier. Since the collection is empty and upsert must insert a new
    document, it will apply those operations to the
    <parameter>$criteria</parameter> parameter in order to create the document.
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$c->drop();
$c->update(
    array("uri" => "/summer_pics"),
    array('$inc' => array("page hits" => 1)),
    array("upsert" => true)
);
var_dump($c->findOne());

?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
array(3) {
  ["_id"]=>
  object(MongoId)#9 (0) {
  }
  ["uri"]=>
  string(12) "/summer_pics"
  ["page hits"]=>
  int(1)
}
]]>
   </screen>
   <para>
    If <parameter>$new_object</parameter> does not contain atomic modifiers
    (i.e. <literal>$</literal> operators), upsert will use
    <parameter>$new_object</parameter> as-is for the new document. This matches
    the behavior of a normal update, where not using atomic modifiers causes the
    document to be overwritten.
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$c->drop();
$c->update(
    array("name" => "joe"),
    array("username" => "joe312", "createdAt" => new MongoDate()), 
    array("upsert" => true)
);
var_dump($c->findOne());

?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[
array(3) {
  ["_id"]=>
  object(MongoId)#10 (0) {
  }
  ["username"]=>
  string(6) "joe312"
  ["createdAt"]=>
  object(MongoDate)#4 (0) {
  }
}
]]>
   </screen>
  </example>
  <example>
   <title><function>MongoCollection::update</function> multiple example</title>
   <para>
    By default, <function>MongoCollection::update</function> will only update
    the first document matching <parameter>$criteria</parameter> that it
    finds. Using the "multiple" option can override this behavior, if needed.
   </para>
   <para>
    This example adds a "gift" field to every person whose birthday is in the
    next day.
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$today = array('$gt' => new MongoDate(), '$lt' => new MongoDate(strtotime("+1 day")));
$people->update(
    array("birthday" => $today),
    array('$set' => array('gift' => $surprise)),
    array("multiple" => true)
);

?>
]]>
   </programlisting>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   The <link linkend="mongo.updates">PHP documentation on updates</link> and the
   <link xlink:href="&url.mongodb.dochub.update;">MongoDB core docs</link>.
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->