php-doc-en/reference/mongo/mongodb/execute.xml

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

<!-- $Revision$ -->
<refentry xml:id="mongodb.execute" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>MongoDB::execute</refname>
  <refpurpose>Runs JavaScript code on the database server.</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>array</type><methodname>MongoDB::execute</methodname>
   <methodparam><type>mixed</type><parameter>code</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>args</parameter><initializer>array()</initializer></methodparam>
  </methodsynopsis>
  <para>
   The Mongo database server runs a JavaScript engine.  This method allows you
   to run arbitary JavaScript on the database.  This can be useful if you want
   touch a number of collections lightly, or process some results on the
   database side to reduce the amount that has to be sent to the client.
  </para>
  <para>
   Running JavaScript in the database takes a write lock, meaning it blocks 
   other operations.  Make sure you consider this before running a long script.
  </para>
  <para>
   This is a wrapper for a database command.  This method is basically:
   <programlisting role="php">
<![CDATA[
<?php

public function execute($code, $args) {
    return $this->command(array('$eval' => $code, 'args' => $args));
}

?>
]]>
   </programlisting>
  </para>
  <para>
   MongoDB implies a return statement if you have a single statement on a single
   line. This can cause some unintuitive behavior.  For example, this returns 
   "foo":
  </para>
  <programlisting role="php">
<![CDATA[
<?php

$db->execute('"foo";');

?>
]]>
  </programlisting>
  <para>
   However, these return &null;:
  </para>
  <programlisting role="php">
<![CDATA[
<?php

$db->execute('"bar"; "foo";'); // more than one statement

$db->execute('db.foo.count(
);'); // more than one line

?>
]]>
  </programlisting>
  <para>
   To avoid surprising behavior, it is best not to depend on MongoDB to decide 
   what to return, but to explicitly state a return value. In the examples 
   above, we can change them to:
  </para>
  <programlisting role="php">
<![CDATA[
<?php

$db->execute('"bar"; return "foo";');

$db->execute('return db.foo.count(
);');

?>
]]>
  </programlisting>
  <para>
   Now the first statement will return "foo" and the second statement will 
   return a count of the "foo" collection.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term>
      <parameter>code</parameter>
     </term>
     <listitem>
      <para>
       <classname>MongoCode</classname> or string to execute.
      </para>
     </listitem>
    </varlistentry>   
    <varlistentry>
     <term>
      <parameter>args</parameter>
     </term>
     <listitem>
      <para>
       Arguments to be passed to <literal>code</literal>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the result of the evaluation.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title>Simple <function>MongoDB::execute</function> example</title>
   <programlisting role="php">
<![CDATA[
<?php

$response = $db->execute("function() { return 'Hello, world!'; }");
echo $response['retval'];

?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
Hello, world!
   </screen>
  </example>
  <example>
   <title>Parameter <function>MongoDB::execute</function> example</title>
   <para>
    The optional array of parameters will be passed to the JavaScript function.
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$response = $db->execute("function(greeting, name) { return greeting+', '+name+'!'; }", array("Good bye", "Joe"));
echo $response['retval'];

?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
Good bye, Joe!
   </screen>
  </example>
  <example>
   <title>Scope example</title>
   <para>
    If a <classname>MongoCode</classname> object is used instead of a string for
    the first parameter, a scope can be passed in which the JavaScript will be 
    executed.
   </para>
   <programlisting role="php">
<![CDATA[
<?php

$func = 
    "function(greeting, name) { ".
        "return greeting+', '+name+', says '+greeter;".
    "}";
$scope = array("greeter" => "Fred");

$code = new MongoCode($func, $scope);

$response = $db->execute($code, array("Goodbye", "Joe"));
echo $response['retval'];

?>
]]>
   </programlisting>
   &example.outputs.similar;
   <screen>
Goodbye, Joe, says Fred 
   </screen>
  </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
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
-->