php-doc-en/reference/mongo/mongowritebatch/add.xml

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

<refentry xml:id="mongowritebatch.add" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>MongoWriteBatch::add</refname>
  <refpurpose>Adds a write operation to a batch</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>bool</type><methodname>MongoWriteBatch::add</methodname>
   <methodparam><type>array</type><parameter>item</parameter></methodparam>
  </methodsynopsis>
  <para>
   Adds a write operation to the batch.
  </para>
  <para>
   If <parameter>$item</parameter> causes the batch to exceed the
   <link xlink:href="url.mongodb.dochub.maxWriteBatchSize">maxWriteBatchSize</link>
   or <link xlink:href="url.mongodb.dochub.maxBsonObjectSize">maxBsonObjectSize</link>
   limits, the driver will internally split the batches into multiple write
   commands upon calling <methodname>MongoWriteBatch::execute</methodname>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>item</parameter></term>
    <listitem>
     <para>
      An array that describes a write operation. The structure of this value
      depends on the batch's operation type.
      <informaltable>
       <thead>
        <row>
         <entry>Batch type</entry>
         <entry>Argument expectation</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry><constant>MongoWriteBatch::COMMAND_INSERT</constant></entry>
         <entry>
          <simpara>The document to add.</simpara>
         </entry>
        </row>
        <row>
         <entry><constant>MongoWriteBatch::COMMAND_UPDATE</constant></entry>
         <entry>
          <para>Raw update operation.</para>
          <para>Required keys are <literal>"q"</literal> and <literal>"u"</literal>, which correspond to the <link linkend="mongocollection.update.criteria"><parameter>$criteria</parameter></link> and <link linkend="mongocollection.update.new_object"><parameter>$new_object</parameter></link> parameters of <function>MongoCollection::update</function>, respectively.</para>
          <para>Optional keys are <literal>"multi"</literal> and <literal>"upsert"</literal>, which correspond to the <link linkend="mongocollection.update.multiple"><literal>"multiple"</literal></link> and <link linkend="mongocollection.update.upsert"><literal>"upsert"</literal></link> options for <function>MongoCollection::update</function>, respectively. If unspecified, both options default to &false;.</para>
         </entry>
        </row>
        <row>
         <entry><constant>MongoWriteBatch::COMMAND_DELETE</constant></entry>
         <entry>
          <para>Raw delete operation.</para>
          <para>Required keys are: <literal>"q"</literal> and <literal>"limit"</literal>, which correspond to the <link linkend="mongocollection.remove.criteria"><parameter>$criteria</parameter></link> parameter and <link linkend="mongocollection.remove.justone"><literal>"justOne"</literal></link> option of <function>MongoCollection::remove</function>, respectively.</para>
          <para>The <literal>"limit"</literal> option is an <type>integer</type>; however, MongoDB only supports <literal>0</literal> (i.e. remove all matching documents) and <literal>1</literal> (i.e. remove at most one matching document) at this time.</para>
         </entry>
        </row>
       </tbody>
      </informaltable>
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns &true; on success and throws an exception on failure.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simplelist>
   <member><classname>Exception</classname> on parameter parsing failures</member>
   <member><classname>Exception</classname> on argument validation errors (e.g. missing keys)</member>
  </simplelist>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example xml:id="mongowritebatch.add.example.insert">
   <title><methodname>MongoWriteBatch::add</methodname> example</title>
   <para>
    Batching up multiple insert operations
   </para>
   <programlisting role="php">
<![CDATA[
<?php
$mc = new MongoClient("localhost");
$collection = $mc->selectCollection("test", "test");


$docs = array();
$docs[] = array("my" => "demo");
$docs[] = array("is" => "working");
$docs[] = array("pretty" => "well");

$batch = new MongoInsertBatch($collection);
foreach($docs as $document) {
    $batch->add($document);
}
$batch->execute(array("w" => 1));
?>
]]>
   </programlisting>
  </example>

  <example xml:id="mongowritebatch.add.example.update">
   <title><methodname>MongoWriteBatch::add</methodname> example</title>
   <para>
    Batching up multiple update operations
   </para>
   <programlisting role="php">
<![CDATA[
<?php
$mc = new MongoClient("localhost");
$collection = $mc->selectCollection("test", "test");


$item1 = array(
    "q" => array("my" => "demo"),
    "u" => array('$set' => array("try" => 1)),
    "multi"  => false, /* default value */
    "upsert" => false, /* default value */
);
$item2 = array(
    "q" => array("is" => "working"),
    "u" => array('$set' => array("try" => 2)),
    "multi" => true,
);
$item3 = array(
    "q" => array("created" => "new-document"),
    "u" => array('$set' => array("try" => 3)),
    "upsert" => true,
);

$batch = new MongoUpdateBatch($collection);
$batch->add($item1);
$batch->add($item2);
$batch->add($item3);
$batch->execute(array("w" => 1));

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

  <example xml:id="mongowritebatch.add.example.delete">
   <title><methodname>MongoWriteBatch::add</methodname> example</title>
   <para>
    Batching up multiple delete operations
   </para>
   <programlisting role="php">
<![CDATA[
<?php
$mc = new MongoClient("localhost");
$collection = $mc->selectCollection("test", "test");


$item1 = array(
    "q" => array("my" => "demo"),
    "limit" => 1,
);
$item2 = array(
    "q" => array("try" => 3),
    "limit" => 1,
);


$batch = new MongoDeleteBatch($collection);
$batch->add($item1);
$batch->add($item2);
$batch->execute(array("w" => 1));
?>
]]>
   </programlisting>
  </example>
 </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
indent-tabs-mode:nil
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
-->