php-doc-en/reference/mongo/mongocursor/slaveokay.xml

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

<!-- $Revision$ -->
<refentry xml:id="mongocursor.slaveokay" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>MongoCursor::slaveOkay</refname>
  <refpurpose>Sets whether this query can be done on a secondary [deprecated]</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>MongoCursor</type><methodname>MongoCursor::slaveOkay</methodname>
   <methodparam choice="opt"><type>bool</type><parameter>okay</parameter><initializer>true</initializer></methodparam>
  </methodsynopsis>
  <warning>
   <para>
    This method is deprecated since version 1.5.0. Instead, please use
    <methodname>MongoCursor::setReadPreference</methodname> and <xref
    linkend="mongo.readpreferences" />.
   </para>
  </warning>
  <para>
   Calling this will make the driver route reads to secondaries if:
   <itemizedlist>
    <listitem>
     <simpara>
      You are using a replica set, and
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      You created a <classname>MongoClient</classname> instance using the option
      <literal>"replicaSet" => "setName"</literal>, and
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      There is a healthy secondary that can be reached by the driver.
     </simpara>
    </listitem>
   </itemizedlist>
   You can check which server was used for this query by calling 
   <function>MongoCursor::info</function> after running the query.  It's
   <literal>server</literal> field will show which server the query was sent to.
  </para>
  <para>
   Note that you should use this function even if you do not use the automatic
   routing to secondaries. If you connect directly to a secondary in a replica
   set, you still need to call this function, which basically tells the database
   that you are aware that you might be getting older data and you're okay with
   that. If you do not call this, you'll get "not master" errors when you try to
   query.
  </para>
  <para>
   This method will override the static class variable 
   <varname>MongoCursor::$slaveOkay</varname>.  It will also override 
   <function>Mongo::setSlaveOkay</function>, 
   <function>MongoDB::setSlaveOkay</function> and
   <function>MongoCollection::setSlaveOkay</function>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term>
      <parameter>okay</parameter>
     </term>
     <listitem>
      <para>
       If it is okay to query the secondary.
      </para>
     </listitem>
    </varlistentry>   
   </variablelist>
  </para>
 </refsect1> 

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;  
  <para>
   Returns this cursor.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Throws <classname>MongoCursorException</classname> if this cursor has started iterating.
  </para>
 </refsect1>

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

MongoCursor::$slaveOkay = false;

// cannot query secondary
$cursor = $collection->find();

// can query secondary
$cursor = $collection->find()->slaveOkay();

MongoCursor::$slaveOkay = true;

// can query secondary
$cursor = $collection->find();

// cannot query secondary
$cursor = $collection->find()->slaveOkay(false);

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

 <refsect1 role="seealso"><!-- {{{ -->
  &reftitle.seealso;
  <simplelist>
   <member><xref linkend="mongo.readpreferences" /></member>
   <member><methodname>MongoCursor::setReadPreference</methodname></member>
   <member><methodname>MongoCursor::getReadPreference</methodname></member>
  </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>1.5.0</entry>
       <entry>
        This method has been deprecated in favour of
        <methodname>MongoCursor::setReadPreference</methodname> and <xref
        linkend="mongo.readpreferences" />.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </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
-->