construct.xml

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

<refentry xml:id="mongodb-driver-command.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>MongoDB\Driver\Command::__construct</refname>
  <refpurpose>Create a new Command</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>final</modifier> <modifier>public</modifier> <methodname>MongoDB\Driver\Command::__construct</methodname>
   <methodparam><type class="union"><type>array</type><type>object</type></type><parameter>document</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>commandOptions</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Constructs a new <classname>MongoDB\Driver\Command</classname>, which is an
   immutable value object that represents a database command. The command may
   then be executed with
   <methodname>MongoDB\Driver\Manager::executeCommand</methodname>.
  </para>
  <para>
   The complete command document, which includes the command name and its
   options, should be expressed in the <parameter>document</parameter>
   parameter. The <parameter>commandOptions</parameter> parameter is only used
   to specify options related to the execution of the command and the resulting
   <classname>MongoDB\Driver\Cursor</classname>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>document</parameter></term>
    <listitem>
     <para>
      The complete command document, which will be sent to the server.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>commandOptions</parameter></term>
    <listitem>
     <note>
      <simpara>
       Do not use this parameter to specify options described in the command's
       reference in the MongoDB manual. This parameter should only be used for
       the options explicitly listed below.
      </simpara>
     </note>
     <para>
      <table>
       <title>commandOptions</title>
       <tgroup cols="3">
        <thead>
         <row>
          <entry>Option</entry>
          <entry>Type</entry>
          <entry>Description</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry>maxAwaitTimeMS</entry>
          <entry><type>int</type></entry>
          <entry>
           <para>
            Positive integer denoting the time limit in milliseconds for the
            server to block a getMore operation if no data is available. This
            option should only be used in conjunction with commands that return
            a tailable cursor (e.g. <link
            xlink:href="&url.mongodb.docs;changeStreams/">Change
            Streams</link>).
           </para>
          </entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simplelist>
   &mongodb.throws.argumentparsing;
  </simplelist>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>PECL mongodb 1.4.0</entry>
       <entry>
        <para>
         Added a second <parameter>commandOptions</parameter> argument, which supports
         the <literal>"maxAwaitTimeMS"</literal> option.
        </para>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><function>MongoDB\Driver\Command::__construct</function> example</title>
   <programlisting role="php">
<![CDATA[
<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
$command = new MongoDB\Driver\Command(array("buildinfo" => 1));

try {
    $cursor = $manager->executeCommand("admin", $command);
    $response = $cursor->toArray()[0];
} catch(MongoDB\Driver\Exception $e) {
    echo $e->getMessage(), "\n";
    exit;
}
var_dump($response);

?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
<![CDATA[

array(13) {
  ["version"]=>
  string(14) "2.8.0-rc2-pre-"
  ["gitVersion"]=>
  string(62) "b743d7158f7642f4da6b7eac8320374b3b88dc2e modules: subscription"
  ["OpenSSLVersion"]=>
  string(25) "OpenSSL 1.0.1f 6 Jan 2014"
  ["sysInfo"]=>
  string(104) "Linux infant 3.16.0-24-generic #32-Ubuntu SMP Tue Oct 28 13:07:32 UTC 2014 x86_64 BOOST_LIB_VERSION=1_49"
  ["loaderFlags"]=>
  string(91) "-fPIC -pthread -Wl,-z,now -rdynamic -Wl,-Bsymbolic-functions -Wl,-z,relro -Wl,-z,now -Wl,-E"
  ["compilerFlags"]=>
  string(301) "-Wnon-virtual-dtor -Woverloaded-virtual -std=c++11 -fPIC -fno-strict-aliasing -ggdb -pthread -Wall -Wsign-compare -Wno-unknown-pragmas -Winvalid-pch -pipe -Werror -O3 -Wno-unused-local-typedefs -Wno-unused-function -Wno-deprecated-declarations -Wno-unused-but-set-variable -fno-builtin-memcmp -std=c99"
  ["allocator"]=>
  string(8) "tcmalloc"
  ["versionArray"]=>
  array(4) {
    [0]=>
    int(2)
    [1]=>
    int(8)
    [2]=>
    int(0)
    [3]=>
    int(-8)
  }
  ["javascriptEngine"]=>
  string(2) "V8"
  ["bits"]=>
  int(64)
  ["debug"]=>
  bool(false)
  ["maxBsonObjectSize"]=>
  int(16777216)
  ["ok"]=>
  float(1)
}

]]>
   </screen>
  </example>

  <example>
   <title><function>MongoDB\Driver\Command::__construct</function> example</title>
   <para>
    Commands can accept options as well, as part of the normal structure that
    you create to send to the server. For example, the
    <literal>maxTimeMS</literal> option can be passed with most commands to
    restrict the amount of time a specific command can run for on the server.
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
$command = new MongoDB\Driver\Command(
    array(
        "distinct" => "beer",
        "key" => "beer_name",
        "maxTimeMS" => 10,
    )
);

try {
    $cursor = $manager->executeCommand("beerdb", $command);
    $response = $cursor->toArray()[0];
} catch(MongoDB\Driver\Exception\Exception $e) {
    echo $e->getMessage(), "\n";
    exit;
}
var_dump($response);

?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
    operation exceeded time limit
   </screen>
  </example>
 </refsect1>


 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><methodname>MongoDB\Driver\Manager::executeCommand</methodname></member>
   <member><classname>MongoDB\Driver\Cursor</classname></member>
  </simplelist>
 </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
-->