sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-15 08:28:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Remove legacy MongoDb driver docs

Browse source
This commit is contained in:
George Peter Banyard 2021-05-24 19:35:23 +01:00
parent 1d00d0ad21
commit 1fc853737a
No known key found for this signature in database
GPG key ID: D49A095D7329F6DC
283 changed files with 5 additions and 36443 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
appendices/extensions.xml
View file

@ -81,7 +81,6 @@
<listitem><simpara><xref linkend="book.memcached"/></simpara></listitem>
<listitem><simpara><xref linkend="book.mhash"/></simpara></listitem>
<listitem><simpara><xref linkend="book.misc"/></simpara></listitem>
<listitem><simpara><xref linkend="book.mongo"/></simpara></listitem>
<listitem><simpara><xref linkend="book.bson"/></simpara></listitem>
<listitem><simpara><xref linkend="book.mongodb"/></simpara></listitem>
<listitem><simpara><xref linkend="book.mqseries"/></simpara></listitem>
@ -331,7 +330,6 @@
<listitem><para><xref linkend="book.mailparse"/></para></listitem>
<listitem><para><xref linkend="book.memcache"/></para></listitem>
<listitem><para><xref linkend="book.memcached"/></para></listitem>
<listitem><para><xref linkend="book.mongo"/></para></listitem>
<listitem><para><xref linkend="book.mqseries"/></para></listitem>
<listitem><para><xref linkend="book.mysqlnd-memcache"/></para></listitem>
<listitem><para><xref linkend="book.mysqlnd-ms"/></para></listitem>

1
appendices/ini.list.xml
View file

@ -554,7 +554,6 @@
<entry>PHP_INI_ALL</entry>
<entry></entry>
</row>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('mongo.configuration.list')/*)"><xi:fallback/></xi:include>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('mysql.configuration.list')/*)"><xi:fallback/></xi:include>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('mysqli.configuration.list')/*)"><xi:fallback/></xi:include>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('mysqlnd.config.options.list')/*)"><xi:fallback/></xi:include>

1
language/context.xml
View file

@ -20,7 +20,6 @@
&language.context.ssl;
&language.context.curl;
&language.context.phar;
&language.context.mongodb;
&language.context.parameters;
&language.context.zip;

158
language/context/mongodb.xml
View file

@ -1,158 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="context.mongodb" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" role="noversion">
<refnamediv>
<refname>MongoDB context options</refname>
<refpurpose>MongoDB context option listing</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<para>
Context options for <literal>mongodb://</literal> transports.
</para>
</refsect1>
<refsect1 role="options"><!-- {{{ -->
&reftitle.options;
<para>
<variablelist>
<varlistentry xml:id="context.mongodb.log-cmd-insert">
<term>
<parameter>log_cmd_insert</parameter>
<type>callable</type>
</term>
<listitem>
<para>
A callback function called when inserting a document, see <function>log_cmd_insert</function>.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.mongodb.log-cmd-delete">
<term>
<parameter>log_cmd_delete</parameter>
<type>callable</type>
</term>
<listitem>
<para>
A callback function called when deleting a document, see <function>log_cmd_delete</function>.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.mongodb.log-cmd-update">
<term>
<parameter>log_cmd_update</parameter>
<type>callable</type>
</term>
<listitem>
<para>
A callback function called when updating a document, see <function>log_cmd_update</function>.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.mongodb.log-write-batch">
<term>
<parameter>log_write_batch</parameter>
<type>callable</type>
</term>
<listitem>
<para>
A callback function called when executing a Write Batch, see <function>log_write_batch</function>.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.mongodb.log-reply">
<term>
<parameter>log_reply</parameter>
<type>callable</type>
</term>
<listitem>
<para>
A callback function called when reading a reply from MongoDB, see <function>log_reply</function>.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.mongodb.log-getmore">
<term>
<parameter>log_getmore</parameter>
<type>callable</type>
</term>
<listitem>
<para>
A callback function called when retrieving more results from a MongoDB cursor, see <function>log_getmore</function>.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.mongodb.log-killcursor">
<term>
<parameter>log_killcursor</parameter>
<type>callable</type>
</term>
<listitem>
<para>
A callback function called executing a killcursor opcode, see <function>log_killcursor</function>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</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/mongo 1.5.0</entry>
<entry>
Added Write API Context options
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1><!-- }}} -->
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><xref linkend="context.socket" /></member>
<member><xref linkend="context.ssl" /></member>
</simplelist>
</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
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
-->

13
reference/mongo/batch.xml
View file

@ -1,13 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<part xml:id="mongo.batch" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Batch Classes</title>
&reference.mongo.mongowritebatch;
&reference.mongo.mongoinsertbatch;
&reference.mongo.mongoupdatebatch;
&reference.mongo.mongodeletebatch;
</part>

43
reference/mongo/book.xml
View file

@ -1,43 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<book xml:id="book.mongo" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>MongoDB driver (legacy)</title>
<titleabbrev>Mongo</titleabbrev>
&reference.mongo.setup;
&reference.mongo.constants;
&reference.mongo.manual;
&reference.mongo.core;
&reference.mongo.types;
&reference.mongo.gridfs;
&reference.mongo.batch;
&reference.mongo.misc;
&reference.mongo.reference;
&reference.mongo.exceptions;
&reference.mongo.changelog;
</book>
<!-- 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
-->

125
reference/mongo/changelog.xml
View file

@ -1,125 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<appendix xmlns="http://docbook.org/ns/docbook" xml:id="changelog.mongo" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>&ChangelogListingTitle;</title>
<para>&ChangelogListingDescription;</para>
<simplesect xml:id="changelog.mongo.1.5">
<title>MongoDB PHP Driver 1.5.0</title>
<para>
It supports all new features for MongoDB 2.6, including:
<simplelist>
<member>Aggregate can now return a cursor</member>
<member>Aggregation pipelines can now be explained</member>
<member>Possible to set maxTimeMS for commands and queries</member>
<member>Transparent support for the new command-based MongoDB write API</member>
<member>New MongoWriteBatch classes (using the new MongoDB write API)</member>
<member>Support for MongoDB Enterprise features (e.g. Kerberos, LDAP, X509)</member>
<member>Option to tune acceptable server latency for secondary reads (secondaryAcceptableLatencyMS)</member>
</simplelist>
</para>
<para>
With this release, some driver functionality which was previously
documented as deprecated will now formally raise deprecation notices. This
includes:
<simplelist>
<member>Instantiating the Mongo class</member>
<member>Calling MongoCursor::slaveOkay()</member>
<member>"wtimeout" and "safe" options for MongoCollection write operations</member>
<member>Manipulating public properties on core classes (such as $collection->w)</member>
</simplelist>
</para>
<note>
<para>
No previously deprecated features have been removed.
</para>
</note>
<para>
Changes in behaviour:
<simplelist>
<member>Setting the mongo.native_long INI setting now raises an error on 32-bit
platforms, and now defaults to true for 64-bit platforms.</member>
</simplelist>
</para>
</simplesect>
<simplesect xml:id="changelog.mongo.1.4">
<title>MongoDB PHP Driver 1.4.0</title>
<para>
The 1.4 series introduced fundemental changes in how connections are created to the MongoDB servers.
The driver now utilizes PHP native streams, so all normal PHP stream options apply.
Furthermore, an experimental Stream Context Support was added.
</para>
<para>
The 1.4.x series also added support for MongoDB 2.4.x.
</para>
<para>
The most important improvements however deal with the handling of replica sets,
especially nodes that timeout and nodes that are unreachable for various
reasons. Besides the improvements to replica set handling, this release
addresses issues with read preferences through mongos nodes. It also
adds support for SSL enabled connections as well as journal and fsync
connection string options.
</para>
</simplesect>
<simplesect xml:id="changelog.mongo.1.3">
<title>MongoDB PHP Driver 1.3.0</title>
<para>
The 1.3 series introduced several major changes to the extension such as
completely rewritten <link linkend="mongo.connecting">connection
handling</link> (and removal of the pooling mechanism), support for
<link linkend="mongo.readpreferences">ReadPreferences</link> and change the
default <link linkend="mongo.writes">WriteConcerns</link> to be
<emphasis>acknowledged</emphasis> by introducing a new class
<link linkend="class.mongoclient">MongoClient</link> which serves as a
replacement class for the now deprecated <classname>Mongo</classname> class.
</para>
<para>
The driver now also supports connecting to multiple mongos instances (the
Mongo Shard router) for loadbalancing.
</para>
<para>
Other enhancements include improved logging for easier connection handling
debugging with <classname>MongoLog</classname> and support for the
<link xlink:href="&url.mongodb.docs.aggregation;">Aggregation Framework</link>
via the <methodname>MongoCollection::aggregate</methodname> method.
</para>
</simplesect>
<simplesect>
<title>Changes to existing methods</title>
<para>
Following is a list of all improvements to existing methods since
their inception.
</para>
<?phpdoc generate-changelog-for="mongo.batch mongo.connecting mongo.context mongo.core mongo.exceptions mongo.gridfs mongo.manual mongo.manual.intro mongo.miscellaneous class.mongo class.mongobindata class.mongoclient class.mongocode class.mongocollection class.mongocommandcursor class.mongoconnectionexception class.mongocursor class.mongocursorinterface class.mongocursorexception class.mongocursortimeoutexception class.mongodate class.mongodb class.mongodbref class.mongodeletebatch class.mongoduplicatekeyexception class.mongoexception class.mongoexecutiontimeoutexception class.mongogridfs class.mongogridfscursor class.mongogridfsexception class.mongogridfsfile class.mongoid class.mongoinsertbatch class.mongoint32 class.mongoint64 class.mongolog class.mongomaxkey class.mongominkey class.mongopool class.mongoprotocolexception class.mongoregex class.mongoresultexception class.mongotimestamp class.mongoupdatebatch class.mongowritebatch class.mongowriteconcernexception mongo.queries mongo.readpreferences ref.mongo mongo.security mongo.setup mongo.sqltomongo mongo.testing mongo.trouble mongo.tutorial mongo.types mongo.updates mongo.writeconcerns mongo.writes" ?>
</simplesect>
</appendix>
<!-- 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
-->

302
reference/mongo/configure.xml
View file

@ -1,302 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<section xml:id="mongo.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.install;
<warning>
&mongo.deprecated.note;
</warning>
<para>
The MongoDB PHP driver should work on nearly any system: Windows, macOS,
Unix, and Linux; little- and big-endian machines; 32- and 64-bit machines; PHP
5.3 through 5.6 (versions prior to 1.6 also support PHP 5.2).
</para>
<para>
&pecl.moved;
</para>
<simplelist>
<member>
<xref linkend="mongo.installation.manual" />
</member>
<member>
<xref linkend="mongo.installation.nix" />
</member>
<member>
<xref linkend="mongo.installation.windows" />
</member>
<member>
<xref linkend="mongo.installation.osx" />
</member>
<member>
<xref linkend="mongo.installation.gentoo" />
</member>
<member>
<xref linkend="mongo.installation.fedora" />
</member>
<member>
<xref linkend="mongo.installation.thirdparty" />
</member>
</simplelist>
<section xml:id="mongo.installation.manual">
<title>Manual Installation</title>
<para>For driver developers and people interested in the latest bugfixes, you
can compile the driver from the latest source code on
<link xlink:href="&url.mongodb.github;">Github</link>.
Go to Github and click the "download" button. Then run:
<programlisting role="shell">
<![CDATA[
$ tar zxvf mongo-php-driver-legacy-<commit_id>.tar.gz
$ cd mongo-php-driver-legacy-<commit_id>
$ phpize
$ ./configure
$ make all
$ sudo make install
]]>
</programlisting>
</para>
<para>
Make the following changes to &php.ini;:
</para>
<itemizedlist>
<listitem>
<para>
Make sure the <emphasis>extension_dir</emphasis> variable is pointing to
the directory containing <emphasis>mongo.so</emphasis>. The build will display where
it is installing the PHP driver with output that looks something like:
<programlisting role="txt">
<![CDATA[
Installing '/usr/lib/php/extensions/no-debug-non-zts-20060613/mongo.so'
]]>
</programlisting>
Make sure that it is the same as the PHP extension directory by running:
<programlisting role="shell">
<![CDATA[
$ php -i | grep extension_dir
extension_dir => /usr/lib/php/extensions/no-debug-non-zts-20060613 =>
/usr/lib/php/extensions/no-debug-non-zts-20060613
]]>
</programlisting>
If it's not, change the <emphasis>extension_dir</emphasis> in &php.ini; or
move <emphasis>mongo.so</emphasis>.
</para>
</listitem>
<listitem>
<para>
To load the extension on PHP startup, add a line:
<programlisting role="ini">
<![CDATA[
extension=mongo.so
]]>
</programlisting>
</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="mongo.installation.nix">
<title>Installing on *NIX</title>
<para>
Run:
<programlisting role="shell">
<![CDATA[
$ sudo pecl install mongo
]]>
</programlisting>
</para>
<para>
Add the following line to your &php.ini; file:
<programlisting role="ini">
<![CDATA[
extension=mongo.so
]]>
</programlisting>
</para>
<para>
If pecl runs out of memory while installing, make sure memory_limit in
&php.ini; is set to at least 128MB.
</para>
</section>
<section xml:id="mongo.installation.windows">
<title>Installing on Windows</title>
<para>
Precompiled binaries for each release are available from
<link xlink:href="&url.pecl.package;mongo">PECL</link> for a variety
of combinations of versions, thread safety, and VC libraries. Unzip the
archive and put php_mongo.dll in your PHP extension directory ("ext" by
default).
</para>
<para>
Add the following line to your &php.ini; file:
<programlisting role="ini">
<![CDATA[
extension=php_mongo.dll
]]>
</programlisting>
</para>
<note>
<title>Additional DLL dependencies for Windows Users</title>
<para>
&ext.windows.path.dll;
<filename>libsasl.dll</filename>
</para>
</note>
</section>
<section xml:id="mongo.installation.osx">
<title>macOS</title>
<para>
In most cases installing from PECL is the easiest way:
<programlisting role="shell">
<![CDATA[
$ sudo pecl install mongo
]]>
</programlisting>
</para>
<para>
If your system has multiple version of PHP installed (e.g. macOS default,
Homebrew, <link xlink:href="&url.xampp;">XAMPP</link>), note that each
version of PHP has its own <link linkend="install.pecl">pecl</link>
command and &php.ini; file.
</para>
<note>
<title>Xcode dependency for compiling on macOS</title>
<para>
Compiling the driver on macOS will require Xcode developer tools, which may
be installed with <code>xcode-select --install</code>. If that command is
not available, you may first need to install the
<link xlink:href="&url.apple.clt;">Command Line Tools</link> package.
</para>
</note>
</section>
<section xml:id="mongo.installation.gentoo">
<title>Gentoo</title>
<para>
Gentoo has a package for the PHP PECL driver called dev-php/pecl-mongo, which can be
installed with:
</para>
<programlisting role="shell">
<![CDATA[
$ sudo emerge -va dev-php/pecl-mongo
]]>
</programlisting>
<para>
If you use PECL, you may get an error that libtool is the wrong version.
Compiling from source you'll need to run aclocal and autoconf.
</para>
<programlisting role="shell">
<![CDATA[
$ phpize
$ aclocal
$ autoconf
$ ./configure
$ make
$ sudo make install
]]>
</programlisting>
</section>
<section xml:id="mongo.installation.fedora">
<title>Red Hat</title>
<para>
This includes Fedora and CentOS.
</para>
<para>
The default Apache settings on these systems do not let requests make
network connections, meaning that the driver will get "Permission denied"
errors when it tries to connect to the database. If you run into this, try
running:
<programlisting role="shell">
<![CDATA[
$ /usr/sbin/setsebool -P httpd_can_network_connect 1
]]>
</programlisting>
Then restart Apache. (This issue has also occurred with SELinux.)
</para>
</section>
<section xml:id="mongo.installation.thirdparty">
<title>Third-Party Installation Instructions</title>
<para>
A number of people have created excellent tutorials on installing the PHP
driver.
</para>
<itemizedlist>
<listitem>
<para>
<link xlink:href="&url.mongodb.install.osx.homebrew;">
(Re)installing PHP on macOS
</link>
</para>
<para>
This article by Justin Hileman details the process of installing PHP and
additional extensions with Homebrew on macOS. This complements the earlier
instructions on this page for installing the driver with Homebrew.
</para>
</listitem>
<listitem>
<para>
<link xlink:href="&url.mongodb.install.ubuntu.9.10.video;">
PHP 5.3.1 with Xdebug, MongoDB and Lithium on Ubuntu 9.10 / Apache 2.2
</link>
</para>
<para>This screencast by Jon Adams demonstrates how to quickly get up and
running with PHP 5.3.1, Xdebug, and MongoDB on Ubuntu 9.10 with Apache.
</para>
</listitem>
</itemizedlist>
</section>
</section>
<!-- 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
-->

775
reference/mongo/connecting.xml
View file

@ -1,775 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter xml:id="mongo.connecting" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Connecting</title>
<para>
Connecting to MongoDB can be as easy as <literal>new MongoClient</literal>,
but there are many additional options and configurations. The documentation
for <function>MongoClient::__construct</function> covers all of the API
options, but this page gives some more details and advice for practical use
cases.
</para>
<section xml:id="mongo.connecting.ssl">
<title>Connecting over SSL</title>
<para>
The driver supports connecting to <link xlink:href="&url.mongodb.docs.configure-ssl;">MongoDB over SSL</link>
and can optionally use <link linkend="context.ssl">SSL Stream Context</link> options to provide more details,
such as verifying certificates against specific certificate chain, or authenticate to
<link xlink:href="&url.mongodb.docs.configure-x509;">MongoDB using X509 certificates</link>.
</para>
<example xml:id="mongo.connecting.context.ssl">
<title>Connect to MongoDB Instance with SSL Encryption</title>
<programlisting role="php">
<![CDATA[
<?php
$mc = new MongoClient("mongodb://server1", array("ssl" => true));
?>
]]>
</programlisting>
</example>
<example xml:id="mongo.connecting.context.ssl.verify">
<title>Connect to MongoDB Instance with SSL Encryption, verifying it is who we think it is</title>
<programlisting role="php">
<![CDATA[
<?php
$SSL_DIR = "/vagrant/certs";
$SSL_FILE = "CA_Root_Certificate.pem";
$ctx = stream_context_create(array(
"ssl" => array(
/* Certificate Authority the remote server certificate must be signed by */
"cafile" => $SSL_DIR . "/" . $SSL_FILE,
/* Disable self signed certificates */
"allow_self_signed" => false,
/* Verify the peer certificate against our provided Certificate Authority root certificate */
"verify_peer" => true, /* Default to false pre PHP 5.6 */
/* Verify the peer name (e.g. hostname validation) */
/* Will use the hostname used to connec to the node */
"verify_peer_name" => true,
/* Verify the server certificate has not expired */
"verify_expiry" => true, /* Only available in the MongoDB PHP Driver */
),
);
$mc = new MongoClient(
"mongodb://server1",
array("ssl" => true),
array("context" => $ctx)
);
?>
]]>
</programlisting>
<note>
<para>
The <literal>"verify_peer_name"</literal> is new in PHP 5.6.0. The
MongoDB driver as of 1.6.5 however has backported this feature into the
driver itself, so it works with PHP 5.3 and 5.4 too
</para>
</note>
</example>
<example xml:id="mongo.connecting.context.ssl.certificate">
<title>Connect to MongoDB Instance that Requires Client Certificates</title>
<programlisting role="php">
<![CDATA[
<?php
$SSL_DIR = "/vagrant/certs";
$SSL_FILE = "CA_Root_Certificate.pem";
$MYCERT = "/vagrant/certs/ca-signed-client.pem";
$ctx = stream_context_create(array(
"ssl" => array(
"local_cert" => $MYCERT,
/* If the certificate we are providing was passphrase encoded, we need to set it here */
"passphrase" => "My Passphrase for the local_cert",
/* Optionally verify the server is who he says he is */
"cafile" => $SSL_DIR . "/" . $SSL_FILE,
"allow_self_signed" => false,
"verify_peer" => true,
"verify_peer_name" => true,
"verify_expiry" => true,
),
));
$mc = new MongoClient(
"mongodb://server1/?ssl=true",
array(),
array("context" => $ctx)
);
?>
]]>
</programlisting>
</example>
<example xml:id="mongo.connecting.authenticate.ssl.x509">
<title>Authenticating with X.509 certificates</title>
<para>
The username is the <literal>certificate subject</literal> from the X509, which can be extracted like this:
</para>
<programlisting role="shell">
<![CDATA[
openssl x509 -in /vagrant/certs/ca-signed-client.pem -inform PEM -subject -nameopt RFC2253
]]>
</programlisting>
<programlisting role="php">
<![CDATA[
<?php
$ctx = stream_context_create( array(
"ssl" => array(
"local_cert" => "/vagrant/certs/ca-signed-client.pem",
)
) );
$mc = new MongoClient(
'mongodb://username@server1/?authSource=$external&authMechanism=MONGODB-X509&ssl=true',
array(),
array("context" => $ctx)
);
?>
]]>
</programlisting>
<para>
Where <literal>username</literal> is the certificate subject.
</para>
</example>
<simplesect role="changelog">
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>1.5.0</entry>
<entry>
Added support for X509 authentication.
</entry>
</row>
<row>
<entry>1.4.0</entry>
<entry>
Added support for connecting to SSL enabled MongoDB.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</simplesect>
</section>
<section xml:id="mongo.connecting.auth">
<title>Authentication</title>
<para>
If MongoDB is started with the <literal>--auth</literal> or
<literal>--keyFile</literal> options, you must authenticate before you can do
any operations with the driver. You may authenticate a connection by
specifying the username and password in either the connection URI or the
<literal>"username"</literal> and <literal>"password"</literal> options for
<function>MongoClient::__construct</function>.
</para>
<example xml:id="mongo.connecting.auth-example">
<title>Authenticating against the "admin" database</title>
<programlisting role="php">
<![CDATA[
<?php
// Specifying the username and password in the connection URI (preferred)
$m = new MongoClient("mongodb://${username}:${password}@localhost");
// Specifying the username and password via the options array (alternative)
$m = new MongoClient("mongodb://localhost", array("username" => $username, "password" => $password));
?>
]]>
</programlisting>
</example>
<para>
By default, the driver will authenticate against the <literal>admin</literal>
database. You may authenticate against a different database by specifying it
in either the connection URI or the <literal>"db"</literal> option for
<function>MongoClient::__construct</function>.
</para>
<example xml:id="mongo.connecting.auth-db-example">
<title>Authenticating against normal databases</title>
<programlisting role="php">
<![CDATA[
<?php
// Specifying the authentication database in the connection URI (preferred)
$m = new MongoClient("mongodb://${username}:${password}@localhost/myDatabase");
// Specifying the authentication database via the options array (alternative)
$m = new MongoClient("mongodb://${username}:${password}@localhost", array("db" => "myDatabase"));
?>
]]>
</programlisting>
</example>
<para>
If your connection is dropped, the driver will automatically attempt to
reconnect and reauthenticate you.
</para>
</section>
<section xml:id="mongo.connecting.rs">
<title>Replica Sets</title>
<para>
To connect to a replica set, specify one or more members of the set and use
the <literal>"replicaSet"</literal> option. Multiple servers may be delimited
by a comma.
</para>
<example xml:id="mongo.connecting.rs-example">
<title>ReplicaSet seed list</title>
<programlisting role="php">
<![CDATA[
<?php
// Using multiple servers as the seed list (preferred)
$m = new MongoClient("mongodb://rs1.example.com:27017,rs2.example.com:27017/?replicaSet=myReplSetName");
// Using one server as the seed list
$m = new MongoClient("mongodb://rs1.example.com:27017", array("replicaSet" => "myReplSetName"));
// Using multiple servers as the seed list
$m = new MongoClient("mongodb://rs1.example.com:27017,rs2.example.com:27017", array("replicaSet" => "myReplSetName"));
?>
]]>
</programlisting>
</example>
<para>
The PHP driver will query the database server(s) listed to determine the
primary. So long as it can connect to at least one host listed and find a
primary, the connection will succeed. If it cannot make a connection to any
servers listed or cannot find a primary, a
<classname>MongoConnectionException</classname> will be thrown.
</para>
<tip>
<para>
You should always provide a seed list with more than one member of the
ReplicaSet. For highest availability you should seed with at least one
server from each of your datacenters.
</para>
</tip>
<warning>
<para>
The host names that you specify in the seed list <emphasis>must</emphasis>
match the host names in the replica set configuration. This is because the
driver only uses the host names in the replica set configuration to create
the hash for its persistent connections.
</para>
<para>
For example, if an IP address is used in the seed list and the replica set
is configured with host names, the driver will discard any seed list
connection(s) that differ from the canonical host names reported by the
replica set. Effectively, these non-canonical seed list connections will be
recreated on each request, greatly reducing the benefit of using persistent
connections.
</para>
</warning>
<warning>
<para>
The driver does <emphasis>not</emphasis> support connecting to different
replica sets with the same name. This extends beyond one script so make
sure to have separate names for each of your replica sets. That also means
that you can <emphasis>not</emphasis> do this:
</para>
<example xml:id="mongo.connecting.rs-example-wrong-replset">
<title>Wrong replica set name duplication</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient("mongodb://devserver1,devserver2,devserver3/?replicaSet=repset");
$m = new MongoClient("mongodb://prodserver1,prodserver2,prodserver3/?replicaSet=repset");
?>
]]>
</programlisting>
</example>
<para>
Instead, you need to have two different names for your replica sets:
</para>
<example xml:id="mongo.connecting.rs-example-correct-replset">
<title>Correct use of two replica set names</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient("mongodb://devserver1,devserver2,devserver3/?replicaSet=devset");
$m = new MongoClient("mongodb://prodserver1,prodserver2,prodserver3/?replicaSet=prodset");
?>
]]>
</programlisting>
</example>
</warning>
<para>
If the primary becomes unavailable, an election will take place and a
secondary will be promoted to the role of primary (unless a majority vote
cannot be established). During this time
(<link xlink:href="&url.mongodb.replica.failover;">20-60 seconds</link>), the
connection will not be able to perform any write operations and attempts to
do so will result in an exception. Connections to secondaries will still be
able to perform reads.
</para>
<note>
<para>
The default <link linkend="mongo.readpreferences">Read Preference</link>
is to only read from the primary. During the election process there is no
primary, and all read will therefore fail.
</para>
<para>
It is recommended to use
<constant>MongoClient::RP_PRIMARY_PREFERRED</constant> Read Preference for
applications that require high availability for reads, as reads will only
be executed on the secondaries when there simply isn't a primary
available.
</para>
</note>
<para>
Once a primary is elected, attempting to perform a read or write will allow
the driver to detect the new primary. The driver will make this its primary
database connection and continue operating normally.
</para>
<para>
The health and state of a secondary is checked every 5 seconds
(configurable with
<link linkend="ini.mongo.ping-interval">mongo.ping_interval</link>)
or when the next operation occurs after 5 seconds. It will also recheck
the configuration when the driver has a problem reaching a server.
</para>
<para>
Replica set failovers are checked every 60 seconds (configurable with
<link linkend="ini.mongo.is-master-interval">mongo.is_master_interval</link>),
and whenever a write operation fails when using acknowledged writes.
</para>
<caution>
<para>
Secondaries may be behind the primary in operations, so
your application must be able to handle out-of-date data when using
Read Preferences other then <constant>MongoClient::RP_PRIMARY</constant>.
</para>
</caution>
<para>
For more information on replica sets, see the
<link xlink:href="&url.mongodb.replica;">core documentation</link>.
</para>
<simplesect role="seealso">
&reftitle.seealso;
<simplelist>
<member><xref linkend="mongo.readpreferences" /></member>
<member><xref linkend="mongo.writeconcerns" /></member>
</simplelist>
</simplesect>
<simplesect role="changelog">
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>1.0.9</entry>
<entry>
Added support for connecting to ReplicaSet and automatic failover.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</simplesect>
</section>
<section xml:id="mongo.connecting.mongos">
<title>Sharding</title>
<para>
To connect to a shard cluster, specify the address of one or more
<literal>mongos</literal> instances in the connection string. Multiple
servers may be delimited by a comma.
</para>
<example xml:id="mongo.connecting.mongos-example">
<programlisting role="php">
<![CDATA[
<?php
// Using one server as the seed list
$m = new MongoClient("mongodb://mongos1.example.com:27017");
// Using multiple servers as the seed list
$m = new MongoClient("mongodb://mongos1.example.com:27017,mongos2.example.com:27017");
?>
]]>
</programlisting>
</example>
<para>
Regardless of whether each shard is a stand-alone <literal>mongod</literal>
server or a full replica set, the driver's connection process is the same.
All database communication will be routed through <literal>mongos</literal>.
</para>
<para>
For more information on sharding with MongoDB, see the
<link xlink:href="&url.mongodb.docs.sharding;">sharding documentation</link>.
</para>
</section>
<section xml:id="mongo.connecting.uds">
<title>Domain Socket Support</title>
<para>
MongoDB has built-in support for connecting via Unix Domain Sockets and will
open the socket on startup. By default, the socket is located in
<filename>/tmp/mongodb-&lt;port&gt;.sock</filename>.
</para>
<para>
To connect to the socket file, specify the path in your MongoDB connection
string:
</para>
<example xml:id="mongo.connecting.uds-example">
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient("mongodb:///tmp/mongo-27017.sock");
?>
]]>
</programlisting>
</example>
<para>
If you would like to authenticate against a database (as described above)
with a socket file, you must specify a port of <literal>0</literal> so that
the connection string parser can detect the end of the socket path.
Alternatively, you can use the constructor options.
</para>
<example xml:id="mongo.connecting.uds-auth-example">
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient("mongodb://username:password@/tmp/mongo-27017.sock:0/foo");
?>
]]>
</programlisting>
</example>
<simplesect role="changelog">
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>1.0.9</entry>
<entry>
Added support for Unix Domain Sockets.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</simplesect>
</section>
<section xml:id="mongo.connecting.persistent">
<title>Persistent Connections (version 1.3.0+)</title>
<para>
All versions of the driver since 1.3.0 utilize persistent connections to
minimize the number of connections made to each database server. These
connections are saved by the PHP worker process and may be reused between
multiple requests.
</para>
<para>
Before connecting to a database server, the driver will create a hash for the
connection based on its host, port, replica set name (if any), any
authentication credentials (e.g. username, password, database), and the
process ID. If a connection already exists for that hash, it will be used in
lieu of creating a new connection associated with that hash.
<function>MongoClient::getConnections</function> may be used to retrieve info
about each persistent connection. Consider the following program:
</para>
<example xml:id="mongo.connecting.persistent-example">
<programlisting role="php">
<![CDATA[
<?php
$m1 = new MongoClient('mongodb://localhost');
$m2 = new MongoClient('mongodb://localhost');
$m3 = new MongoClient('mongodb://user:pw@localhost');
$m4 = new MongoClient('mongodb://127.0.0.1');
$m5 = new MongoClient('mongodb://rs1.local:30017,rs2.local:30018/?replicaSet=rs');
$m6 = new MongoClient('mongodb://sharding.local:40017');
foreach (MongoClient::getConnections() as $conn) {
echo $conn['hash'], "\n";
}
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
localhost:27017;-;X;15487
localhost:27017;-;admin/user/c56c…8bbc;15487
127.0.0.1:27017;-;X;15487
rs1.local:30017;rs;X;15487
rs2.local:30018;rs;X;15487
sharding.local:40017;-;X;15487
]]>
</screen>
</example>
<para>
In this example <literal>$m1</literal> and <literal>$m2</literal> have the
same hash and share a persistent connection. Connections for each other
MongoClient instance hash to unique values and use their own sockets. Note
that "localhost" and "127.0.0.1" do not share the same hash; DNS resolution
is not taken into account.
</para>
</section>
<section xml:id="mongo.connecting.pools">
<title>Connection Pooling (version 1.2.0-1.2.12 *only*)</title>
<note>
<para>
This section is no longer relevant as of the 1.3.0 release of the driver
and only serves as a historical information on how the pooling used to
work.
</para>
<para>
The latest versions of the driver have no concept of pooling anymore and
will maintain only one connection per process, for each connection type
(ReplicaSet/standalone/mongos), for each credentials combination.
</para>
</note>
<para>
Creating connections is one of the most heavyweight things that the driver
does. It can take hundreds of milliseconds to set up a connection correctly,
even on a fast network. Thus, the driver tries to minimize the number of new
connections created by reusing connections from a pool.
</para>
<para>
When a user creates a new instance of <classname>MongoClient</classname>, all
necessary connections will be taken from their pools (replica sets may
require multiple connections, one for each member of the set). When the
<classname>MongoClient</classname> instance goes out of scope, the
connections will be returned to the pool. When the PHP process exits, all
connections in the pools will be closed.
</para>
<section>
<title>"Why do I have so many open connections?"</title>
<para>
Connection pools can generate a large number of connections. This is
expected and, using a little arithmetic, you can figure out how many
connections will be created. There are three factors in determining the
total number of connections:
</para>
<itemizedlist>
<listitem>
<para>
<literal>
connections_per_pool
</literal>
</para>
<para>
Each connection pool will create, by default, an unlimited number of
connections. One might assume that this is a problem: if it can create an
unlimited number of connections, couldn't it create thousands and the
server would run out of file descriptors? In practice, this is unlikely,
as unused connections are returned to the pool to be used later, so future
connections will use the same connection instead of creating a new one.
Unless you create thousands of connections at once without letting any go
out of scope, the number of connections open should stay at a reasonable
number.
</para>
<para>
You can see how many connections you have in a pool using the
<function>MongoPool::info</function> function. Add up the "in use" and
"in pool" fields for a given server. That is the total number of
connections for that pool.
</para>
</listitem>
<listitem>
<para>
<literal>
pools_per_process
</literal>
</para>
<para>
Each MongoDB server address you're connecting to gets its own connection
pool. For example, if your local hostname is "example.net", connecting
to "example.net:27017", "localhost:27017", and "/tmp/mongodb-27017.sock"
will create three connection pools. You can see how many connection pools
you have open using <function>MongoPool::info</function>.
</para>
</listitem>
<listitem>
<para>
<literal>
processes
</literal>
</para>
<para>
Each PHP process has a separate set of pools. PHP-FPM and Apache
generally create between 6 and a couple of dozen PHP worker children.
Check your settings to see what the max number of PHP processes is that
can be spawned.
</para>
<para>
If you are using PHP-FPM, estimating the number of connections can be
tricky because it will spawn more PHP-FPM workers under heavy load. To be
on the safe side, look at the <literal>max_children</literal> parameter or
add up <literal>spare_servers</literal> + <literal>start_servers</literal>
(choose whichever number is higher). That will indicate how many PHP
processes (i.e. sets of pools) you should plan for.
</para>
</listitem>
</itemizedlist>
<para>
The three variables above can be multiplied together to give the max
number of connections expected:
<literal>connections_per_pool</literal> *
<literal>pools_per_process</literal> *
<literal>processes</literal>. Note that
<literal>connections_per_pool</literal> can be different for different
pools, so <literal>connections_per_pool</literal> should be the max.
</para>
<para>
For example, suppose we're getting 30 connections per pool, 10 pools per PHP
process, and 128 PHP processes. Then we can expect 38400 connections from
this machine. Thus, we should set this machine's file descriptor limit to
be high enough to handle all of these connections or it may run out of file
descriptors.
</para>
<para>
See <classname>MongoPool</classname> for more information on connection
pooling.
</para>
</section>
</section>
<section xml:id="mongo.connecting.persistent.manual">
<title>Manually Persistent Connections (version up to 1.1.4 *only*)</title>
<note>
<para>
This section is not relevant for 1.2.0+. In 1.2.0+, connections are always
persistent and managed automatically by the driver. If you are using a
1.2.x release (but not 1.3.x or later), see
<classname>MongoPool</classname> for more information on pooling.
</para>
</note>
<para>
Creating new connection to the database is very slow. To minimize the number
of connections that you need to make, you can use persistent connections. A
persistent connection is saved by PHP, so you can use the same connection for
multiple requests.
</para>
<para>
For example, this simple program connects to the database 1000 times:
</para>
<example xml:id="mongo.connecting.no-manual-persist-example">
<programlisting role="php">
<![CDATA[
<?php
for ($i=0; $i<1000; $i++) {
$m = new MongoClient();
}
?>
]]>
</programlisting>
</example>
<para>
It takes approximately 18 seconds to execute. If we change it to use a
persistent connection:
</para>
<example xml:id="mongo.connecting.manual-persist-example">
<programlisting role="php">
<![CDATA[
<?php
for ($i=0; $i<1000; $i++) {
$m = new MongoClient("localhost:27017", array("persist" => "x"));
}
?>
]]>
</programlisting>
</example>
<para>
...it takes less than .02 seconds to execute, as it only makes one database
connection.
</para>
<para>
Persistent connections need an identifier string (which is "x" in the above
example) to uniquely identify them. For a persistent connection to be used,
the hostname, port, persist string, and authentication credentials (username,
password and database, if given) must match an existing persistent
connection. Otherwise, a new connection will be created with this identifying
information.
</para>
<para>
Persistent connections are <emphasis>highly recommended</emphasis> and should
always be used in production unless there is a compelling reason not to.
Most of the reasons that they are not recommended for relational databases
are irrelevant to MongoDB.
</para>
</section>
</chapter>
<!-- 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
-->

299
reference/mongo/constants.xml
View file

@ -1,299 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<appendix xml:id="mongo.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.constants;
&extension.constants;
<para>
<variablelist>
<varlistentry xml:id="constant.mongo-streams">
<term>
<constant>MONGO_STREAMS</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
Alias of <constant>MONGO_SUPPORTS_STREAMS</constant>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-supports-streams">
<term>
<constant>MONGO_SUPPORTS_STREAMS</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
1 when compiled against PHP Streams (default since 1.4.0).
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-supports-ssl">
<term>
<constant>MONGO_SUPPORTS_SSL</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
1 when <xref linkend="book.openssl" /> is enabled and available.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-supports-auth-mechanism-mongodb-cr">
<term>
<constant>MONGO_SUPPORTS_AUTH_MECHANISM_MONGODB_CR</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
1 when MongoDB-Challenge/Reponse authentication is compiled in.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-supports-auth-mechanism-mongodb-x509">
<term>
<constant>MONGO_SUPPORTS_AUTH_MECHANISM_MONGODB_X509</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
1 when x.509 authentication is compiled in.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-supports-auth-mechanism-gssapi">
<term>
<constant>MONGO_SUPPORTS_AUTH_MECHANISM_GSSAPI</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
1 when GSSAPI authentication is compiled in.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-supports-auth-mechanism-plain">
<term>
<constant>MONGO_SUPPORTS_AUTH_MECHANISM_PLAIN</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
1 when PLAIN authentication is compiled in.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-type-io-init">
<term>
<constant>MONGO_STREAM_NOTIFY_TYPE_IO_INIT</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-type-log">
<term>
<constant>MONGO_STREAM_NOTIFY_TYPE_LOG</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-io-read">
<term>
<constant>MONGO_STREAM_NOTIFY_IO_READ</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-io-write">
<term>
<constant>MONGO_STREAM_NOTIFY_IO_WRITE</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-io-progress">
<term>
<constant>MONGO_STREAM_NOTIFY_IO_PROGRESS</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-io-completed">
<term>
<constant>MONGO_STREAM_NOTIFY_IO_COMPLETED</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-log-insert">
<term>
<constant>MONGO_STREAM_NOTIFY_LOG_INSERT</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-log-query">
<term>
<constant>MONGO_STREAM_NOTIFY_LOG_QUERY</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-log-update">
<term>
<constant>MONGO_STREAM_NOTIFY_LOG_UPDATE</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-log-delete">
<term>
<constant>MONGO_STREAM_NOTIFY_LOG_DELETE</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-log-getmore">
<term>
<constant>MONGO_STREAM_NOTIFY_LOG_GETMORE</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-log-killcursor">
<term>
<constant>MONGO_STREAM_NOTIFY_LOG_KILLCURSOR</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-log-batchinsert">
<term>
<constant>MONGO_STREAM_NOTIFY_LOG_BATCHINSERT</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-log-response-header">
<term>
<constant>MONGO_STREAM_NOTIFY_LOG_RESPONSE_HEADER</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-log-write-reply">
<term>
<constant>MONGO_STREAM_NOTIFY_LOG_WRITE_REPLY</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-log-cmd-insert">
<term>
<constant>MONGO_STREAM_NOTIFY_LOG_CMD_INSERT</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-log-cmd-update">
<term>
<constant>MONGO_STREAM_NOTIFY_LOG_CMD_UPDATE</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-log-cmd-delete">
<term>
<constant>MONGO_STREAM_NOTIFY_LOG_CMD_DELETE</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mongo-stream-notify-log-write-batch">
<term>
<constant>MONGO_STREAM_NOTIFY_LOG_WRITE_BATCH</constant>
(<type>int</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
</appendix>
<!-- 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
-->

64
reference/mongo/context.xml
View file

@ -1,64 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<reference xml:id="mongo.context" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Stream Context Options</title>
<partintro>
<para xml:id="mongo.context.options">
The PHP MongoDB extension provides <link linkend="context">Stream Context Support</link>
using the <link linkend="context.mongodb">mongodb</link> context.
</para>
<para>
A stream context must be created with <function>stream_context_create</function> and passed to the <methodname>MongoClient::__construct</methodname> before the actual connection to MongoDB is made.
It is not possible to apply a stream context to already created streams.
</para>
<para>
Additional context options and parameters, such as <link linkend="context.ssl">ssl</link>
and <link linkend="context.params">notification parameters</link>, are also supported.
</para>
<para>
The MongoDB context options provide a rich interface to log network traffic between the driver and the MongoDB servers.
This interface can be used to provide query logging, profiler, debuggers, or anything that would need to inspect the underlaying
commands and protocol options.
</para>
<simplesect role="seealso">
&reftitle.seealso;
<simplelist>
<member><xref linkend="context.ssl" /></member>
<member><xref linkend="context.socket" /></member>
<member><xref linkend="context.params" /></member>
</simplelist>
</simplesect>
</partintro>
&reference.mongo.entities.context;
</reference>
<!-- 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
-->

114
reference/mongo/context/log-cmd-delete.xml
View file

@ -1,114 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.log-cmd-delete" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>log_cmd_delete</refname>
<refpurpose>Callback When Deleting Documents</refpurpose>
</refnamediv>
<refsect1 role="description"><!-- {{{ -->
&reftitle.description;
<methodsynopsis role="procedural">
<methodname>log_cmd_delete</methodname>
<methodparam><type>array</type><parameter>server</parameter></methodparam>
<methodparam><type>array</type><parameter>writeOptions</parameter></methodparam>
<methodparam><type>array</type><parameter>deleteOptions</parameter></methodparam>
<methodparam><type>array</type><parameter>protocolOptions</parameter></methodparam>
</methodsynopsis>
<para>
A <type>callable</type> function, used by the
<link linkend="context.mongodb.log-cmd-delete">log_cmd_delete context option</link>,
when deleteing a document
</para>
<note>
<para>
This is <emphasis>not</emphasis> a real function, only a prototype of how the function should
be.
</para>
</note>
</refsect1><!-- }}} -->
<refsect1 role="parameters"><!-- {{{ -->
&reftitle.parameters;
<variablelist>
&mongo.context.server;
&mongo.context.writeoptions;
<varlistentry>
<term>
<parameter>deleteOptions</parameter>
</term>
<listitem>
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>key</entry>
<entry>value</entry>
</row>
</thead>
<tbody>
<row>
<entry>limit</entry>
<entry>integer, 1 or 0. If 0, delete all matching documents.</entry>
</row>
<row>
<entry>q</entry>
<entry>Array, the search criteria</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
</varlistentry>
&mongo.context.protocoloptions;
</variablelist>
</refsect1><!-- }}} -->
<refsect1 role="changelog"><!-- {{{ -->
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>PECL mongo 1.5.0</entry>
<entry>
Only available when connected to MongoDB 2.6.0+
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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
-->

95
reference/mongo/context/log-cmd-insert.xml
View file

@ -1,95 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.log-cmd-insert" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>log_cmd_insert</refname>
<refpurpose>Callback When Inserting Documents</refpurpose>
</refnamediv>
<refsect1 role="description"><!-- {{{ -->
&reftitle.description;
<methodsynopsis role="procedural">
<methodname>log_cmd_insert</methodname>
<methodparam><type>array</type><parameter>server</parameter></methodparam>
<methodparam><type>array</type><parameter>document</parameter></methodparam>
<methodparam><type>array</type><parameter>writeOptions</parameter></methodparam>
<methodparam><type>array</type><parameter>protocolOptions</parameter></methodparam>
</methodsynopsis>
<para>
A <type>callable</type> function, used by the
<link linkend="context.mongodb.log-cmd-insert">log_cmd_insert context option</link>,
when inserting a document
</para>
<note>
<para>
This is <emphasis>not</emphasis> a real function, only a prototype of how the function should
be.
</para>
</note>
</refsect1><!-- }}} -->
<refsect1 role="parameters"><!-- {{{ -->
&reftitle.parameters;
<variablelist>
&mongo.context.server;
<varlistentry>
<term>
<parameter>document</parameter>
</term>
<listitem>
<para>
The document that has been prepared to be inserted
</para>
</listitem>
</varlistentry>
&mongo.context.writeoptions;
&mongo.context.protocoloptions;
</variablelist>
</refsect1><!-- }}} -->
<refsect1 role="changelog"><!-- {{{ -->
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>PECL mongo 1.5.0</entry>
<entry>
Only available when connected to MongoDB 2.6.0+
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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
-->

122
reference/mongo/context/log-cmd-update.xml
View file

@ -1,122 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.log-cmd-update" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>log_cmd_update</refname>
<refpurpose>Callback When Updating Documents</refpurpose>
</refnamediv>
<refsect1 role="description"><!-- {{{ -->
&reftitle.description;
<methodsynopsis role="procedural">
<methodname>log_cmd_update</methodname>
<methodparam><type>array</type><parameter>server</parameter></methodparam>
<methodparam><type>array</type><parameter>writeOptions</parameter></methodparam>
<methodparam><type>array</type><parameter>updateOptions</parameter></methodparam>
<methodparam><type>array</type><parameter>protocolOptions</parameter></methodparam>
</methodsynopsis>
<para>
A <type>callable</type> function, used by the
<link linkend="context.mongodb.log-cmd-update">log_cmd_update context option</link>,
when updateing a document
</para>
<note>
<para>
This is <emphasis>not</emphasis> a real function, only a prototype of how the function should
be.
</para>
</note>
</refsect1><!-- }}} -->
<refsect1 role="parameters"><!-- {{{ -->
&reftitle.parameters;
<variablelist>
&mongo.context.server;
&mongo.context.writeoptions;
<varlistentry>
<term>
<parameter>updateOptions</parameter>
</term>
<listitem>
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>key</entry>
<entry>value</entry>
</row>
</thead>
<tbody>
<row>
<entry>multi</entry>
<entry>Boolean, true if this update is allowed to update all matched criteria</entry>
</row>
<row>
<entry>upsert</entry>
<entry>Boolean, true if the document should be created if criteria does not match</entry>
</row>
<row>
<entry>q</entry>
<entry>Array, the search criteria</entry>
</row>
<row>
<entry>u</entry>
<entry>Array, the new object/modifications</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
</varlistentry>
&mongo.context.protocoloptions;
</variablelist>
</refsect1><!-- }}} -->
<refsect1 role="changelog"><!-- {{{ -->
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>PECL mongo 1.5.0</entry>
<entry>
Only available when connected to MongoDB 2.6.0+
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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
-->

91
reference/mongo/context/log-getmore.xml
View file

@ -1,91 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.log-getmore" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>log_getmore</refname>
<refpurpose>Callback When Retrieving Next Cursor Batch</refpurpose>
</refnamediv>
<refsect1 role="description"><!-- {{{ -->
&reftitle.description;
<methodsynopsis role="procedural">
<methodname>log_getmore</methodname>
<methodparam><type>array</type><parameter>server</parameter></methodparam>
<methodparam><type>array</type><parameter>info</parameter></methodparam>
</methodsynopsis>
<para>
A <type>callable</type> function, used by the
<link linkend="context.mongodb.log-getmore">log_getmore context option</link>,
when executing a GET_MORE operation.
</para>
<note>
<para>
This is <emphasis>not</emphasis> a real function, only a prototype of how the function should
be.
</para>
</note>
</refsect1><!-- }}} -->
<refsect1 role="parameters"><!-- {{{ -->
&reftitle.parameters;
<variablelist>
&mongo.context.server;
<varlistentry>
<term>
<parameter>info</parameter>
</term>
<listitem>
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>key</entry>
<entry>value</entry>
</row>
</thead>
<tbody>
<row>
<entry>request_id</entry>
<entry>integer, the driver request identifier</entry>
</row>
<row>
<entry>cursor_id</entry>
<entry>integer, the cursor identifier being used to fetch more data</entry>
</row>
<row>
<entry>batch_size</entry>
<entry>integer, maximum number of documents being requested</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
</varlistentry>
</variablelist>
</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
-->

83
reference/mongo/context/log-killcursor.xml
View file

@ -1,83 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.log-killcursor" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>log_killcursor</refname>
<refpurpose>Callback When Executing KILLCURSOR operations</refpurpose>
</refnamediv>
<refsect1 role="description"><!-- {{{ -->
&reftitle.description;
<methodsynopsis role="procedural">
<methodname>log_killcursor</methodname>
<methodparam><type>array</type><parameter>server</parameter></methodparam>
<methodparam><type>array</type><parameter>info</parameter></methodparam>
</methodsynopsis>
<para>
A <type>callable</type> function, used by the
<link linkend="context.mongodb.log-killcursor">log_killcursor context option</link>,
when reading a killcursor from MongoDB.
</para>
<note>
<para>
This is <emphasis>not</emphasis> a real function, only a prototype of how the function should
be.
</para>
</note>
</refsect1><!-- }}} -->
<refsect1 role="parameters"><!-- {{{ -->
&reftitle.parameters;
<variablelist>
&mongo.context.server;
<varlistentry>
<term>
<parameter>info</parameter>
</term>
<listitem>
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>key</entry>
<entry>value</entry>
</row>
</thead>
<tbody>
<row>
<entry>cursor_id</entry>
<entry>integer, the cursor identifier to kill</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
</varlistentry>
</variablelist>
</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
-->

141
reference/mongo/context/log-reply.xml
View file

@ -1,141 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.log-reply" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>log_reply</refname>
<refpurpose>Callback When Reading the MongoDB reply</refpurpose>
</refnamediv>
<refsect1 role="description"><!-- {{{ -->
&reftitle.description;
<methodsynopsis role="procedural">
<methodname>log_reply</methodname>
<methodparam><type>array</type><parameter>server</parameter></methodparam>
<methodparam><type>array</type><parameter>messageHeaders</parameter></methodparam>
<methodparam><type>array</type><parameter>operationHeaders</parameter></methodparam>
</methodsynopsis>
<para>
A <type>callable</type> function, used by the
<link linkend="context.mongodb.log-reply">log_reply context option</link>,
when reading a reply from MongoDB.
</para>
<note>
<para>
This is <emphasis>not</emphasis> a real function, only a prototype of how the function should
be.
</para>
</note>
</refsect1><!-- }}} -->
<refsect1 role="parameters"><!-- {{{ -->
&reftitle.parameters;
<variablelist>
&mongo.context.server;
<varlistentry>
<term>
<parameter>messageHeaders</parameter>
</term>
<listitem>
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>key</entry>
<entry>value</entry>
</row>
</thead>
<tbody>
<row>
<entry>length</entry>
<entry>integer, bytes, message reply length</entry>
</row>
<row>
<entry>request_id</entry>
<entry>integer, the server request identifier</entry>
</row>
<row>
<entry>response_id</entry>
<entry>integer, the driver request identifier this message is a response of</entry>
</row>
<row>
<entry>opcode</entry>
<entry>integer, the opcode id</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>operationHeaders</parameter>
</term>
<listitem>
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>key</entry>
<entry>value</entry>
</row>
</thead>
<tbody>
<row>
<entry>flags</entry>
<entry>integer, bitmask of protocol flags</entry>
</row>
<row>
<entry>cursor_id</entry>
<entry>integer, ID of the cursor created on the server (0 if none created, or its been exhausted)</entry>
</row>
<row>
<entry>start</entry>
<entry>The starting offset of this cursor</entry>
</row>
<row>
<entry>returned</entry>
<entry>integer, how many documents are returned in this trip</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1><!-- }}} -->
<refsect1 role="seealso"><!-- {{{ -->
&reftitle.seealso;
<simplelist>
<member>The <link xlink:href="&url.mongodb.dochub.wireprotocol;">OP_REPLY definition in the Wire Protocol</link></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
-->

95
reference/mongo/context/log-write-batch.xml
View file

@ -1,95 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.log-write-batch" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>log_write_batch</refname>
<refpurpose>Callback When Writing Batches</refpurpose>
</refnamediv>
<refsect1 role="description"><!-- {{{ -->
&reftitle.description;
<methodsynopsis role="procedural">
<methodname>log_write_batch</methodname>
<methodparam><type>array</type><parameter>server</parameter></methodparam>
<methodparam><type>array</type><parameter>writeOptions</parameter></methodparam>
<methodparam><type>array</type><parameter>batch</parameter></methodparam>
<methodparam><type>array</type><parameter>protocolOptions</parameter></methodparam>
</methodsynopsis>
<para>
A <type>callable</type> function, used by the
<link linkend="context.mongodb.log-write-batch">log_write_batch context option</link>,
when executing a batch operation.
</para>
<note>
<para>
This is <emphasis>not</emphasis> a real function, only a prototype of how the function should
be.
</para>
</note>
</refsect1><!-- }}} -->
<refsect1 role="parameters"><!-- {{{ -->
&reftitle.parameters;
<variablelist>
&mongo.context.server;
&mongo.context.writeoptions;
<varlistentry>
<term>
<parameter>batch</parameter>
</term>
<listitem>
<para>
Array, the actual batch operation.
</para>
</listitem>
</varlistentry>
&mongo.context.protocoloptions;
</variablelist>
</refsect1><!-- }}} -->
<refsect1 role="changelog"><!-- {{{ -->
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>PECL mongo 1.5.0</entry>
<entry>
Only available when connected to MongoDB 2.6.0+
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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
-->

23
reference/mongo/core.xml
View file

@ -1,23 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<part xml:id="mongo.core" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Core Classes</title>
<partintro>
<warning>
&mongo.deprecated.note;
</warning>
<para>
The core classes are the most important part of the driver.
</para>
</partintro>
&reference.mongo.mongoclient;
&reference.mongo.mongodb;
&reference.mongo.mongocollection;
&reference.mongo.mongocursor;
&reference.mongo.mongocursorinterface;
&reference.mongo.mongocommandcursor;
</part>

45
reference/mongo/exceptions.xml
View file

@ -1,45 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<part xml:id="mongo.exceptions" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Exceptions</title>
<partintro>
<section>
<title>VMWare Oddities</title>
<para>
If you are running VMWare on Windows and are using CIFS, pausing the VM will
cause CIFS to go out of sync and cause weird errors on un-pausing it ("The
Mongo object has not been correctly initialized by its constructor").
Permanently mounting the Windows shares will fix this and you'll be able to
pause and unpause at will.
</para>
<para>
To permanently mount the Windows shares, run:
</para>
<programlisting role="shell">
<![CDATA[
$ sudo update-rc.d -f umountnfs.sh remove
$ sudo update-rc.d umountnfs.sh stop 15 0 6 .
]]>
</programlisting>
<para>
See <link xlink:href="&url.mongodb.cifs;">the Ubuntu docs</link> for the most
up-to-date instructions.
</para>
</section>
</partintro>
&reference.mongo.mongoexception;
&reference.mongo.mongoresultexception;
&reference.mongo.mongocursorexception;
&reference.mongo.mongocursortimeoutexception;
&reference.mongo.mongoconnectionexception;
&reference.mongo.mongogridfsexception;
&reference.mongo.mongoduplicatekeyexception;
&reference.mongo.mongoprotocolexception;
&reference.mongo.mongoexecutiontimeoutexception;
&reference.mongo.mongowriteconcernexception;
</part>

66
reference/mongo/functions/bson-decode.xml
View file

@ -1,66 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.bson-decode" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>bson_decode</refname>
<refpurpose>Deserializes a BSON object into a PHP array</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>bson_decode</methodname>
<methodparam><type>string</type><parameter>bson</parameter></methodparam>
</methodsynopsis>
<para>
This function is very beta and entirely useless for 99% of users. It is only
useful if you're doing something weird, such as writing your own driver on
top of the PHP driver.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>bson</parameter></term>
<listitem>
<para>
The BSON to be deserialized.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the deserialized BSON object.
</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
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
-->

66
reference/mongo/functions/bson-encode.xml
View file

@ -1,66 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.bson-encode" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>bson_encode</refname>
<refpurpose>Serializes a PHP variable into a BSON string</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>bson_encode</methodname>
<methodparam><type>mixed</type><parameter>anything</parameter></methodparam>
</methodsynopsis>
<para>
This function is very beta and entirely useless for 99% of users. It is only
useful if you're doing something weird, such as writing your own driver on
top of the PHP driver.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>anything</parameter></term>
<listitem>
<para>
The variable to be serialized.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the serialized string.
</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
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
-->

12
reference/mongo/gridfs.xml
View file

@ -1,12 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<part xml:id="mongo.gridfs" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>GridFS Classes</title>
&reference.mongo.mongogridfs;
&reference.mongo.mongogridfsfile;
&reference.mongo.mongogridfscursor;
</part>

340
reference/mongo/ini.xml
View file

@ -1,340 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<section xml:id="mongo.configuration" xmlns="http://docbook.org/ns/docbook">
&reftitle.runtime;
&extension.runtime;
<para>
<table>
<title>Mongo &ConfigureOptions;</title>
<tgroup cols="3">
<thead>
<row>
<entry>&Name;</entry>
<entry>&Default;</entry>
<entry>&Changeable;</entry>
<entry>&Changelog;</entry>
</row>
</thead>
<tbody xml:id="mongo.configuration.list">
<row>
<entry><link linkend="ini.mongo.allow-empty-keys">mongo.allow_empty_keys</link></entry>
<entry>0</entry>
<entry>PHP_INI_ALL</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="ini.mongo.allow-persistent">mongo.allow_persistent</link></entry>
<entry>1</entry>
<entry>PHP_INI_ALL</entry>
<entry>Removed in 1.2.0</entry>
</row>
<row>
<entry><link linkend="ini.mongo.chunk-size">mongo.chunk_size</link></entry>
<entry>262144</entry>
<entry>PHP_INI_ALL</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="ini.mongo.cmd">mongo.cmd</link></entry>
<entry>"$"</entry>
<entry>PHP_INI_ALL</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="ini.mongo.default-host">mongo.default_host</link></entry>
<entry>"localhost"</entry>
<entry>PHP_INI_ALL</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="ini.mongo.default-port">mongo.default_port</link></entry>
<entry>27017</entry>
<entry>PHP_INI_ALL</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="ini.mongo.is-master-interval">mongo.is_master_interval</link></entry>
<entry>15</entry>
<entry>PHP_INI_ALL</entry>
<entry>Added in 1.2.10, before 1.3.0 the default value was 60.</entry>
</row>
<row>
<entry><link linkend="ini.mongo.long-as-object">mongo.long_as_object</link></entry>
<entry>0</entry>
<entry>PHP_INI_ALL</entry>
<entry></entry>
</row>
<row>
<entry><link linkend="ini.mongo.native-long">mongo.native_long</link></entry>
<entry>1</entry>
<entry>PHP_INI_ALL</entry>
<entry>Before 1.5.0, the default value was 0.</entry>
</row>
<row>
<entry><link linkend="ini.mongo.ping-interval">mongo.ping_interval</link></entry>
<entry>5</entry>
<entry>PHP_INI_ALL</entry>
<entry>Added in 1.2.10</entry>
</row>
<row>
<entry><link linkend="ini.mongo.utf8">mongo.utf8</link></entry>
<entry>1</entry>
<entry>PHP_INI_ALL</entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</table>
&ini.php.constants;
</para>
&ini.descriptions.title;
<para>
<variablelist>
<varlistentry xml:id="ini.mongo.allow-empty-keys">
<term>
<parameter>mongo.allow_empty_keys</parameter>
<type>int</type>
</term>
<listitem>
<para>
Added in version 1.0.11.
</para>
<para>
If empty strings ("") should be allowed as key names. By default, the
driver will throw an exception if you attempt to pass the empty string as
a key to the database. It is extremely easy to do this inavertently by
using double quotes with $-operators, so it is recommended that you leave
this setting as default. However, if you need to save keys that are empty
strings, you can set this option to true and the driver will allow you to
pass empty strings to the database.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mongo.allow-persistent">
<term>
<parameter>mongo.allow_persistent</parameter>
<type>int</type>
</term>
<listitem>
<para>
If persistent connections are allowed. (Removed in 1.2.0 - all
connections are now persistent).
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mongo.chunk-size">
<term>
<parameter>mongo.chunk_size</parameter>
<type>int</type>
</term>
<listitem>
<para>
The number of bytes-per-chunk. Used in divvying up GridFS files. This
number must be at least 100 less than 4 megabytes (max: 4194204) and it is
recommended that it be less than that.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mongo.cmd">
<term>
<parameter>mongo.cmd</parameter>
<type>string</type>
</term>
<listitem>
<para>
A character to be used in place of $ in modifiers and comparisons.
</para>
<para>
As it is easy to forget to escape the "$", you can also choose your own
special character to use instead of '$'. Choose a character that will not
occur in your key names, e.g. ":":
</para>
<programlisting role="ini">
<![CDATA[
mongo.cmd = ":"
]]>
</programlisting>
<para>
Then, to do a comparison, for example:
</para>
<programlisting role="php">
<![CDATA[
<?php
$query = array( "i" => array( ":gt" => 20, ":lte" => 30 ) );
?>
]]>
</programlisting>
<para>
You can also change it in your code using
<literal>ini_set("mongo.cmd", ":")</literal>. Of course, you can also
just use single quotes or backslash-escape the $.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mongo.default-host">
<term>
<parameter>mongo.default_host</parameter>
<type>string</type>
</term>
<listitem>
<para>
Default hostname when nothing is passed to the constructor.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mongo.default-port">
<term>
<parameter>mongo.default_port</parameter>
<type>string</type>
</term>
<listitem>
<para>
The default TCP port number to use when connecting to the database server
if no other port is specified. The database's default is
<literal>27017</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mongo.is-master-interval">
<term>
<parameter>mongo.is_master_interval</parameter>
<type>int</type>
</term>
<listitem>
<para>
Added in version 1.2.10.
</para>
<para>
For replicaset connections: The minimum interval with which the driver
will send "isMaster" requests to the MongoDB server. If the value is lower,
there will be more requests, but the driver finds faster whether the
topology of the replicaset has been changed.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mongo.long-as-object">
<term>
<parameter>mongo.long_as_object</parameter>
<type>int</type>
</term>
<listitem>
<para>
Return a BSON_LONG as an instance of <classname>MongoInt64</classname>
(instead of a primitive type).
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mongo.native-long">
<term>
<parameter>mongo.native_long</parameter>
<type>int</type>
</term>
<listitem>
<para>
<emphasis>
The default behavior for this has been changed to &true; in 1.5.0, so make
sure to set this variable to the value you want (probably &true;) so that
the driver's behavior doesn't suddenly change when you upgrade.
</emphasis>
</para>
<para>
On 64-bit platforms, the <literal>mongo.native_long</literal> setting
allows for 64-bit integers to be stored in MongoDB. If it is not set, only
32-bits of the integer will be saved. The MongoDB data type that is used
in this case is the BSON LONG, instead of the BSON INT that is used if
this setting is turned off.
</para>
<para>
The setting also changes the way how BSON LONGs behave when they are read
back from MongoDB. Without <literal>mongo.native_long</literal> enabled,
the driver would convert every BSON LONG to a PHP double which can result
in a loss of precision.
</para>
<para>
On 32-bit platforms, the <literal>mongo.native_long</literal> setting
changes nothing for storing integers in MongoDB: the integer is stored
as a BSON INT as before. However, when the setting is enabled and a
BSON LONG is read from MongoDB a
<classname>MongoCursorException</classname> is thrown alerting you that
the data could not be read back without losing precision.
</para>
<para>
On 32-bit systems especially, it is recommended that you combine this with
enabling <literal>mongo.long_as_object</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mongo.ping-interval">
<term>
<parameter>mongo.ping_interval</parameter>
<type>int</type>
</term>
<listitem>
<para>
Added in version 1.2.10.
</para>
<para>
For replicaset connections: The minimum interval with which the driver
will send "ping" requests to the MongoDB server. If the value is lower,
there will be more pings, but the driver finds faster whether a node is
no longer reachable from the replicaset.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mongo.utf8">
<term>
<parameter>mongo.utf8</parameter>
<type>int</type>
</term>
<listitem>
<para>
If an exception should be thrown for non-UTF8 strings. Until version
1.0.4, the PHP driver would ignore non-UTF8 strings, even though you're
not supposed to insert them. As of 1.0.4, the driver throws a
<classname>MongoException</classname>. To ease the transition for
applications that insert non-UTF8 strings, you can turn this option off to
emulate the old, non-exception-throwning behavior. This option will be
eliminated and exceptions always thrown for non-UTF8 strings starting with
version 1.1.0.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
<!-- 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
-->

53
reference/mongo/manual.xml
View file

@ -1,53 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<part xml:id="mongo.manual" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Manual</title>
<partintro xml:id="mongo.manual.intro">
<warning>
&mongo.deprecated.note;
</warning>
<para>
This manual goes into some detail about how to use MongoDB, but it mostly
covers using the PHP driver. For information about how to design a
schema, what terms means, and setting up the database server, check out the
<link xlink:href="&url.mongodb;">MongoDB documentation</link>.
</para>
</partintro>
&reference.mongo.tutorial;
&reference.mongo.readpreferences;
&reference.mongo.writeconcerns;
&reference.mongo.sqltomongo;
&reference.mongo.connecting;
&reference.mongo.context;
&reference.mongo.writes;
&reference.mongo.queries;
&reference.mongo.updates;
&reference.mongo.security;
&reference.mongo.trouble;
&reference.mongo.testing;
</part>
<!-- 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
-->

12
reference/mongo/misc.xml
View file

@ -1,12 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<part xml:id="mongo.miscellaneous" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Miscellaneous</title>
&reference.mongo.mongolog;
&reference.mongo.mongopool;
&reference.mongo.mongo;
</part>

93
reference/mongo/mongo.xml
View file

@ -1,93 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<phpdoc:classref xml:id="class.mongo" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>The Mongo class [deprecated]</title>
<titleabbrev>Mongo</titleabbrev>
<partintro>
<!-- {{{ Mongo intro -->
<section xml:id="mongo.intro">
&reftitle.intro;
<para>
A connection between PHP and MongoDB.
</para>
<para>
This class extends <classname>MongoClient</classname> and provides access to
several deprecated methods.
</para>
<para>
For backwards compatibility, it also defaults the <literal>"w"</literal>
option of its constructor argument to <literal>0</literal>, which does not
require write operations to be acknowledged by the server. See
<function>MongoClient::__construct</function> for more information.
</para>
<warning xmlns="http://docbook.org/ns/docbook">
<simpara>
This class has been <emphasis>DEPRECATED</emphasis> as of version
1.3.0. Relying on this feature is highly discouraged. Please use
<classname>MongoClient</classname> instead.
</simpara>
</warning>
</section>
<!-- }}} -->
<section xml:id="mongo.synopsis">
&reftitle.classsynopsis;
<!-- {{{ Synopsis -->
<classsynopsis>
<ooclass><classname>Mongo</classname></ooclass>
<!-- {{{ Class synopsis -->
<classsynopsisinfo>
<ooclass>
<classname>Mongo</classname>
</ooclass>
<ooclass>
<modifier>extends</modifier>
<classname>MongoClient</classname>
</ooclass>
</classsynopsisinfo>
<!-- }}} -->
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongo')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
<classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongoclient')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
</classsynopsis>
<!-- }}} -->
</section>
<!-- }}} -->
</partintro>
&reference.mongo.entities.mongo;
</phpdoc:classref>
<!-- 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
-->

63
reference/mongo/mongo/connectutil.xml
View file

@ -1,63 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongo.connectutil" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Mongo::connectUtil</refname>
<refpurpose>Connects with a database server</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>protected</modifier> <type>bool</type><methodname>Mongo::connectUtil</methodname>
<void/>
</methodsynopsis>
<warning>
<para>
This is an internal function that you should <emphasis>never</emphasis>
call yourself.
</para>
</warning>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
If the connection was successful.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoConnectionException</classname> if it fails to connect
to the databases.
</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
-->

62
reference/mongo/mongo/construct.xml
View file

@ -1,62 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongo.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Mongo::__construct</refname>
<refpurpose>The __construct purpose</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<constructorsynopsis>
<modifier>public</modifier> <methodname>Mongo::__construct</methodname>
<methodparam choice="opt"><type>string</type><parameter>server</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
</constructorsynopsis>
<para>
This method overwrites the <classname>MongoClient</classname> constructor
and turns off acknowledged writes.
</para>
<para>
Please see <methodname>MongoClient::__construct</methodname> for
description of the parameters.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.returnvalues;
<warning>
<para>
Instanciating this class will emit <constant>E_DEPRECATED</constant>
warning, and turn off acknowledged writes.
</para>
</warning>
<para>
Please use the <classname>MongoClient</classname> instead.
</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
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
-->

127
reference/mongo/mongo/getpoolsize.xml
View file

@ -1,127 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongo.getpoolsize" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Mongo::getPoolSize</refname>
<refpurpose>Get pool size for connection pools</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <modifier>static</modifier> <type>int</type><methodname>Mongo::getPoolSize</methodname>
<void/>
</methodsynopsis>
<warning xmlns="http://docbook.org/ns/docbook">
<simpara>This feature has been <emphasis>DEPRECATED</emphasis> as of version
1.2.3. Relying on this feature is highly discouraged. Please use
<function>MongoPool::getSize</function> instead.
</simpara>
</warning>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the current pool size.
</para>
</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 mongo 1.2.11</entry>
<entry>Emits <constant>E_DEPRECATED</constant> when used.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title>Changing pool size</title>
<para>
This returns the default pool size, sets a new pool size, then prints the
new pool size and the pool debugging information. Note that changing the
pool size only affects new connection pools, it does not change old ones.
</para>
<programlisting role="php">
<![CDATA[
<?php
$connection = new Mongo("host1");
// pool size is -1
echo "pool size is: ".Mongo::getPoolSize()."\n";
echo "setting pool size to 200\n";
Mongo::setPoolSize(200);
// pool size is 200
echo "pool size is: ".Mongo::getPoolSize()."\n";
$conn2 = new Mongo("host2");
// remaining for host1 is -2
// remaining for host2 is 199
var_dump(Mongo::poolDebug());
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>Mongo::setPoolSize</function></member>
<member><function>Mongo::poolDebug</function></member>
<member>The <link linkend="mongo.connecting">connection</link> documentation.</member>
</simplelist>
</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
-->

112
reference/mongo/mongo/getslave.xml
View file

@ -1,112 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongo.getslave" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Mongo::getSlave</refname>
<refpurpose>Returns the address being used by this for slaveOkay reads</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>string</type><methodname>Mongo::getSlave</methodname>
<void/>
</methodsynopsis>
<para>
This finds the address of the secondary currently being used for reads. It is
a read-only method: it does not change anything about the internal state of
the object.
</para>
<para>
When you create a connection to the database, the driver will not immediately
decide on a secondary to use. Thus, after you connect, this function will
return &null; even if there are secondaries available. When you first do a
query with slaveOkay set, at that point the driver will choose a secondary
for this connection. At that point, this function will return the chosen
secondary.
</para>
<para>
See <link linkend="mongo.queries">the query section</link> of this manual for
information on distributing reads to secondaries.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The address of the secondary this connection is using for reads.
</para>
<para>
This returns &null; if this is not connected to a replica set or not yet
initialized.
</para>
</refsect1>
<refsect1 role="errors"><!-- {{{ -->
&reftitle.errors;
&mongo.errors.deprecated;
<para>
The returned results aren't really useful as the secondary selection
process is done on each query and database command execution.
</para>
</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 mongo 1.2.11</entry>
<entry>Emits <constant>E_DEPRECATED</constant> when used.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="seealso"><!-- {{{ -->
&reftitle.seealso;
<simplelist>
<member><function>MongoCursor::info</function></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
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
-->

89
reference/mongo/mongo/getslaveokay.xml
View file

@ -1,89 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongo.getslaveokay" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Mongo::getSlaveOkay</refname>
<refpurpose>Get slaveOkay setting for this connection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>Mongo::getSlaveOkay</methodname>
<void/>
</methodsynopsis>
<para>
See <link linkend="mongo.queries">the query section</link> of this manual for
information on distributing reads to secondaries.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the value of slaveOkay for this instance.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
&mongo.errors.deprecated;
</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 mongo 1.2.11</entry>
<entry>Emits <constant>E_DEPRECATED</constant> when used.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="seealso"><!-- {{{ -->
&reftitle.seealso;
<simplelist>
<member><xref linkend="mongo.readpreferences" /></member>
<member><methodname>MongoClient::getReadPreference</methodname></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
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
-->

141
reference/mongo/mongo/pooldebug.xml
View file

@ -1,141 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongo.pooldebug" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Mongo::poolDebug</refname>
<refpurpose>Returns information about all connection pools</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>Mongo::poolDebug</methodname>
<void/>
</methodsynopsis>
<warning xmlns="http://docbook.org/ns/docbook">
<simpara>This feature has been <emphasis>DEPRECATED</emphasis> as of version
1.2.3. Relying on this feature is highly discouraged. Please use
<function>MongoPool::info</function> instead.
</simpara>
</warning>
<para>
Returns an array of information about all connection pools.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Each connection pool has an identifier, which starts with the host. For each
pool, this function shows the following fields:
<variablelist>
<varlistentry>
<term>
<parameter>in use</parameter>
</term>
<listitem>
<para>
The number of connections currently being used by
<classname>MongoClient</classname> instances.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>in pool</parameter>
</term>
<listitem>
<para>
The number of connections currently in the pool (not being used).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>remaining</parameter>
</term>
<listitem>
<para>
The number of connections that could be created by this pool. For
example, suppose a pool had 5 connections remaining and 3 connections in
the pool. We could create 8 new instances of
<classname>MongoClient</classname> before we exhausted this pool
(assuming no instances of <classname>MongoClient</classname> went out of
scope, returning their connections to the pool).
</para>
<para>
A negative number means that this pool will spawn unlimited connections.
</para>
<para>
Before a pool is created, you can change the max number of connections by
calling <function>Mongo::setPoolSize</function>. Once a pool is showing
up in the output of this function, its size cannot be changed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>timeout</parameter>
</term>
<listitem>
<para>
The socket timeout for connections in this pool. This is how long
connections in this pool will attempt to connect to a server before
giving up.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</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 mongo 1.2.11</entry>
<entry>Emits <constant>E_DEPRECATED</constant> when used.</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
-->

129
reference/mongo/mongo/setpoolsize.xml
View file

@ -1,129 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongo.setpoolsize" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Mongo::setPoolSize</refname>
<refpurpose>Set the size for future connection pools</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>Mongo::setPoolSize</methodname>
<methodparam><type>int</type><parameter>size</parameter></methodparam>
</methodsynopsis>
<warning xmlns="http://docbook.org/ns/docbook">
<simpara>This method has been <emphasis>DEPRECATED</emphasis> as of version
1.2.3. Relying on this feature is highly discouraged. Please use
<function>MongoPool::setSize</function> instead.
</simpara>
</warning>
<para>
Sets the max number of connections new pools will be able to create.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>size</parameter>
</term>
<listitem>
<para>
The max number of connections future pools will be able to create.
Negative numbers mean that the pool will spawn an infinite number of
connections.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the former value of pool size.
</para>
</refsect1>
<refsect1 role="examples"><!-- {{{ -->
&reftitle.examples;
<para>
<example xml:id="mongo.setpoolsize.example.basic"><!-- {{{ -->
<title><function>Mongo::setPoolSize</function> example</title>
<para>
If you set the pool size to <literal>n</literal> and then create
<literal>n</literal> connections, attempting to create an
<literal>n+1</literal>st connection will throw a
<classname>MongoConnectionException</classname>.
</para>
<programlisting role="php">
<![CDATA[
<?php
// only allow one connection to a server
Mongo::setPoolSize(1);
// creates one connection to localhost:27017
$m1 = new Mongo();
// attempt to create a second connection to localhost:27017
// only one connection is allowed, so this will throw an exception
$m2 = new Mongo();
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Fatal error: Uncaught exception 'MongoConnectionException' with message 'no more connections in pool' in /path/to/php/script.php:10
Stack trace:
#0 /path/to/php/script.php(10): Mongo->__construct()
#1 {main}
thrown in /path/to/php/script.php on line 10
]]>
</screen>
</example><!-- }}} -->
</para>
</refsect1><!-- }}} -->
<refsect1 role="seealso"><!-- {{{ -->
&reftitle.seealso;
<para>
<simplelist>
<member><function>Mongo::getPoolSize</function></member>
<member><function>Mongo::poolDebug</function></member>
<member>The <link linkend="mongo.connecting">connection</link> documentation.</member>
</simplelist>
</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
-->

98
reference/mongo/mongo/setslaveokay.xml
View file

@ -1,98 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongo.setslaveokay" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Mongo::setSlaveOkay</refname>
<refpurpose>Change slaveOkay setting for this connection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>Mongo::setSlaveOkay</methodname>
<methodparam choice="opt"><type>bool</type><parameter>ok</parameter><initializer>&true;</initializer></methodparam>
</methodsynopsis>
<para>
See <link linkend="mongo.queries">the query section</link> of this manual for
information on distributing reads to secondaries.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>ok</parameter>
</term>
<listitem>
<para>
If reads should be sent to secondary members of a replica set for all
possible queries using this <classname>MongoClient</classname> instance.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the former value of slaveOkay for this instance.
</para>
</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 mongo 1.2.11</entry>
<entry>Emits <constant>E_DEPRECATED</constant> when used.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="seealso"><!-- {{{ -->
&reftitle.seealso;
<simplelist>
<member><xref linkend="mongo.readpreferences" /></member>
<member><methodname>MongoClient::setReadPreference</methodname></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
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
-->

112
reference/mongo/mongo/switchslave.xml
View file

@ -1,112 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongo.switchslave" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Mongo::switchSlave</refname>
<refpurpose>Choose a new secondary for slaveOkay reads</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>string</type><methodname>Mongo::switchSlave</methodname>
<void/>
</methodsynopsis>
<para>
This choses a random secondary for a connection to read from. It is called
automatically by the driver and should not need to be used. It calls
<function>MongoClient::getHosts</function> (to refresh the status of hosts)
and <function>Mongo::getSlave</function> (to get the return value).
</para>
<para>
See <link linkend="mongo.queries">the query section</link> of this manual for
information on distributing reads to secondaries.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The address of the secondary this connection is using for reads. This may be
the same as the previous address as addresses are randomly chosen. It may
return only one address if only one secondary (or only the primary) is
available.
</para>
<para>
For example, if we had a three member replica set with a primary, secondary,
and arbiter this method would always return the address of the secondary.
If the secondary became unavailable, this method would always return the
address of the primary. If the primary also became unavailable, this method
would throw an exception, as an arbiter cannot handle reads.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws a <classname>MongoException</classname> (error code 15) if it is
called on a non-replica-set connection. It will also throw
<classname>MongoException</classname>s if it cannot find anyone (primary or
secondary) to read from (error code 16).
</para>
</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 mongo 1.2.11</entry>
<entry>Emits <constant>E_DEPRECATED</constant> when used.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="seealso"><!-- {{{ -->
&reftitle.seealso;
<simplelist>
<member><xref linkend="mongo.readpreferences" /></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
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
-->

260
reference/mongo/mongobindata.xml
View file

@ -1,260 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<phpdoc:classref xml:id="class.mongobindata" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>The MongoBinData class</title>
<titleabbrev>MongoBinData</titleabbrev>
<partintro>
<warning>
&mongo.alternative.class.note;
<simplelist role="alternatives">
<member><classname>MongoDB\BSON\Binary</classname></member>
</simplelist>
</warning>
<!-- {{{ MongoBinData intro -->
<section xml:id="mongobindata.intro">
&reftitle.intro;
<para>
An object that can be used to store or retrieve binary data from the database.
</para>
<para>
The maximum size of a single object that can be inserted into the database
is 16MB. For data that is larger than this (movies, music, Henry Kissinger's
autobiography), use <classname>MongoGridFS</classname>. For data that is
smaller than 16MB, you may find it easier to embed it within the document
using <classname>MongoBinData</classname>.
</para>
<para>
For example, to embed an image in a document, one could write:
</para>
<example xml:id="mongobindata.intro-example">
<programlisting role="php">
<![CDATA[
<?php
$profile = array(
"username" => "foobity",
"pic" => new MongoBinData(file_get_contents("gravatar.jpg"), MongoBinData::GENERIC),
);
$users->save($profile);
?>
]]>
</programlisting>
</example>
<para>
This class contains a <varname>type</varname> field, which currently gives
no additional functionality in the PHP driver or the database. There are
seven predefined types, which are defined as class constants below. For
backwards compatibility, the PHP driver uses
<constant>MongoBinData::BYTE_ARRAY</constant> as the default; however, this
may change to <constant>MongoBinData::GENERIC</constant> in the future.
Users are encouraged to specify a type in
<function>MongoBinData::__construct</function>.
</para>
</section>
<!-- }}} -->
<section xml:id="mongobindata.synopsis">
&reftitle.classsynopsis;
<!-- {{{ Synopsis -->
<classsynopsis>
<ooclass><classname>MongoBinData</classname></ooclass>
<!-- {{{ Class synopsis -->
<classsynopsisinfo>
<ooclass>
<classname>MongoBinData</classname>
</ooclass>
</classsynopsisinfo>
<!-- }}} -->
<classsynopsisinfo role="comment">&Constants;</classsynopsisinfo>
<fieldsynopsis>
<modifier>const</modifier>
<type>int</type>
<varname linkend="mongobindata.constants.generic">MongoBinData::GENERIC</varname>
<initializer>0</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>int</type>
<varname linkend="mongobindata.constants.func">MongoBinData::FUNC</varname>
<initializer>1</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>int</type>
<varname linkend="mongobindata.constants.byte_array">MongoBinData::BYTE_ARRAY</varname>
<initializer>2</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>int</type>
<varname linkend="mongobindata.constants.uuid">MongoBinData::UUID</varname>
<initializer>3</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>int</type>
<varname linkend="mongobindata.constants.uuid_rfc4122">MongoBinData::UUID_RFC4122</varname>
<initializer>4</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>int</type>
<varname linkend="mongobindata.constants.md5">MongoBinData::MD5</varname>
<initializer>5</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>int</type>
<varname linkend="mongobindata.constants.custom">MongoBinData::CUSTOM</varname>
<initializer>128</initializer>
</fieldsynopsis>
<classsynopsisinfo role="comment">Fields</classsynopsisinfo>
<fieldsynopsis>
<modifier>public</modifier>
<type>string</type>
<varname>bin</varname>
</fieldsynopsis>
<fieldsynopsis>
<modifier>public</modifier>
<type>int</type>
<varname>type</varname>
<initializer>2</initializer>
</fieldsynopsis>
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongobindata')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
</classsynopsis>
<!-- }}} -->
</section>
<!-- {{{ MongoBinData constants -->
<section>
&reftitle.constants;
<section xml:id="mongobindata.constants.types">
<title>Binary Data Types</title>
<variablelist>
<varlistentry xml:id="mongobindata.constants.generic">
<term><constant>MongoBinData::GENERIC</constant></term>
<listitem>
<simpara>
Generic binary data.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongobindata.constants.func">
<term><constant>MongoBinData::FUNC</constant></term>
<listitem>
<simpara>
Function.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongobindata.constants.byte_array">
<term><constant>MongoBinData::BYTE_ARRAY</constant></term>
<listitem>
<simpara>
Generic binary data (deprecated in favor of
<constant>MongoBinData::GENERIC</constant>).
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongobindata.constants.uuid">
<term><constant>MongoBinData::UUID</constant></term>
<listitem>
<simpara>
Universally unique identifier (deprecated in favor of
<constant>MongoBinData::UUID_RFC4122</constant>).
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongobindata.constants.uuid_rfc4122">
<term><constant>MongoBinData::UUID_RFC4122</constant></term>
<listitem>
<simpara>
Universally unique identifier (according to
<link xlink:href="&url.rfc;4122">RFC 4122</link>).
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongobindata.constants.md5">
<term><constant>MongoBinData::MD5</constant></term>
<listitem>
<simpara>
MD5.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongobindata.constants.custom">
<term><constant>MongoBinData::CUSTOM</constant></term>
<listitem>
<simpara>
User-defined type.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<!-- }}} -->
<simplesect role="changelog">
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>1.5.0</entry>
<entry>
Added <constant>MongoBinData::GENERIC</constant> and
<constant>MongoBinData::UUID_RFC4122</constant> constants.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</simplesect>
</partintro>
&reference.mongo.entities.mongobindata;
</phpdoc:classref>
<!-- 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
-->

130
reference/mongo/mongobindata/construct.xml
View file

@ -1,130 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongobindata.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoBinData::__construct</refname>
<refpurpose>Creates a new binary data object</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
<sidebar>
&mongo.alternative.method.note;
<simplelist role="alternatives">
<member><methodname>MongoDB\BSON\Binary::__construct</methodname></member>
</simplelist>
</sidebar>
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <methodname>MongoBinData::__construct</methodname>
<methodparam><type>string</type><parameter>data</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>type</parameter><initializer>0</initializer></methodparam>
</methodsynopsis>
<para>
Creates a new binary data object.
</para>
<para>
There are seven types of binary data currently recognized by the BSON spec,
which are defined as
<link linkend="mongobindata.constants.types">class constants</link>. For
backwards compatibility, the PHP driver uses
<constant>MongoBinData::BYTE_ARRAY</constant> as the default; however, this
may change to <constant>MongoBinData::GENERIC</constant> in the future.
Users are encouraged to specify a type instead of relying on the default.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>data</parameter>
</term>
<listitem>
<para>
Binary data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>type</parameter>
</term>
<listitem>
<para>
Data type.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a new binary data object.
</para>
</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 mongo 1.5.0</entry>
<entry>
The default changed from <literal>2</literal>
(<constant>MongoBinData::BYTE_ARRAY</constant>) to
<literal>0</literal> (<constant>MongoBinData::GENERIC</constant>).
</entry>
</row>
<row>
<entry>PECL mongo 1.2.11</entry>
<entry>
Emits <constant>E_DEPRECATED</constant> when the second argument is not
used. The default value for <parameter>type</parameter> may change in
the near future.
</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
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
-->

60
reference/mongo/mongobindata/tostring.xml
View file

@ -1,60 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongobindata.tostring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoBinData::__toString</refname>
<refpurpose>The string representation of this binary data object</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
<sidebar>
&mongo.alternative.method.note;
<simplelist role="alternatives">
<member><methodname>MongoDB\BSON\Binary::getData</methodname></member>
</simplelist>
</sidebar>
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>string</type><methodname>MongoBinData::__toString</methodname>
<void />
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the string "&lt;Mongo Binary Data&gt;". To access the contents of a
<classname>MongoBinData</classname>, use the <literal>bin</literal> field.
</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
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
-->

297
reference/mongo/mongoclient.xml
View file

@ -1,297 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<phpdoc:classref xml:id="class.mongoclient" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>The MongoClient class</title>
<titleabbrev>MongoClient</titleabbrev>
<partintro>
<!-- {{{ MongoClient intro -->
<warning>
&mongo.alternative.class.note;
<simplelist role="alternatives">
<member><classname>MongoDB\Driver\Manager</classname></member>
</simplelist>
</warning>
<section xml:id="mongoclient.intro">
&reftitle.intro;
<para>
A connection manager for PHP and MongoDB.
</para>
<para>
This class is used to create and manage connections. A typical use is:
<example xml:id="mongoclient.intro-example">
<title><classname>MongoClient</classname> basic usage</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient(); // connect
$db = $m->foo; // get the database named "foo"
?>
]]>
</programlisting>
</example>
</para>
<para>
See <function>MongoClient::__construct</function> and the section on
<link linkend="mongo.connecting">connecting</link> for more information
about creating connections.
</para>
</section>
<!-- }}} -->
<section xml:id="mongoclient.synopsis">
&reftitle.classsynopsis;
<!-- {{{ Synopsis -->
<classsynopsis>
<ooclass><classname>MongoClient</classname></ooclass>
<!-- {{{ Class synopsis -->
<classsynopsisinfo>
<ooclass>
<classname>MongoClient</classname>
</ooclass>
</classsynopsisinfo>
<!-- }}} -->
<classsynopsisinfo role="comment">&Constants;</classsynopsisinfo>
<fieldsynopsis>
<modifier>const</modifier>
<type>string</type>
<varname linkend="mongoclient.constants.version">MongoClient::VERSION</varname>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>string</type>
<varname linkend="mongoclient.constants.defaulthost">MongoClient::DEFAULT_HOST</varname>
<initializer>"localhost"</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>int</type>
<varname linkend="mongoclient.constants.defaultport">MongoClient::DEFAULT_PORT</varname>
<initializer>27017</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>string</type>
<varname linkend="mongoclient.constants.rpprimary">MongoClient::RP_PRIMARY</varname>
<initializer>"primary"</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>string</type>
<varname linkend="mongoclient.constants.rpprimarypreferred">MongoClient::RP_PRIMARY_PREFERRED</varname>
<initializer>"primaryPreferred"</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>string</type>
<varname linkend="mongoclient.constants.rpsecondary">MongoClient::RP_SECONDARY</varname>
<initializer>"secondary"</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>string</type>
<varname linkend="mongoclient.constants.rpsecondary">MongoClient::RP_SECONDARY_PREFERRED</varname>
<initializer>"secondaryPreferred"</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>string</type>
<varname linkend="mongoclient.constants.rpsecondary">MongoClient::RP_NEAREST</varname>
<initializer>"nearest"</initializer>
</fieldsynopsis>
<classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
<fieldsynopsis>
<modifier>public</modifier>
<type>bool</type>
<varname linkend="mongoclient.props.connected">connected</varname>
<initializer>&false;</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>public</modifier>
<type>string</type>
<varname linkend="mongoclient.props.status">status</varname>
<initializer>&null;</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>protected</modifier>
<type>string</type>
<varname>server</varname>
<initializer>&null;</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>protected</modifier>
<type>bool</type>
<varname>persistent</varname>
<initializer>&null;</initializer>
</fieldsynopsis>
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongoclient')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[1])" />
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongoclient')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
</classsynopsis>
<!-- }}} -->
</section>
<!-- Mongo constants -->
<section xml:id="mongoclient.constants">
&reftitle.constants;
<section xml:id="mongoclient.constants.types">
<title>MongoClient Constants</title>
<variablelist>
<varlistentry xml:id="mongoclient.constants.version">
<term><constant>MongoClient::VERSION</constant></term>
<listitem>
<simpara>
PHP driver version. May be suffixed with "dev", "+" or "-" if it is
in-between versions.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongoclient.constants.defaulthost">
<term><constant>MongoClient::DEFAULT_HOST</constant></term>
<listitem>
<simpara>
Host to connect to if no host is given.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongoclient.constants.defaultport">
<term><constant>MongoClient::DEFAULT_PORT</constant></term>
<listitem>
<simpara>
Port to connect to if no port is given.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongoclient.constants.rpprimary">
<term><constant>MongoClient::RP_PRIMARY</constant></term>
<listitem>
<simpara>
<link linkend="mongo.readpreferences">Read preference</link> for the
primary replica set member.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongoclient.constants.rpprimarypreferred">
<term><constant>MongoClient::RP_PRIMARY_PREFERRED</constant></term>
<listitem>
<simpara>
<link linkend="mongo.readpreferences">Read preference</link> for
preferring the primary replica set member.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongoclient.constants.rpsecondary">
<term><constant>MongoClient::RP_SECONDARY</constant></term>
<listitem>
<simpara>
<link linkend="mongo.readpreferences">Read preference</link> for a
secondary replica set member.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongoclient.constants.rpsecondarypreferred">
<term><constant>MongoClient::RP_SECONDARY_PREFERRED</constant></term>
<listitem>
<simpara>
<link linkend="mongo.readpreferences">Read preference</link> for
preferring a secondary replica set member.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongoclient.constants.rpnearest">
<term><constant>MongoClient::RP_NEAREST</constant></term>
<listitem>
<simpara>
<link linkend="mongo.readpreferences">Read preference</link> for the
nearest replica set member.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="mongoclient.fields">
<title>Fields</title>
<variablelist>
<varlistentry xml:id="mongoclient.props.connected">
<term><varname>connected</varname></term>
<listitem>
<para>
This property will be set to &true; if we have a open connection to
the database, &false; otherwise. If the connection is to a replica set,
this property will only be &true; if the driver has a connection to a
node matching the current read preference. This property does not take
authentication into account.
</para>
<para>
This property is <emphasis>deprecated</emphasis> since version 1.5.0.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="mongoclient.props.status">
<term><varname>status</varname></term>
<listitem>
<para>
This property is no longer used and will be set to &null; In driver
versions 1.1.x and earlier, this may be set to a string value (e.g.
<literal>"recycled"</literal>, <literal>"new"</literal>) when persistent
connections are used.
</para>
<para>
This property is <emphasis>deprecated</emphasis> since version 1.5.0.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section role="seealso" xml:id="mongoclient.seealso">
&reftitle.seealso;
<simplelist>
<member><xref linkend="mongo.readpreferences" /></member>
<member><xref linkend="mongo.writeconcerns" /></member>
<member><xref linkend="mongo.connecting" /></member>
<member>MongoDB core docs on <link xlink:href="&url.mongodb.dochub.connections;">connecting</link></member>
</simplelist>
</section>
<!-- }}} -->
</partintro>
&reference.mongo.entities.mongoclient;
</phpdoc:classref>
<!-- 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
-->

175
reference/mongo/mongoclient/close.xml
View file

@ -1,175 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoclient.close" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoClient::close</refname>
<refpurpose>Closes this connection</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
<sidebar>
&mongo.noalternative.method.note;
</sidebar>
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>MongoClient::close</methodname>
<methodparam choice="opt"><type class="union"><type>bool</type><type>string</type></type><parameter>connection</parameter></methodparam>
</methodsynopsis>
<para>
The <function>MongoClient::close</function> method forcefully closes a
connection to the database, even if persistent connections are being used.
You should <emphasis>never</emphasis> have to do this under normal
circumstances.
</para>
<para>
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>connection</parameter>
</term>
<listitem>
<para>
If connection is not given, or &false; then connection that would be
selected for writes would be closed. In a single-node configuration,
that is then the whole connection, but if you are connected to a
replica set, close() will <emphasis>only</emphasis> close the
connection to the primary server.
</para>
<para>
If connection is &true; then all connections as known by the connection
manager will be closed. This can include connections that are not
referenced in the connection string used to create the object that
you are calling close on.
</para>
<para>
If connection is a string argument, then it will only close the
connection identified by this hash. Hashes are identifiers for a
connection and can be obtained by calling
<function>MongoClient::getConnections</function>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns if the connection was successfully closed.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoClient::close</function> example</title>
<para>This example demonstrates how to selectively close all connections
for secondaries only.</para>
<programlisting role="php">
<![CDATA[
<?php
// Connect to a replicaset
$a = new MongoClient("mongodb://whisky:13000/?replicaset=seta");
$connections = $a->getConnections();
foreach ( $connections as $con )
{
// Loop over all the connections, and when the type is "SECONDARY"
// we close the connection
if ( $con['connection']['connection_type_desc'] == "SECONDARY" )
{
echo "Closing '{$con['hash']}': ";
$closed = $a->close( $con['hash'] );
echo $closed ? "ok" : "failed", "\n";
}
}
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Closing 'whisky:13001;X;4948': ok
]]>
</screen>
</example>
</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 mongo 1.3.0</entry>
<entry>
<para>
The <parameter>connection</parameter> parameter to this function was
added in 1.3.0. Before that, only the write connection would be
closed by this method.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.2.0</entry>
<entry>
<para>
Before version 1.2.0 the driver would not use persistent connections
by default, and all connections would be closed as soon as a MongoDB
connection went out if scope. Since version 1.2.0 this is no longer
the case and it is a bad idea to call close as you might end up
overloading the server with connections under high load.
</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>MongoClient::getConnections</function></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
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
-->

63
reference/mongo/mongoclient/connect.xml
View file

@ -1,63 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoclient.connect" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoClient::connect</refname>
<refpurpose>Connects to a database server</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
<sidebar>
&mongo.noalternative.method.note;
</sidebar>
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>MongoClient::connect</methodname>
<void/>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
If the connection was successful.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoConnectionException</classname> if it fails to connect
to the database.
</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
-->

855
reference/mongo/mongoclient/construct.xml
View file

@ -1,855 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoclient.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoClient::__construct</refname>
<refpurpose>Creates a new database connection object</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
<sidebar>
&mongo.alternative.method.note;
<simplelist role="alternatives">
<member><methodname>MongoDB\Driver\Manager::__construct</methodname></member>
</simplelist>
</sidebar>
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<constructorsynopsis>
<modifier>public</modifier> <methodname>MongoClient::__construct</methodname>
<methodparam choice="opt"><type>string</type><parameter>server</parameter><initializer>"mongodb://localhost:27017"</initializer></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array("connect" => &true;)</initializer></methodparam>
<methodparam choice="opt"><type>array</type><parameter>driver_options</parameter></methodparam>
</constructorsynopsis>
<para>
If no parameters are passed, this connects to "localhost:27017" (or whatever
was specified in php.ini for
<link linkend="ini.mongo.default-host">mongo.default_host</link> and
<link linkend="ini.mongo.default-port">mongo.default_port</link>).
</para>
<para>
<parameter>server</parameter> should have the form:
<programlisting role="txt">
<![CDATA[
mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
]]>
</programlisting>
</para>
<para>
The connection string always starts with <literal>mongodb://</literal>, to
indicate it is a connection string in this form.
</para>
<para>If <literal>username</literal> and <literal>password</literal>
are specified, the constructor will attempt to authenticate the connection
with the database before returning. Username and password are optional
and must be followed by an <literal>@</literal>, if specified.
</para>
<para>
At least one host must be given (port optional, always defaulting to 27017)
and as many hosts as desired may be connected to. Host names are
comma-separated and the constructor will return successfully if it connected
to at least one host. If it could not connect to any of the hosts, it will
throw a <classname>MongoConnectionException</classname>. Please see the
<link linkend="mongo.connecting.rs">Replica Sets</link> section for
information on how to connect to Replica Sets.
</para>
<para>
If you specified a username and password, you may specify a database to
authenticate with. If <literal>db</literal> is not specified, "admin" will
be used.
</para>
<para>
An optional query string may be used to specify extra options. The same
options are supported through the <parameter>options</parameter> array as
well, and are therefore redescribed there. See the <link
linkend="mongo.mongoclient.construct.examples">examples below</link> on
how to set those options.
</para>
<para>
One part of the options governs how the driver reads from secondary nodes
in a replica set environment. Extra information on how these read
preferences work is available as well through the <link
linkend="mongo.readpreferences">read preferences</link> documentation page.
</para>
</refsect1>
<refsect1 role="parameters" xml:id="mongo.mongoclient.construct.parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>server</parameter>
</term>
<listitem>
<para>
The server name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>options</parameter>
</term>
<listitem>
<para>
An array of options for the connection. Currently available options
include:
<itemizedlist>
<listitem>
<para>
<literal>"authMechanism"</literal>
</para>
<para>
Available mechanisms are:
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>authMechanism</entry>
<entry>Description</entry>
<entry>Availability</entry>
</row>
</thead>
<tbody>
<row>
<entry>MONGODB-CR</entry>
<entry>Authenticate using Challenge Response mechanism. This is the default value.</entry>
<entry>All MongoDB versions</entry>
</row>
<row>
<entry>MONGODB-X509</entry>
<entry>Authenticates using X509 certificates</entry>
<entry>MongoDB 2.6. Only available when <xref linkend="book.openssl" /> is enabled</entry>
</row>
<row>
<entry>PLAIN</entry>
<entry>Authenticates using unencrypted plain username+password. Must be used over SSL connections. Generally used by MongoDB to login via 3rd party LDAP server</entry>
<entry>MongoDB Enterprise 2.4. The Driver must be compiled against CyrusSASL2</entry>
</row>
<row>
<entry>GSSAPI</entry>
<entry>Authenticates via kerberos systems</entry>
<entry>MongoDB Enterprise 2.4. The Driver must be compiled against CyrusSASL2</entry>
</row>
<row>
<entry>SCRAM-SHA-1</entry>
<entry>Authenticates using SCRAM-SHA-1</entry>
<entry>MongoDB 3.0.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
<listitem>
<para>
<literal>"authSource"</literal>
</para>
<para>
Should be set to the database name where the user is defined it.
</para>
</listitem>
<listitem>
<para>
<literal>"connect"</literal>
</para>
<para>
If the constructor should connect before returning. Default is
&true;. When set to &false; the driver will
<emphasis>automatically</emphasis> connect to the server whenever
it is necessary to do a query. Alternatively, you can run
<function>MongoClient::connect</function> manually.
</para>
<warning>
<para>
This option is not supported through the connection string.
</para>
</warning>
</listitem>
<listitem>
<para>
<literal>"connectTimeoutMS"</literal>
</para>
<para>
How long a connection can take to be opened before timing out in
milliseconds. Defaults to <literal>60000</literal> (60 seconds).
</para>
<para>
If <literal>-1</literal> is specified, no connection timeout will be
applied and PHP will use
<link linkend="ini.default-socket-timeout">default_socket_timeout</link>.
</para>
</listitem>
<listitem>
<para>
<literal>"db"</literal>
</para>
<para>
The database to authenticate against can be specified here, instead of
including it in the host list. This overrides a database given in the
host list.
</para>
</listitem>
<listitem>
<para>
<literal>"fsync"</literal>
</para>
<para>
When <literal>"fsync"</literal> is set, all write operations will
block until the database has flushed the changes to disk. This makes
the write operations slower, but it guarantees that writes have
succeeded and that the operations can be recovered in case of total
system failure.
</para>
<para>
If the MongoDB server has journaling enabled, this option is identical
to <emphasis>"journal"</emphasis>. If journaling is not enabled, this
option ensures that write operations will be synced to database files
on disk.
</para>
<note>
<simpara>
If journaling is enabled, users are strongly encouraged to use the
<literal>"journal"</literal> option instead of
<literal>"fsync"</literal>. Do not use <literal>"fsync"</literal> and
<literal>"journal"</literal> simultaneously, as that will result in
an error.
</simpara>
</note>
</listitem>
<listitem>
<para>
<literal>"journal"</literal>
</para>
<para>
When <literal>"journal"</literal> is set, all write operations will
block until the database has flushed the changes to the journal on
disk. This makes the write operations slower, but it guarantees that
writes have succeeded and that the operations can be recovered in case
of total system failure.
</para>
<note>
<simpara>
If this option is used and journaling is disabled, MongoDB 2.6+ will
raise an error and the write will fail; older server versions will
simply ignore the option.
</simpara>
</note>
</listitem>
<listitem>
<para>
<literal>"gssapiServiceName"</literal>
</para>
<para>
Sets the <link xlink:href="&url.mongodb.docs.kerberos.service-principal;">Kerberos service principal</link>. Only applicable when authMechanism=GSSAPI. Defaults to "mongodb".
</para>
</listitem>
<listitem>
<para>
<literal>"password"</literal>
</para>
<para>
The password can be specified here, instead of including it in the
host list. This is especially useful if a password has a "@" in it.
This overrides a password set in the host list.
</para>
</listitem>
<listitem>
<para>
<literal>"readPreference"</literal>
</para>
<para>
Specifies the read preference type. Read preferences provide you
with control from which secondaries data can be read from.
</para>
<para>
Allowed values are: <constant>MongoClient::RP_PRIMARY</constant>,
<constant>MongoClient::RP_PRIMARY_PREFERRED</constant>,
<constant>MongoClient::RP_SECONDARY</constant>,
<constant>MongoClient::RP_SECONDARY_PREFERRED</constant> and
<constant>MongoClient::RP_NEAREST</constant>.
</para>
<para>
See the documentation on <link linkend="mongo.readpreferences">read
preferences</link> for more information.
</para>
</listitem>
<listitem>
<para>
<literal>"readPreferenceTags"</literal>
</para>
<para>
Specifies the read preference tags as an array of strings. Tags can be
used in combination with the <literal>readPreference</literal> option
to further control which secondaries data might be read from.
</para>
<para>
See the documentation on <link linkend="mongo.readpreferences">read
preferences</link> for more information.
</para>
</listitem>
<listitem>
<para>
<literal>"replicaSet"</literal>
</para>
<para>
The name of the replica set to connect to. If this is given, the
primary will be automatically be determined. This means that the
driver may end up connecting to a server that was not even listed.
See the replica set example below for details.
</para>
</listitem>
<listitem>
<para>
<literal>"secondaryAcceptableLatencyMS"</literal>
</para>
<para>
When reading from a secondary (using ReadPreferences), do not read from secondaries known to be more then
<literal>secondaryAcceptableLatencyMS</literal> away from us. Defaults to <literal>15</literal>
</para>
</listitem>
<listitem>
<para>
<literal>"socketTimeoutMS"</literal>
</para>
<para>
How long a socket operation (read or write) can take before timing out
in milliseconds. Defaults to <literal>30000</literal> (30 seconds).
</para>
<para>
If <literal>-1</literal> is specified, socket operations may block
indefinitely. This option may also be set on a per-operation basis
using <methodname>MongoCursor::timeout</methodname> for queries or the
<literal>"socketTimeoutMS"</literal> option for write methods.
</para>
<note>
<simpara>
This is a client-side timeout. If a write operation times out, there
is no way to know if the server actually handled the write or not, as
a <classname>MongoCursorTimeoutException</classname> will be thrown
in lieu of returning a write result.
</simpara>
</note>
</listitem>
<listitem>
<para>
<literal>"ssl"</literal>
</para>
<para>
A boolean to specify whether you want to enable SSL for the
connections to MongoDB. Extra options such as certificates
can be set with <xref linkend="context.ssl" />.
</para>
</listitem>
<listitem>
<para>
<literal>"username"</literal>
</para>
<para>
The username can be specified here, instead of including it in the
host list. This is especially useful if a username has a ":" in it.
This overrides a username set in the host list.
</para>
</listitem>
<listitem>
<para>
<literal>"w"</literal>
</para>
<para>
The <literal>w</literal> option specifies the
<link linkend="mongo.writeconcerns">Write Concern</link> for the driver,
which determines how long the driver blocks when writing. The
default value is <literal>1</literal>.
</para>
<para>
This option is applicable when connecting to both single servers and
replica sets. A positive value controls how <emphasis>many</emphasis>
nodes must acknowledge the write instruction before the driver
continues. A value of <literal>1</literal> would require the single
server or primary (in a replica set) to acknowledge the write
operation. A value of <literal>3</literal> would cause the driver to
block until the write has been applied to the primary as well as two
secondary servers (in a replica set).
</para>
<para>
A string value is used to control which tag sets are taken into
account for write concerns. <literal>"majority"</literal> is special
and ensures that the write operation has been applied to the majority
(more than 50%) of the participating nodes.
</para>
</listitem>
<listitem>
<para>
<literal>"wTimeoutMS"</literal>
</para>
<para>
This option specifies the time limit, in milliseconds, for
<link linkend="mongo.writeconcerns">write concern</link>
acknowledgement. It is only applicable for write operations where
<literal>"w"</literal> is greater than <literal>1</literal>, as the
timeout pertains to replication. If the write concern is not satisfied
within the time limit, a <classname>MongoCursorException</classname>
will be thrown. A value of <literal>0</literal> may be specified to
block indefinitely. The default value is <literal>10000</literal>
(ten seconds).
</para>
</listitem>
</itemizedlist>
</para>
<para>
The following options are deprecated and should no longer be used:
<itemizedlist>
<listitem>
<para>
<literal>"slaveOkay"</literal>
</para>
<para>
Deprecated. Please use the <link linkend="mongo.readpreferences">read
preference</link> options.
</para>
</listitem>
<listitem>
<para>
<literal>"timeout"</literal>
</para>
<para>
Deprecated alias for <literal>"connectTimeoutMS"</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>"wTimeout"</literal>
</para>
<para>
Deprecated alias for <literal>"wTimeoutMS"</literal>.
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>driver_options</parameter>
</term>
<listitem>
<para>
An array of options for the MongoDB driver. Options include setting
connection <link linkend="mongo.connecting.context.ssl">context options for SSL</link>
or <link linkend="context.mongodb">logging callbacks</link>.
<itemizedlist>
<listitem>
<para>
<literal>"context"</literal>
</para>
<para>
The Stream Context to attach to all new connections. This allows you
for example to configure SSL certificates and are described at
<link linkend="context.ssl">SSL context options</link>. See the
<link linkend="mongo.connecting.context.ssl">Connecting over SSL</link> tutorial.
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a new database connection object.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoConnectionException</classname> if it tries and fails
to connect to the database for all hostnames given. It will also throw a
<classname>MongoConnnectionException</classname> if an invalid username or
password is given. See <classname>MongoConnectionException</classname>
documentation for common exceptions and their causes.
</para>
</refsect1>
<refsect1 role="examples" xml:id="mongo.mongoclient.construct.examples">
&reftitle.examples;
<example>
<title><function>MongoClient::__construct</function> replica set example</title>
<para>
This example shows how to connect the driver to a replica set. It assumes
that there is a set of three servers: sf1.example.com, sf2.example.com, and
ny1.example.com. The primary could be any one of these servers.
</para>
<programlisting role="php">
<![CDATA[
<?php
// pass a comma-separated list of server names to the constructor
// Note that we don't need to pass in all the members of the replicaset, the driver
// will derive the full list.
$m1 = new MongoClient("mongodb://sf2.example.com,ny1.example.com", array("replicaSet" => "myReplSet"));
?>
]]>
</programlisting>
<para>
If the current primary fails, the driver will figure out which secondary
server became the new primary and automatically start using that connection.
Automatic failover will not work correctly if <literal>replicaSet</literal>
is not specified.
</para>
<para>
At least one seed in the seed list must be up for the driver to connect to
the replica set.
</para>
<para>
If you include seeds from two separate replica sets, behavior is undefined.
</para>
<para>See the
<link xlink:href="&url.mongodb.dochub.rs;">core documentation</link> on
replica sets for more information.
</para>
</example>
<example>
<title>Connecting to a domain socket</title>
<para>
In version 1.0.9+, you can use a UNIX domain socket to connect to an
instance of MongoDB running locally. This should be slightly faster than
using a network connection.
</para>
<para>
In version 1.5.0, the MongoDB server automatically opens a socket at
/tmp/mongodb-&lt;port&gt;.sock. You can connect to this by specifying the
path in your connection string:
</para>
<programlisting role="php">
<![CDATA[
<?php
// MongoDB server running locally on port 20000
$m = new MongoClient("mongodb:///tmp/mongodb-20000.sock");
?>
]]>
</programlisting>
<para>
You can combine this with any other connections you'd like:
</para>
<programlisting role="php">
<![CDATA[
<?php
// try to connect to the domain socket, fall back to localhost connection
$m = new MongoClient("mongodb:///tmp/mongodb-27017.sock,localhost:27017");
?>
]]>
</programlisting>
</example>
<example>
<title><function>MongoClient::__construct</function> authentication example</title>
<para>
A user must exist in the admin database before attempting to use
authentication. You can create one with the Mongo shell by running:
</para>
<programlisting role="shell">
<![CDATA[
> use admin
switched to db admin
> db.addUser("testUser", "testPass");
{
"_id" : ObjectId("4b21272fd9ab21611d19095c"),
"user" : "testUser",
"pwd" : "03b9b27e0abf1865e2f6fcbd9845dd59"
}
>
]]>
</programlisting>
<para>
After creating a user with, in this case, username "testUser" and password
"testPass", you can create an authenticated connection:
</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient("mongodb://testUser:testPass@localhost");
?>
]]>
</programlisting>
</example>
<example>
<title><function>MongoClient::__construct</function> read preference example</title>
<programlisting role="php">
<![CDATA[
<?php
// Prefer the nearest server in the "east" data center
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
?>
]]>
</programlisting>
<para>
See the <link linkend="mongo.readpreferences">read preferences</link>
section of this manual for further information.
</para>
</example>
<example>
<title><function>MongoClient::__construct</function> options example</title>
<para>
Options can be passed both through the query string in the connection
string, or as an array passed as second argument to the constructor.
</para>
<para>
Here we set the journal option to true and readPreference to secondary
preferred as default for all write operations:
</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient("mongodb://localhost/?journal=true&readPreference=secondary");
?>
]]>
</programlisting>
<para>
And now we do the same, but as an options array:
</para>
<programlisting role="php">
<![CDATA[
<?php
$options = array(
'journal' => true,
'readPreference' => 'secondary',
);
$m = new MongoClient("mongodb://localhost/", $options);
?>
]]>
</programlisting>
</example>
<example>
<title><function>MongoClient::__construct</function> read preference example</title>
<programlisting role="php">
<![CDATA[
<?php
// Prefer the nearest server in the "east" data center
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
?>
]]>
</programlisting>
<para>
See the <link linkend="mongo.readpreferences">read preferences</link>
section of this manual for further information.
</para>
</example>
</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 mongo 1.6.0</entry>
<entry>
<para>
Added support for <literal>"SCRAM-SHA-1"</literal> in
<literal>"authMechanism"</literal> option.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.5.0</entry>
<entry>
<para>
Added <literal>"authMechanism"</literal>, <literal>"gssapiServiceName"</literal>, and <literal>"secondaryAcceptableLatencyMS"</literal>.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.4.0</entry>
<entry>
<para>
Added <literal>"ssl"</literal> option and support for
<link linkend="mongo.connecting.ssl">connecting over SSL</link>.
</para>
<para>
Added <literal>"wTimeoutMS"</literal> option, which replaces
<literal>"wTimeout"</literal>.
</para>
<para>
Emits <constant>E_DEPRECATED</constant> when
<literal>"slaveOkay"</literal> or <literal>"timeout"</literal> is used.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.5.0</entry>
<entry>
<para>
Added <literal>"authSource"</literal>.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.3.4</entry>
<entry>
<para>
Added <literal>"connectTimeoutMS"</literal> and
<literal>"socketTimeoutMS"</literal> options.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.3.0</entry>
<entry>
<para>
Added <literal>"readPreference"</literal>,
<literal>"readPreferenceTags"</literal>, <literal>"w"</literal>, and
<literal>"wTimeout"</literal> options.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.2.0</entry>
<entry>
<para>
Added <literal>"username"</literal> and <literal>"password"</literal>
options.
</para>
<para>
Removed <literal>"persist"</literal> option, as all connections are
now persistent. It can still be used, but it doesn't affect anything.
</para>
<variablelist>
<varlistentry>
<term>
<parameter>"persist"</parameter>
</term>
<listitem>
<para>
If the connection should be persistent. If set, the connection will
be persistent. The string representation of the value is used as an
ID for the connection, so two instances of
<classname>MongoClient</classname> that are initialized with
<literal>array("persist" => "foobar")</literal> will share the same
database connection, whereas an instance initialized with
<literal>array("persist" => "barbaz")</literal> will use a different
database connection.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The <literal>"replicaSet"</literal> option now takes a string, not a
boolean.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.0.9</entry>
<entry>Added <literal>"replicaSet"</literal> option.</entry>
</row>
<row>
<entry>PECL mongo 1.0.2</entry>
<entry>
<para>
Changed constructor to take an array of options. Pre-1.0.2, the
constructor took the following parameters:
</para>
<variablelist>
<varlistentry>
<term>
<parameter>server</parameter>
</term>
<listitem>
<para>
The server name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>connect</parameter>
</term>
<listitem>
<para>
Optional boolean parameter specifying if the constructor should
connect to the database before returning. Defaults to &true;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>persistent</parameter>
</term>
<listitem>
<para>
If the connection should be persistent.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>paired</parameter>
</term>
<listitem>
<para>
If the connection should be paired.
</para>
</listitem>
</varlistentry>
</variablelist>
</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
-->

76
reference/mongo/mongoclient/dropdb.xml
View file

@ -1,76 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoclient.dropdb" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoClient::dropDB</refname>
<refpurpose>Drops a database [deprecated]</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
&mongo.alternative.phplib.note;
<simplelist>
<member><link xlink:href="&url.mongodb.library.apidocs;/method/MongoDBClient-dropDatabase/">MongoDB\Client::dropDatabase()</link></member>
</simplelist>
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoClient::dropDB</methodname>
<methodparam><type>mixed</type><parameter>db</parameter></methodparam>
</methodsynopsis>
<warning>
<title>Deprecated</title>
<para>
Use <function>MongoDB::drop</function> instead.
</para>
</warning>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>db</parameter>
</term>
<listitem>
<para>
The database to drop. Can be a MongoDB object or the name of the database.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the database response.
</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
-->

94
reference/mongo/mongoclient/get.xml
View file

@ -1,94 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoclient.get" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoClient::__get</refname>
<refpurpose>Gets a database</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
&mongo.alternative.phplib.note;
<simplelist>
<member><link xlink:href="&url.mongodb.library.apidocs;/method/MongoDBClient__get/">MongoDB\Client::__get()</link></member>
</simplelist>
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>MongoDB</type><methodname>MongoClient::__get</methodname>
<methodparam><type>string</type><parameter>dbname</parameter></methodparam>
</methodsynopsis>
<para>
This is the cleanest way of getting a database. If the database name has any
special characters, <function>MongoClient::selectDB</function> will need to
be used; however, this should be sufficient for most cases.
<programlisting role="php">
<![CDATA[
<?php
$mongo = new MongoClient();
// the following two lines are equivalent
$db = $mongo->selectDB("foo");
$db = $mongo->foo;
?>
]]>
</programlisting>
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>dbname</parameter>
</term>
<listitem>
<para>
The database name.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a new db object.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws a generic exception if the database name is invalid.
</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
-->

117
reference/mongo/mongoclient/getconnections.xml
View file

@ -1,117 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoclient.getconnections" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoClient::getConnections</refname>
<refpurpose>Return info about all open connections</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
&mongo.noalternative.method.note;
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <modifier>static</modifier> <type>array</type><methodname>MongoClient::getConnections</methodname>
<void />
</methodsynopsis>
<para>
Returns an array of all open connections, and information about each of the
servers
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
An <type>array</type> of open connections.
</para>
</refsect1>
<refsect1 role="examples"><!-- {{{ -->
&reftitle.examples;
<example xml:id="mongoclient-getconnections.example.basic"><!-- {{{ -->
<title><methodname>MongoClient::getConnections</methodname> example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient;
var_dump($m->getConnections());
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
array(1) {
[0]=>
array(3) {
["hash"]=>
string(26) "localhost:27017;-;X;56052"
["server"]=>
array(3) {
["host"]=>
string(10) "localhost"
["port"]=>
int(27017)
["pid"]=>
int(56052)
}
["connection"]=>
array(8) {
["last_ping"]=>
int(1354076401)
["last_ismaster"]=>
int(0)
["ping_ms"]=>
int(0)
["connection_type"]=>
int(1)
["connection_type_desc"]=>
string(10) "STANDALONE"
["max_bson_size"]=>
int(16777216)
["tag_count"]=>
int(0)
["tags"]=>
array(0) {
}
}
}
}
]]>
</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
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
-->

159
reference/mongo/mongoclient/gethosts.xml
View file

@ -1,159 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoclient.gethosts" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoClient::getHosts</refname>
<refpurpose>Updates status for all associated hosts</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
&mongo.alternative.method.note;
<simplelist>
<member><methodname>MongoDB\Driver\Manager::getServers</methodname></member>
</simplelist>
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoClient::getHosts</methodname>
<void/>
</methodsynopsis>
<para>
This method is only useful with a connection to a replica set. It returns
the status of all of the hosts in the set. Without a replica set, it will
just return an array with one element containing the host that you are
connected to.
</para>
<para>
See <link linkend="mongo.queries">the query section</link> of this manual for
information on distributing reads to secondaries.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an array of information about the hosts in the set. Includes each
host's hostname, its health (1 is healthy), its state (1 is primary, 2 is
secondary, 0 is anything else), the amount of time it took to ping the
server, and when the last ping occurred. For example, on a three-member
replica set, it might look something like:
</para>
<screen>
<![CDATA[
array(3) {
["A:27017"]=>
array(4) {
["host"]=>
"A"
["port"]=>
27017
["health"]=>
int(1)
["state"]=>
int(2)
["ping"]=>
int(369)
["lastPing"]=>
int(1309470644)
}
["B:27017"]=>
array(4) {
["host"]=>
"B"
["port"]=>
27017
["health"]=>
int(1)
["state"]=>
int(1)
["ping"]=>
int(139)
["lastPing"]=>
int(1309470644)
}
["C:27017"]=>
array(4) {
["host"]=>
"C"
["port"]=>
27017
["health"]=>
int(1)
["state"]=>
int(2)
["ping"]=>
int(1012)
["lastPing"]=>
int(1309470644)
}
}
]]>
</screen>
</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 mongo 1.2.10</entry>
<entry>
<para>
Support for non-replicasets was added.
</para>
<para>
The returned array elements now also include the
<literal>hostname</literal> and <literal>port</literal>.
</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>MongoClient::getConnections</function></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
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
-->

138
reference/mongo/mongoclient/getreadpreference.xml
View file

@ -1,138 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoclient.getreadpreference" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoClient::getReadPreference</refname>
<refpurpose>Get the read preference for this connection</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
&mongo.noalternative.method.note;
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoClient::getReadPreference</methodname>
<void />
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
&mongo.getreadpreference.returnvalues;
</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 mongo 1.3.3</entry>
<entry>
The return value has changed to be consistent with
<methodname>MongoClient::setReadPreference</methodname>. The
<literal>type</literal> value was changed from a number to a string,
<literal>type_string</literal> was removed, and
<literal>tagsets</literal> now expresses tags as key/value pairs instead
of colon-delimited strings.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><methodname>MongoClient::getReadPreference</methodname> return value example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$m->setReadPreference(MongoClient::RP_SECONDARY, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
array(),
));
var_dump($m->getReadPreference());
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(2) {
["type"]=>
string(9) "secondary"
["tagsets"]=>
array(3) {
[0]=>
array(2) {
["dc"]=>
string(4) "east"
["use"]=>
string(9) "reporting"
}
[1]=>
array(1) {
["dc"]=>
string(7) "west"
}
[2]=>
array(0) {
}
}
}
]]>
</screen>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member>The <link linkend="mongo.readpreferences">read preferences</link> documentation.</member>
<member><function>MongoClient::setReadPreference</function></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
-->

97
reference/mongo/mongoclient/getwriteconcern.xml
View file

@ -1,97 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoclient.getwriteconcern" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoClient::getWriteConcern</refname>
<refpurpose>Get the write concern for this connection</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
&mongo.noalternative.method.note;
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoClient::getWriteConcern</methodname>
<void />
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
&mongo.getwriteconcern.returnvalues;
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><methodname>MongoClient::getWriteConcern</methodname> return value example</title>
<programlisting role="php">
<![CDATA[
<?php
$mc = new MongoClient('mongodb://localhost:27017', array('wTimeoutMS' => 500));
var_dump($mc->getWriteConcern());
$mc->setWriteConcern(1, 1000);
var_dump($mc->getWriteConcern());
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(2) {
["w"]=>
int(1)
["wtimeout"]=>
int(500)
}
array(2) {
["w"]=>
int(1)
["wtimeout"]=>
int(1000)
}
]]>
</screen>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member>The <link linkend="mongo.writeconcerns">write concern</link> documentation.</member>
<member><function>MongoClient::setWriteConcern</function></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
-->

129
reference/mongo/mongoclient/killcursor.xml
View file

@ -1,129 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoclient.killcursor" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoClient::killCursor</refname>
<refpurpose>Kills a specific cursor on the server</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
&mongo.noalternative.method.note;
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>MongoClient::killCursor</methodname>
<methodparam><type>string</type><parameter>server_hash</parameter></methodparam>
<methodparam><type class="union"><type>int</type><type>MongoInt64</type></type><parameter>id</parameter></methodparam>
</methodsynopsis>
<para>
In certain situations it might be needed to kill a cursor on the server.
Usually cursors time out after 10 minutes of inactivity, but it is possible
to create an immortal cursor with
<methodname>MongoCursor::immortal</methodname> that never times out. In
order to be able to kill such an immortal cursor, you can call this
method with the information supplied by
<methodname>MongoCursor::info</methodname>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>server_hash</parameter>
</term>
<listitem>
<para>
The server hash that has the cursor. This can be obtained through
<methodname>MongoCursor::info</methodname>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>id</parameter>
</term>
<listitem>
<para>
The ID of the cursor to kill. You can either supply an <type>int</type>
containing the 64 bit cursor ID, or an object of the
<classname>MongoInt64</classname> class. The latter is necessary on 32
bit platforms (and Windows).
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns &true; if the method attempted to kill a cursor, and &false; if
there was something wrong with the arguments (such as a wrong
<parameter>server_hash</parameter>). The return status does <emphasis>not
reflect</emphasis> where the cursor was actually killed as the server does
not provide that information.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
This method displays a warning if the supplied
<parameter>server_hash</parameter> does not match up with an existing
connection. No attempt to kill a cursor is attempted in that case either.
</para>
</refsect1>
<refsect1 role="examples" xml:id="mongo.mongoclient.killcursor.examples">
&reftitle.examples;
<example>
<title><function>MongoClient::killCursor</function> example</title>
<para>
This example shows how to connect, do a query, obtain the cursor
information and then kill the cursor.
</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$c = $m->testdb->collection;
$cursor = $c->find();
$result = $cursor->next();
// Now the cursor is valid, so we can get the hash and ID out:
$info = $cursor->info();
// Kill the cursor
MongoClient::killCursor( $info['server'], $info['id'] );
?>
]]>
</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
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
-->

102
reference/mongo/mongoclient/listdbs.xml
View file

@ -1,102 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoclient.listdbs" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoClient::listDBs</refname>
<refpurpose>Lists all of the databases available</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
&mongo.alternative.phplib.note;
<simplelist>
<member><link xlink:href="&url.mongodb.library.apidocs;/method/MongoDBClient-listDatabases/">MongoDB\Client::listDatabases()</link></member>
</simplelist>
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoClient::listDBs</methodname>
<void/>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an associative array containing three fields. The first field is
<literal>databases</literal>, which in turn contains an array. Each element
of the array is an associative array corresponding to a database, giving th
database's name, size, and if it's empty. The other two fields are
<literal>totalSize</literal> (in bytes) and <literal>ok</literal>, which is 1
if this method ran successfully.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><methodname>MongoClient::listDBs</methodname> example</title>
<para>
Example demonstrating how to use listDBs and the returned data structure.
</para>
<programlisting role="php">
<![CDATA[
<?php
$mongo = new MongoClient();
$dbs = $mongo->listDBs();
print_r($dbs);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Array
(
[databases] => Array
(
[0] => Array
(
[name] => doctrine
[sizeOnDisk] => 218103808
[empty] =>
)
)
[totalSize] => 218103808
[ok] => 1
)
]]>
</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
-->

106
reference/mongo/mongoclient/selectcollection.xml
View file

@ -1,106 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoclient.selectcollection" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoClient::selectCollection</refname>
<refpurpose>Gets a database collection</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
&mongo.alternative.phplib.note;
<simplelist>
<member><link xlink:href="&url.mongodb.library.apidocs;/method/MongoDBClient-selectCollection/">MongoDB\Client::selectCollection()</link></member>
</simplelist>
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>MongoCollection</type><methodname>MongoClient::selectCollection</methodname>
<methodparam><type>string</type><parameter>db</parameter></methodparam>
<methodparam><type>string</type><parameter>collection</parameter></methodparam>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>db</parameter>
</term>
<listitem>
<para>
The database name.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>collection</parameter>
</term>
<listitem>
<para>
The collection name.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a new collection object.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>Exception</classname> if the database or collection name is invalid.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoClient::selectCollection</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$c1 = $m->selectCollection("foo", "bar.baz");
// which is equivalent to
$c2 = $m->selectDB("foo")->selectCollection("bar.baz");
// $c1 and $c2 now represent the same collection
?>
]]>
</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
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
-->

76
reference/mongo/mongoclient/selectdb.xml
View file

@ -1,76 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoclient.selectdb" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoClient::selectDB</refname>
<refpurpose>Gets a database</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
&mongo.alternative.phplib.note;
<simplelist>
<member><link xlink:href="&url.mongodb.library.apidocs;/method/MongoDBClient-selectDatabase/">MongoDB\Client::selectDatabase()</link></member>
</simplelist>
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>MongoDB</type><methodname>MongoClient::selectDB</methodname>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>name</parameter>
</term>
<listitem>
<para>
The database name.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a new database object.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>Exception</classname> if the database name is invalid.
</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
-->

89
reference/mongo/mongoclient/setreadpreference.xml
View file

@ -1,89 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoclient.setreadpreference" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoClient::setReadPreference</refname>
<refpurpose>Set the read preference for this connection</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
&mongo.noalternative.method.note;
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>MongoClient::setReadPreference</methodname>
<methodparam><type>string</type><parameter>read_preference</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>tags</parameter></methodparam>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&mongo.setreadpreference.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
&mongo.setreadpreference.returnvalues;
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
&mongo.setreadpreference.errors;
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><methodname>MongoClient::setReadPreference</methodname> tag set array syntax example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
// Prefer the nearest server in the "east" data center also used for reporting,
// but fall back to a server in the "west" data center
$m->setReadPreference(MongoClient::RP_NEAREST, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
));
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member>The <link linkend="mongo.readpreferences">read preferences</link> documentation.</member>
<member><function>MongoClient::getReadPreference</function></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
-->

86
reference/mongo/mongoclient/setwriteconcern.xml
View file

@ -1,86 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoclient.setwriteconcern" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoClient::setWriteConcern</refname>
<refpurpose>Set the write concern for this connection</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
&mongo.noalternative.method.note;
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>MongoClient::setWriteConcern</methodname>
<methodparam><type>mixed</type><parameter>w</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>wtimeout</parameter></methodparam>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&mongo.setwriteconcern.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
&mongo.setwriteconcern.returnvalues;
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
&mongo.setwriteconcern.errors;
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><methodname>MongoClient::setWriteConcern</methodname> example</title>
<programlisting role="php">
<![CDATA[
<?php
$mc = new MongoClient('mongodb://rs1.example.com,rs2.example.com');
// Require that the majority of servers in the replica set acknowledge writes
// within three seconds.
$mc->setWriteConcern('majority', 3000);
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member>The <link linkend="mongo.writeconcerns">write concern</link> documentation.</member>
<member><function>MongoClient::getWriteConcern</function></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
-->

52
reference/mongo/mongoclient/tostring.xml
View file

@ -1,52 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoclient.tostring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoClient::__toString</refname>
<refpurpose>String representation of this connection</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
&mongo.noalternative.method.note;
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>string</type><methodname>MongoClient::__toString</methodname>
<void/>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns hostname and port for this connection.
</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
-->

77
reference/mongo/mongocode.xml
View file

@ -1,77 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<phpdoc:classref xml:id="class.mongocode" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>The MongoCode class</title>
<titleabbrev>MongoCode</titleabbrev>
<partintro>
<warning>
&mongo.alternative.class.note;
<simplelist role="alternatives">
<member><classname>MongoDB\BSON\JavaScript</classname></member>
</simplelist>
</warning>
<!-- {{{ MongoId intro -->
<section xml:id="mongocode.intro">
&reftitle.intro;
<para>
Represents JavaScript code for the database.
</para>
<para>
MongoCode objects are composed of two parts: a string of code and an optional scope. The string of code must be valid JavaScript. The scope is a associative array of variable name/value pairs.
</para>
</section>
<!-- }}} -->
<section xml:id="mongocode.synopsis">
&reftitle.classsynopsis;
<!-- {{{ Synopsis -->
<classsynopsis>
<ooclass><classname>MongoCode</classname></ooclass>
<!-- {{{ Class synopsis -->
<classsynopsisinfo>
<ooclass>
<classname>MongoCode</classname>
</ooclass>
</classsynopsisinfo>
<!-- }}} -->
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongocode')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
</classsynopsis>
<!-- }}} -->
</section>
</partintro>
&reference.mongo.entities.mongocode;
</phpdoc:classref>
<!-- 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
-->

137
reference/mongo/mongocode/construct.xml
View file

@ -1,137 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocode.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCode::__construct</refname>
<refpurpose>Creates a new code object</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
<sidebar>
&mongo.alternative.method.note;
<simplelist role="alternatives">
<member><methodname>MongoDB\BSON\JavaScript::__construct</methodname></member>
</simplelist>
</sidebar>
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <methodname>MongoCode::__construct</methodname>
<methodparam><type>string</type><parameter>code</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>scope</parameter><initializer>array()</initializer></methodparam>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>code</parameter>
</term>
<listitem>
<para>
A string of code.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>scope</parameter>
</term>
<listitem>
<para>
The scope to use for the code.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a new code object.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><methodname>MongoCode::__construct</methodname> example</title>
<programlisting role="php">
<![CDATA[
<?php
$code = new MongoCode('function() { '.
'for(i=0;i<10;i++) {'.
'db.foo.update({z : i}, {z : x});'.
'}'.
'return x-1;'.
'}', array("x" => 4));
var_dump($code);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
object(MongoCode)#1 (2) {
["scope"]=>
array(1) {
["x"]=>
int(4)
}
["code"]=>
string(80) "function() { for(i=0;i<10;i++) { db.foo.update({z : i}, {z : x}); } return x-1; }"
}
]]>
</screen>
</example>
<example>
<title>Using <classname>MongoCode</classname> with $where</title>
<para>
This example queries a collection for elements where the 'x' fields is less than $y. Notice that
PHP objects can be passed into the JavaScript scope and that the JavaScript function returns a boolean.
</para>
<programlisting role="php">
<![CDATA[
<?php
$cursor = $collection->find(array('$where' => new MongoCode('function() { return this.x < y; }', array('y'=>$y))));
?>
]]>
</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
-->

83
reference/mongo/mongocode/tostring.xml
View file

@ -1,83 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocode.tostring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCode::__toString</refname>
<refpurpose>Returns this code as a string</refpurpose>
</refnamediv>
<refsynopsisdiv role="soft-deprecation-notice">
<sidebar>
&mongo.noalternative.method.note;
</sidebar>
</refsynopsisdiv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>string</type><methodname>MongoCode::__toString</methodname>
<void/>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
This code, the scope is not returned.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCode::__toString</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$code = new MongoCode('return x;', array("x"=>"hi"));
echo "$code\n";
$code = new MongoCode('function() { for(i=0;i<10;i++) { db.foo.update({x:i}, {x:i+1}); } }');
echo "$code\n";
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
return x;
function() { for(i=0;i<10;i++) { db.foo.update({x:i}, {x:i+1}); } }
]]>
</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
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
-->

175
reference/mongo/mongocollection.xml
View file

@ -1,175 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<phpdoc:classref xml:id="class.mongocollection" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>The MongoCollection class</title>
<titleabbrev>MongoCollection</titleabbrev>
<partintro>
<!-- {{{ Mongocollection intro -->
<section xml:id="mongocollection.intro">
&reftitle.intro;
<para>
Represents a MongoDB collection.
</para>
<para>
Collection names can use any character in the ASCII set. Some valid
collection names are &quot;&quot;, &quot;...&quot;,
&quot;my collection&quot;, and &quot;&#42;&amp;&#35;&#64;&quot;.
</para>
<para>
User-defined collection names cannot contain the $ symbol. There are
certain system collections which use a $ in their names (e.g.,
local.oplog.$main), but it is a reserved character. If you attempt to
create and use a collection with a $ in the name, MongoDB will assert.
</para>
</section>
<!-- }}} -->
<section xml:id="mongocollection.synopsis">
&reftitle.classsynopsis;
<!-- {{{ Synopsis -->
<classsynopsis>
<ooclass><classname>MongoCollection</classname></ooclass>
<!-- {{{ Class synopsis -->
<classsynopsisinfo>
<ooclass>
<classname>MongoCollection</classname>
</ooclass>
</classsynopsisinfo>
<!-- }}} -->
<classsynopsisinfo role="comment">&Constants;</classsynopsisinfo>
<fieldsynopsis>
<modifier>const</modifier>
<type>int</type>
<varname linkend="mongocollection.constants.ascending">MongoCollection::ASCENDING</varname>
<initializer>1</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>int</type>
<varname linkend="mongocollection.constants.descending">MongoCollection::DESCENDING</varname>
<initializer>-1</initializer>
</fieldsynopsis>
<classsynopsisinfo role="comment">Fields</classsynopsisinfo>
<fieldsynopsis>
<modifier>public</modifier>
<type>MongoDB</type>
<varname linkend="mongocollection.props.db">db</varname>
<initializer>&null;</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>public</modifier>
<type>int</type>
<varname linkend="mongocollection.props.w">w</varname>
</fieldsynopsis>
<fieldsynopsis>
<modifier>public</modifier>
<type>int</type>
<varname linkend="mongocollection.props.wtimeout">wtimeout</varname>
</fieldsynopsis>
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongocollection')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
</classsynopsis>
<!-- }}} -->
</section>
<section>
&reftitle.constants;
<variablelist>
<varlistentry xml:id="mongocollection.constants.ascending">
<term><constant>MongoCollection::ASCENDING</constant></term>
<listitem>
<simpara>
Ascending direction for sorts and index creation.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongocollection.constants.descending">
<term><constant>MongoCollection::DESCENDING</constant></term>
<listitem>
<simpara>
Descending direction for sorts and index creation.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Fields</title>
<variablelist>
<varlistentry xml:id="mongocollection.props.db">
<term><varname>db</varname></term>
<listitem>
<para>
The "parent" database for this collection.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="mongocollection.props.w">
<term><varname>w</varname></term>
<listitem>
<para>
The number of servers to replicate a change to before returning success.
Value is inherited from the parent database. The
<classname>MongoDB</classname> class has a more detailed description of
how <literal>w</literal> works.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="mongocollection.props.wtimeout">
<term><varname>wtimeout</varname></term>
<listitem>
<para>
The number of milliseconds to wait for <literal>$this->w</literal>
replications to take place. Value is inherited from the parent database.
The <classname>MongoDB</classname> class has a more detailed description
of how <literal>wtimeout</literal> works.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
&reftitle.seealso;
<para>
MongoDB core docs on <link xlink:href="&url.mongodb.glossary;#term-collection">collections</link>.
</para>
</section>
</partintro>
&reference.mongo.entities.mongocollection;
</phpdoc:classref>
<!-- 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
-->

570
reference/mongo/mongocollection/aggregate.xml
View file

@ -1,570 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.aggregate" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::aggregate</refname>
<refpurpose>Perform an aggregation using the aggregation framework</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::aggregate</methodname>
<methodparam><type>array</type><parameter>pipeline</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::aggregate</methodname>
<methodparam><type>array</type><parameter>op</parameter></methodparam>
<methodparam rep="repeat"><type>array</type><parameter>ops</parameter></methodparam>
</methodsynopsis>
<para>
The MongoDB
<link xlink:href="&url.mongodb.docs.aggregation;">aggregation framework</link>
provides a means to calculate aggregated values without having to use
MapReduce. While MapReduce is powerful, it is often more difficult than
necessary for many simple aggregation tasks, such as totaling or averaging
field values.
</para>
<para>
This method accepts either a variable amount of pipeline operators, or a
single array of operators constituting the pipeline.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>pipeline</parameter></term>
<listitem>
<para>
An array of pipeline operators.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>options</parameter></term>
<listitem>
<para>Options for the aggregation command. Valid options include:</para>
<itemizedlist>
<listitem>
<para><literal>"allowDiskUse"</literal></para>
<para>Allow aggregation stages to write to temporary files</para>
</listitem>
<listitem>
<para><literal>"cursor"</literal></para>
<para>
Options controlling the creation of the cursor object. This option
causes the command to return a result document suitable for constructing
a <classname>MongoCommandCursor</classname>. If you need to use this
option, you should consider using
<methodname>MongoCollection::aggregateCursor</methodname>.
</para>
</listitem>
<listitem>
<para><literal>"explain"</literal></para>
<para>Return information on the processing of the pipeline.</para>
</listitem>
&mongo.command.parameters.maxtimems;
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
<para>Or</para>
<variablelist>
<varlistentry>
<term><parameter>op</parameter></term>
<listitem>
<para>
First pipeline operator.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ops</parameter></term>
<listitem>
<para>
Additional pipeline operators.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The result of the aggregation as an array. The <varname>ok</varname> will
be set to <literal>1</literal> on success, <literal>0</literal> on failure.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
When an error occurs an array with the following keys will be returned:
<itemizedlist>
<listitem>
<simpara>
<varname>errmsg</varname> - containing the reason for the failure
</simpara>
</listitem>
<listitem>
<simpara>
<varname>code</varname> - the errorcode of the failure
</simpara>
</listitem>
<listitem>
<simpara>
<varname>ok</varname> - will be set to 0.
</simpara>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 role="changelog"><!-- {{{ -->
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>PECL mongo 1.5.0</entry>
<entry>
Added optional <parameter>options</parameter> argument
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1><!-- }}} -->
<refsect1 role="examples">
&reftitle.examples;
<example xml:id="mongocollection.aggregate.example.basic">
<title><methodname>MongoCollection::aggregate</methodname> example</title>
<para>
The following example aggregation operation pivots data to create a set of
author names grouped by tags applied to an article. Call the aggregation
framework by issuing the following command:
</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient("localhost");
$c = $m->selectDB("examples")->selectCollection("article");
$data = array (
'title' => 'this is my title',
'author' => 'bob',
'posted' => new MongoDate,
'pageViews' => 5,
'tags' => array ( 'fun', 'good', 'fun' ),
'comments' => array (
array (
'author' => 'joe',
'text' => 'this is cool',
),
array (
'author' => 'sam',
'text' => 'this is bad',
),
),
'other' =>array (
'foo' => 5,
),
);
$d = $c->insert($data, array("w" => 1));
$ops = array(
array(
'$project' => array(
"author" => 1,
"tags" => 1,
)
),
array('$unwind' => '$tags'),
array(
'$group' => array(
"_id" => array("tags" => '$tags'),
"authors" => array('$addToSet' => '$author'),
),
),
);
$results = $c->aggregate($ops);
var_dump($results);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(2) {
["result"]=>
array(2) {
[0]=>
array(2) {
["_id"]=>
array(1) {
["tags"]=>
string(4) "good"
}
["authors"]=>
array(1) {
[0]=>
string(3) "bob"
}
}
[1]=>
array(2) {
["_id"]=>
array(1) {
["tags"]=>
string(3) "fun"
}
["authors"]=>
array(1) {
[0]=>
string(3) "bob"
}
}
}
["ok"]=>
float(1)
}
]]>
</screen>
</example>
<para>
The following examples use the <link xlink:href="&url.mongodb.examples.zipcode;">zipcode data set</link>.
Use mongoimport to load this data set into your mongod instance.
</para>
<example xml:id="mongocollection.aggregate.example.zipcode.population">
<title><methodname>MongoCollection::aggregate</methodname> example</title>
<para>
To return all states with a population greater than 10 million, use the following aggregation operation:
</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient("localhost");
$c = $m->selectDB("test")->selectCollection("zips");
$pipeline = array(
array(
'$group' => array(
'_id' => array('state' => '$state'),
'totalPop' => array('$sum' => '$pop')
)
),
array(
'$match' => array(
'totalPop' => array('$gte' => 10 * 1000 * 1000)
)
),
);
$out = $c->aggregate($pipeline);
var_dump($out);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
array(2) {
["result"]=>
array(7) {
[0]=>
array(2) {
["_id"]=>
string(2) "TX"
["totalPop"]=>
int(16986510)
}
[1]=>
array(2) {
["_id"]=>
string(2) "PA"
["totalPop"]=>
int(11881643)
}
[2]=>
array(2) {
["_id"]=>
string(2) "NY"
["totalPop"]=>
int(17990455)
}
[3]=>
array(2) {
["_id"]=>
string(2) "IL"
["totalPop"]=>
int(11430602)
}
[4]=>
array(2) {
["_id"]=>
string(2) "CA"
["totalPop"]=>
int(29760021)
}
[5]=>
array(2) {
["_id"]=>
string(2) "OH"
["totalPop"]=>
int(10847115)
}
[6]=>
array(2) {
["_id"]=>
string(2) "FL"
["totalPop"]=>
int(12937926)
}
}
["ok"]=>
float(1)
}
]]>
</screen>
</example>
<example xml:id="mongocollection.aggregate.example.zipcode.population.average">
<title><methodname>MongoCollection::aggregate</methodname> example</title>
<para>
To return the average populations for cities in each state, use the following aggregation operation:
</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient;
$c = $m->selectDB("test")->selectCollection("zips");
$out = $c->aggregate(
array(
'$group' => array(
'_id' => array('state' => '$state', 'city' => '$city' ),
'pop' => array('$sum' => '$pop' )
)
),
array(
'$group' => array(
'_id' => '$_id.state',
'avgCityPop' => array('$avg' => '$pop')
)
)
);
var_dump($out);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
array(2) {
["result"]=>
array(51) {
[0]=>
array(2) {
["_id"]=>
string(2) "DC"
["avgCityPop"]=>
float(303450)
}
[1]=>
array(2) {
["_id"]=>
string(2) "DE"
["avgCityPop"]=>
float(14481.913043478)
}
...
[49]=>
array(2) {
["_id"]=>
string(2) "WI"
["avgCityPop"]=>
float(7323.0074850299)
}
[50]=>
array(2) {
["_id"]=>
string(2) "WV"
["avgCityPop"]=>
float(2759.1953846154)
}
}
["ok"]=>
float(1)
}
]]>
</screen>
</example>
<example xml:id="mongocollection.aggregate.example.zipcode.explain">
<title><methodname>MongoCollection::aggregate</methodname> with command options</title>
<para>
To return information on how the pipeline will be processed we use the
<literal>explain</literal> command option:
</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient;
$c = $m->selectDB("test")->selectCollection("zips");
$pipeline = array(
array(
'$group' => array(
'_id' => '$state',
'totalPop' => array('$sum' => '$pop'),
),
),
array(
'$match' => array(
'totalPop' => array('$gte' => 10 * 1000 * 1000)
)
),
array(
'$sort' => array("totalPop" => -1),
),
);
$options = array("explain" => true);
$out = $c->aggregate($pipeline, $options);
var_dump($out);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
array(2) {
["stages"]=>
array(4) {
[0]=>
array(1) {
["$cursor"]=>
array(3) {
["query"]=>
array(0) {
}
["fields"]=>
array(3) {
["pop"]=>
int(1)
["state"]=>
int(1)
["_id"]=>
int(0)
}
["plan"]=>
array(4) {
["cursor"]=>
string(11) "BasicCursor"
["isMultiKey"]=>
bool(false)
["scanAndOrder"]=>
bool(false)
["allPlans"]=>
array(1) {
[0]=>
array(3) {
["cursor"]=>
string(11) "BasicCursor"
["isMultiKey"]=>
bool(false)
["scanAndOrder"]=>
bool(false)
}
}
}
}
}
[1]=>
array(1) {
["$group"]=>
array(2) {
["_id"]=>
string(6) "$state"
["totalPop"]=>
array(1) {
["$sum"]=>
string(4) "$pop"
}
}
}
[2]=>
array(1) {
["$match"]=>
array(1) {
["totalPop"]=>
array(1) {
["$gte"]=>
int(10000000)
}
}
}
[3]=>
array(1) {
["$sort"]=>
array(1) {
["sortKey"]=>
array(1) {
["totalPop"]=>
int(-1)
}
}
}
}
["ok"]=>
float(1)
}
]]>
</screen>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><methodname>MongoCollection::aggregateCursor</methodname></member>
<member>The MongoDB <link xlink:href="&url.mongodb.docs.aggregation;">aggregation framework</link></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
-->

232
reference/mongo/mongocollection/aggregatecursor.xml
View file

@ -1,232 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.aggregatecursor" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::aggregateCursor</refname>
<refpurpose>Execute an aggregation pipeline command and retrieve results through a cursor</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>MongoCommandCursor</type><methodname>MongoCollection::aggregateCursor</methodname>
<methodparam><type>array</type><parameter>command</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
With this method you can execute Aggregation Framework pipelines and
retrieve the results through a cursor, instead of getting just one document
back as you would with <methodname>MongoCollection::aggregate</methodname>.
This method returns a <classname>MongoCommandCursor</classname> object.
This cursor object implements the <classname>Iterator</classname> interface
just like the <classname>MongoCursor</classname> objects that are returned
by the <methodname>MongoCollection::find</methodname> method.
</para>
<note>
<simpara>
The resulting <classname>MongoCommandCursor</classname> will inherit this
collection's read preference.
<methodname>MongoCommandCursor::setReadPreference</methodname> may be used
to change the read preference before iterating on the cursor.
</simpara>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>pipeline</parameter>
</term>
<listitem>
<para>
The Aggregation Framework pipeline to execute.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>options</parameter></term>
<listitem>
<para>Options for the aggregation command. Valid options include:</para>
<itemizedlist>
<listitem>
<para><literal>"allowDiskUse"</literal></para>
<para>Allow aggregation stages to write to temporary files</para>
</listitem>
<listitem>
<para><literal>"cursor"</literal></para>
<para>
It is possible to configure how many initial documents the server
should return with the first result set. The default initial batch size
is <literal>101</literal>. You can change it by adding the
<literal>batchSize</literal> option:
</para>
<programlisting role="php">
<![CDATA[
<?php
$collection->aggregateCursor(
$pipeline,
[ "cursor" => [ "batchSize" => 4 ] ]
);
]]>
</programlisting>
<para>
This option only configures the size of the first batch. To configure
the size of future batches, please use the
<methodname>MongoCommandCursor::batchSize</methodname> method on the
returned <classname>MongoCommandCursor</classname> object.
</para>
</listitem>
<listitem>
<para><literal>"explain"</literal></para>
<para>
Return information on the processing of the pipeline. This option may
cause the command to return a result document that is unsuitable for
constructing a <classname>MongoCommandCursor</classname>. If you need
to use this option, you should consider using
<methodname>MongoCollection::aggregate</methodname>.
</para>
</listitem>
&mongo.command.parameters.maxtimems;
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a <classname>MongoCommandCursor</classname> object. Because this
implements the <classname>Iterator</classname> interface you can
iterate over each of the results as returned by the command query. The
<classname>MongoCommandCursor</classname> also implements the
<classname>MongoCursorInterface</classname> interface which adds the
<methodname>MongoCommandCursor::batchSize</methodname>,
<methodname>MongoCommandCursor::dead</methodname>,
<methodname>MongoCommandCursor::info</methodname> methods.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::aggregateCursor</function> example</title>
<para>
Finding all of the distinct values for a key.
</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient;
$db = $m->test;
$people = $db->people;
$people->drop();
$people->insert(array("name" => "Joe", "points" => 4));
$people->insert(array("name" => "Molly", "points" => 43));
$people->insert(array("name" => "Sally", "points" => 22));
$people->insert(array("name" => "Joe", "points" => 22));
$people->insert(array("name" => "Molly", "points" => 87));
$ages = $people->aggregateCursor( [
[ '$group' => [ '_id' => '$name', 'points' => [ '$sum' => '$points' ] ] ],
[ '$sort' => [ 'points' => -1 ] ],
] );
foreach ($ages as $person) {
echo "{$person['_id']}: {$person['points']}\n";
}
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
Molly: 130
Joe: 26
Sally: 22
</screen>
</example>
<example>
<title><function>MongoCollection::aggregateCursor</function>
example with different initial batch size</title>
<para>
Finding all of the distinct values for a key.
</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient;
$db = $m->test;
$people = $db->people;
$people->drop();
/* Insert some sample data */
$people->insert(array("name" => "Joe", "points" => 4));
$people->insert(array("name" => "Molly", "points" => 43));
$people->insert(array("name" => "Sally", "points" => 22));
$people->insert(array("name" => "Joe", "points" => 22));
$people->insert(array("name" => "Molly", "points" => 87));
/* Run the command cursor */
$ages = $people->aggregateCursor(
[
[ '$group' => [ '_id' => '$name', 'points' => [ '$sum' => '$points' ] ] ],
[ '$sort' => [ 'points' => -1 ] ],
],
[ "cursor" => [ "batchSize" => 4 ] ]
);
foreach ($ages as $person) {
echo "{$person['_id']}: {$person['points']}\n";
}
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
Molly: 130
Joe: 26
Sally: 22
</screen>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><methodname>MongoDB::command</methodname></member>
<member><classname>MongoCommandCursor</classname></member>
<member><methodname>MongoCommandCursor::batchSize</methodname></member>
<member><methodname>MongoCollection::aggregate</methodname></member>
<member>The MongoDB <link xlink:href="&url.mongodb.docs.aggregation;">aggregation framework</link></member>
</simplelist>
</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
-->

316
reference/mongo/mongocollection/batchinsert.xml
View file

@ -1,316 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.batchinsert" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::batchInsert</refname>
<refpurpose>Inserts multiple documents into this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>mixed</type><methodname>MongoCollection::batchInsert</methodname>
<methodparam><type>array</type><parameter>a</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>a</parameter>
</term>
<listitem>
<para>
An array of arrays or objects. If any objects are used, they may not have
protected or private properties.
</para>
<note>
<para>
If the documents to insert do not have an <literal>_id</literal> key or
property, a new <classname>MongoId</classname> instance will be created
and assigned to it. See <function>MongoCollection::insert</function> for
additional information on this behavior.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>options</parameter>
</term>
<listitem>
<para>
An array of options for the batch of insert operations. Currently
available options include:
<itemizedlist>
<listitem>
<para>
<literal>"continueOnError"</literal>
</para>
<para>
Boolean, defaults to &false;. If set, the database will not stop
processing a bulk insert if one fails (eg due to duplicate IDs).
This makes bulk insert behave similarly to a series of single
inserts, except that calling <function>MongoDB::lastError</function>
will have an error set if any insert fails, not just the last one.
If multiple errors occur, only the most recent will be reported by
<function>MongoDB::lastError</function>.
</para>
<note>
<para>
Please note that <literal>continueOnError</literal> affects errors
on the database side only. If you try to insert a document that has
errors (for example it contains a key with an empty name), then the
document is not even transferred to the database as the driver
detects this error and bails out.
<literal>continueOnError</literal> has no effect on errors detected
in the documents by the driver.
</para>
</note>
</listitem>
&mongo.writes.parameters.fsync;
&mongo.writes.parameters.journal;
&mongo.writes.parameters.sockettimeoutms;
&mongo.writes.parameters.writeconcern;
&mongo.writes.parameters.writeconcerntimeoutms;
</itemizedlist>
</para>
<para>
The following options are deprecated and should no longer be used:
<itemizedlist>
&mongo.writes.parameters.safe;
&mongo.writes.parameters.timeout;
&mongo.writes.parameters.writeconcerntimeout;
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
If the <literal>w</literal> parameter is set to acknowledge the write,
returns an associative array with the status of the inserts ("ok") and any
error that may have occurred ("err"). Otherwise, returns &true; if the
batch insert was successfully sent, &false; otherwise.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoException</classname> if any inserted documents are
empty or if they contains zero-length keys. Attempting to insert an object
with protected and private properties will cause a zero-length key error.
</para>
&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>PECL mongo 1.5.0</entry>
<entry>
<para>
Added the <literal>"wTimeoutMS"</literal> option, which replaces
<literal>"wtimeout"</literal>. Emits <constant>E_DEPRECATED</constant>
when <literal>"wtimeout"</literal> is used.
</para>
<para>
Added the <literal>"socketTimeoutMS"</literal> option, which replaces
<literal>"timeout"</literal>. Emits <constant>E_DEPRECATED</constant>
when <literal>"timeout"</literal> is used.
</para>
<para>
Emits <constant>E_DEPRECATED</constant> when <literal>"safe"</literal>
is used.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.3.4</entry>
<entry>Added <literal>"wtimeout"</literal> option.</entry>
</row>
<row>
<entry>PECL mongo 1.3.0</entry>
<entry>Added <literal>"w"</literal> option.</entry>
</row>
<row>
<entry>PECL mongo 1.2.7</entry>
<entry>Added <literal>"continueOnError"</literal> option.</entry>
</row>
<row>
<entry>PECL mongo 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>
</entry>
</row>
<row>
<entry>PECL mongo 1.0.5</entry>
<entry>Added <parameter>options</parameter> parameter.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::batchInsert</function> example</title>
<para>
Batch insertion is a quick way to add many elements to the database at once
</para>
<programlisting role="php">
<![CDATA[
<?php
$users = array();
for ($i = 0; $i<100; $i++) {
$users[] = array('username' => 'user'.$i, 'i' => $i);
}
$mongo = new MongoClient();
$collection = $mongo->my_db->users;
$collection->drop();
$collection->batchInsert($users);
foreach ($users as $user) {
echo $user['_id']."\n"; // populated with instanceof MongoId
}
$users = $collection->find()->sort(array('i' => 1));
foreach ($users as $user) {
var_dump($user['username']);
}
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
4bf43ac68ead0e1971000000
4bf43ac68ead0e1971010000
4bf43ac68ead0e1971020000
...
string(5) "user1"
string(5) "user2"
string(5) "user3"
...
]]>
</screen>
</example>
<example>
<title><function>MongoCollection::batchInsert</function> example with
ignoring errors</title>
<programlisting role="php">
<![CDATA[
<?php
$con = new Mongo;
$db = $con->demo;
$doc1 = array(
'_id' => new MongoId('4cb4ab6d7addf98506010001'),
'id' => 1,
'desc' => "ONE",
);
$doc2 = array(
'_id' => new MongoId('4cb4ab6d7addf98506010002'),
'id' => 2,
'desc' => "TWO",
);
$doc3 = array(
'_id' => new MongoId('4cb4ab6d7addf98506010002'), // same _id as above
'id' => 3,
'desc' => "THREE",
);
$doc4 = array(
'_id' => new MongoId('4cb4ab6d7addf98506010004'),
'id' => 4,
'desc' => "FOUR",
);
$c = $db->selectCollection('c');
$c->batchInsert(
array($doc1, $doc2, $doc3, $doc4),
array('continueOnError' => true)
);
$docs = $c->find();
foreach ($docs as $doc) {
var_dump($doc['desc']);
}
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
string(3) "ONE"
string(3) "TWO"
string(4) "FOUR"
]]>
</screen>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>MongoCollection::insert</function></member>
<member><function>MongoCollection::update</function></member>
<member><function>MongoCollection::find</function></member>
<member><function>MongoCollection::remove</function></member>
<member>MongoDB core docs on <link xlink:href="&url.mongodb.dochub.insert;">insert</link>.</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
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
-->

83
reference/mongo/mongocollection/construct.xml
View file

@ -1,83 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::__construct</refname>
<refpurpose>Creates a new collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <methodname>MongoCollection::__construct</methodname>
<methodparam><type>MongoDB</type><parameter>db</parameter></methodparam>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<type>MongoDB</type>
<parameter>db</parameter>
</term>
<listitem>
<para>
Parent database.
</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>
<parameter>name</parameter>
</term>
<listitem>
<para>
Name for this collection.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a new collection object.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws default exception if the collection name is invalid.
</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
-->

197
reference/mongo/mongocollection/count.xml
View file

@ -1,197 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.count" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::count</refname>
<refpurpose>Counts the number of documents in this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>int</type><methodname>MongoCollection::count</methodname>
<methodparam choice="opt"><type>array</type><parameter>query</parameter><initializer>array()</initializer></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>query</parameter>
</term>
<listitem>
<para>
Associative array or object with fields to match.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>options</parameter>
</term>
<listitem>
<para>
An array of options for the index creation. Currently available options
include:
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>&Name;</entry>
<entry>&Type;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry><varname>hint</varname></entry>
<entry><type>mixed</type></entry>
<entry>
<para>
Index to use for the query. If a string is passed, it should
correspond to an index name. If an array or object is passed, it
should correspond to the specification used to create the index
(i.e. the first argument to
<function>MongoCollection::createIndex</function>).
</para>
<simpara>This option is only supported in MongoDB 2.6+.</simpara>
</entry>
</row>
<row>
<entry><varname>limit</varname></entry>
<entry><type>int</type></entry>
<entry>The maximum number of matching documents to return.</entry>
</row>
<row>
<entry><varname>maxTimeMS</varname></entry>
<entry><type>int</type></entry>
<entry>
<para>
Specifies a cumulative time limit in milliseconds for processing
the operation (does not include idle time). If the operation is not
completed within the timeout period, a
<classname>MongoExecutionTimeoutException</classname> will be
thrown.
</para>
<simpara>This option is only supported in MongoDB 2.6+.</simpara>
</entry>
</row>
<row>
<entry><varname>skip</varname></entry>
<entry><type>int</type></entry>
<entry>The number of matching documents to skip before returning results.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the number of documents matching the query.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoResultException</classname> if the server could not
execute the command due to an error.
</para>
<para>
Throws <classname>MongoExecutionTimeoutException</classname> if command
execution was terminated due to <varname>maxTimeMS</varname>.
</para>
</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 mongo 1.6.0</entry>
<entry>
The second parameter is now an <parameter>options</parameter> array.
Passing <parameter>limit</parameter> and <parameter>skip</parameter> as
the second and third parameters, respectively, is deprecated.
</entry>
</row>
<row>
<entry>PECL mongo 1.0.7</entry>
<entry>
Added <parameter>limit</parameter> and <parameter>skip</parameter> as
second and third parameters, respectively.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::count</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$collection->insert(array('x'=>1));
$collection->insert(array('x'=>2));
$collection->insert(array('x'=>3));
var_dump($collection->count());
var_dump($collection->count(array('x'=>1)));
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
int(3)
int(1)
]]>
</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
-->

101
reference/mongo/mongocollection/createdbref.xml
View file

@ -1,101 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.createdbref" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::createDBRef</refname>
<refpurpose>Creates a database reference</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::createDBRef</methodname>
<methodparam><type>mixed</type><parameter>document_or_id</parameter></methodparam>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>document_or_id</parameter>
</term>
<listitem>
<para>
If an array or object is given, its <literal>_id</literal> field will be
used as the reference ID. If a <classname>MongoId</classname> or scalar
is given, it will be used as the reference ID.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a database reference array.
</para>
<para>
If an array without an <literal>_id</literal> field was provided as the
<literal>document_or_id</literal> parameter, &null; will be returned.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><methodname>MongoCollection::createDBRef</methodname> example</title>
<programlisting role="php">
<![CDATA[
<?php
$songs = $db->songs;
$playlists = $db->playlists;
// create a reference to a song
$manamana = $songs->findOne(array('title' => 'Ma na ma na'));
$refToSong = $songs->createDBRef($manamana);
// add the reference to my playlist
$playlists->update(array('username' => 'me'), array('$push' => array('songlist' => $refToSong)));
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><methodname>MongoCollection::getDBRef</methodname></member>
</simplelist>
</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
-->

248
reference/mongo/mongocollection/createindex.xml
View file

@ -1,248 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.createindex" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::createIndex</refname>
<refpurpose>
Creates an index on the specified field(s) if it does not already exist
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>MongoCollection::createIndex</methodname>
<methodparam><type>array</type><parameter>keys</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
</methodsynopsis>
<para>
Creates an index on the specified field(s) if it does not already exist.
Fields may be indexed with a direction (e.g. ascending or descending) or a
special type (e.g. text, geospatial, hashed).
</para>
<note>
<para>
This method will use the
<link xlink:href="&url.mongodb.docs.command;createIndexes">createIndexes</link>
database command when communicating with MongoDB 2.6+. For previous database
versions, the method will perform an insert operation on the
special <literal>system.indexes</literal> collection.
</para>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>keys</parameter>
</term>
<listitem>
<para>
An array specifying the index's fields as its keys. For each field, the
value is either the index direction or
<link xlink:href="&url.mongodb.dochub.indexes.types;">index type</link>.
If specifying direction, specify <literal>1</literal> for ascending or
<literal>-1</literal> for descending.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>options</parameter>
</term>
<listitem>
<para>
An array of options for the index creation. We pass all given options
straight to the server, but a non-exhaustive list of currently
available options include:
<itemizedlist>
&mongo.index.parameters.unique;
&mongo.index.parameters.sparse;
&mongo.index.parameters.expireafterseconds;
&mongo.index.parameters.name;
&mongo.index.parameters.background;
&mongo.writes.parameters.sockettimeoutms;
</itemizedlist>
</para>
<para>
The following option may be used with MongoDB 2.6+:
<itemizedlist>
&mongo.command.parameters.maxtimems;
</itemizedlist>
</para>
<para>
The following options may be used with MongoDB versions before 2.8:
<itemizedlist>
&mongo.index.parameters.dropdups;
</itemizedlist>
</para>
<para>
The following options may be used with MongoDB versions before 2.6:
<itemizedlist>
&mongo.writes.parameters.writeconcern;
&mongo.writes.parameters.writeconcerntimeoutms;
</itemizedlist>
</para>
<para>
The following options are deprecated and should no longer be used:
<itemizedlist>
&mongo.writes.parameters.safe;
&mongo.writes.parameters.timeout;
&mongo.writes.parameters.writeconcerntimeout;
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an array containing the status of the index creation. The array
contains whether the operation succeeded (<literal>"ok"</literal>), the
number of indexes before and after the operation
(<literal>"numIndexesBefore"</literal> and
<literal>"numIndexesAfter"</literal>), and whether the collection that the
index belongs to has been created
(<literal>"createdCollectionAutomatically"</literal>). If the index already
existed and did not need to be created, a <literal>"note"</literal> field may
be present in lieu of <literal>"numIndexesAfter"</literal>.
</para>
<para>
With MongoDB 2.4 and earlier, a status document is only returned if the
<link linkend="mongo.writeconcerns">write concern</link> is at least
<literal>1</literal>. Otherwise, &true; is returned. The fields in the status
document are different, except for the <literal>"ok"</literal> field, which
signals whether the index creation was successful. Additional fields are
described in the documentation for
<function>MongoCollection::insert</function>.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoException</classname> if the index name is longer
than 128 bytes, or if the index specification is not an array.
</para>
<para>
Throws <classname>MongoDuplicateKeyException</classname> if the server could not
create the unique index due to conflicting documents.
</para>
<para>
Throws <classname>MongoResultException</classname> if the server could not
create the index due to an error.
</para>
&mongo.errors.exceptions.writeconcern;
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::createIndex</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$c = new MongoCollection($db, 'foo');
// create an index on 'x' ascending
$c->createIndex(array('x' => 1));
// create a unique index on 'y'
$c->createIndex(array('y' => 1), array('unique' => true));
// create a compound index on 'za' ascending and 'zb' descending
$c->createIndex(array('za' => 1, 'zb' => -1));
?>
]]>
</programlisting>
</example>
<example>
<title>Geospatial Indexing</title>
<para>
Mongo supports geospatial indexes, which allow you to search for documents
near a given location or within a shape. The following example creates a
geospatial index on the <literal>"loc"</literal> field:
</para>
<programlisting role="php">
<![CDATA[
<?php
$collection->createIndex(array('loc' => '2dsphere'));
?>
]]>
</programlisting>
</example>
<example>
<title>Drop duplicates example</title>
<programlisting role="php">
<![CDATA[
<?php
$collection->insert(array('username' => 'joeschmoe'));
$collection->insert(array('username' => 'joeschmoe'));
/* Index creation fails, since you cannot create a unique index on a field when
* duplicates exist.
*/
$collection->createIndex(array('username' => 1), array('unique' => 1));
/* MongoDB will one of the conflicting documents and allow the unique index to
* be created.
*/
$collection->createIndex(array('username' => 1), array('unique' => 1, 'dropDups' => 1));
/* We now have a unique index and subsequent inserts with the same username will
* fail.
*/
$collection->insert(array('username' => 'joeschmoe'));
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><methodname>MongoCollection::deleteIndex</methodname></member>
<member><methodname>MongoCollection::deleteIndexes</methodname></member>
<member>
The MongoDB
<link xlink:href="&url.mongodb.dochub.indexes;">index</link> and
<link xlink:href="&url.mongodb.dochub.indexes.types;">index type</link>
documentation.
</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
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
-->

170
reference/mongo/mongocollection/deleteindex.xml
View file

@ -1,170 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.deleteindex" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::deleteIndex</refname>
<refpurpose>Deletes an index from this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::deleteIndex</methodname>
<methodparam><type class="union"><type>string</type><type>array</type></type><parameter>keys</parameter></methodparam>
</methodsynopsis>
<para>
This method is identical to:
</para>
<programlisting role="php">
<![CDATA[
<?php
public function deleteIndexes($keys) {
$indexName = $this->toIndexString($keys);
return $this->db->command(array(
"deleteIndexes" => $this->getName(),
"index" => $indexName,
));
}
?>
]]>
</programlisting>
<para>
Each index is given a unique name when it is created. This is often generated
by the driver based on the index key(s) and order/type, but custom names may
also be specified with <function>MongoCollection::createIndex</function>'s
<literal>"name"</literal> option).
</para>
<para>
Unfortunately, <function>MongoCollection::deleteIndex</function> cannot
delete custom-named indexes due to a backwards compatibility issue. When a
string argument is provided, it is assumed to be the single field name in an
ascending index (e.g. the name <literal>"x_1"</literal> would be used for the
argument <literal>"x"</literal>). If an array or object is provided, an index
name is generated just as if that argument was passed to
<function>MongoCollection::createIndex</function>.
</para>
<para>
In order to delete a custom-named index with the PHP driver, the
<literal>deleteIndexes</literal> database command must be used. For instance,
an index named "myIndex" could be deleted with the PHP driver by running:
</para>
<programlisting role="php">
<![CDATA[
<?php
$db->command(array(
"deleteIndexes" => $collection->getName(),
"index" => "myIndex",
));
?>
]]>
</programlisting>
<para>
To determine the name of an index with the PHP driver, you can query the
<literal>system.indexes</literal> collection of a database and look for the
<literal>"name"</literal> field of each result. The <literal>"ns"</literal>
field will indicate the collection to which each index belongs.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>keys</parameter>
</term>
<listitem>
<para>
An array specifying the index's fields as its keys. For each field, the
value is either the index direction or
<link xlink:href="&url.mongodb.dochub.indexes.types;">index type</link>.
If specifying direction, specify <literal>1</literal> for ascending or
<literal>-1</literal> for descending.
</para>
<para>
If a string is provided, it is assumed to be the single field name in an
ascending index.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the database response.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::deleteIndex</function> example</title>
<para>
This example passes the function string and array parameters.
</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$c = $m->example->indices;
// create and remove a simple index
$c->createIndex(array("i"=>1));
$c->deleteIndex("i");
// create and remove a multi-key index
$c->ensureIndex(array("j" => 1, "k" => 1));
$c->deleteIndex(array("j" => 1, "k" => 1));
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><methodname>MongoCollection::createIndex</methodname></member>
<member><methodname>MongoCollection::deleteIndexes</methodname></member>
<member><methodname>MongoCollection::toIndexString</methodname></member>
<member>
The MongoDB
<link xlink:href="&url.mongodb.dochub.indexes;">index</link> and
<link xlink:href="&url.mongodb.dochub.indexes.types;">index type</link>
documentation.
</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
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
-->

87
reference/mongo/mongocollection/deleteindexes.xml
View file

@ -1,87 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.deleteindexes" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::deleteIndexes</refname>
<refpurpose>Delete all indices for this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::deleteIndexes</methodname>
<void/>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the database response.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::deleteIndexes</function> example</title>
<para>This example demonstrates how to delete all indexes from a collection and the response to expect.</para>
<programlisting role="php">
<![CDATA[
<?php
$collection = $mongo->my_db->articles;
$response = $collection->deleteIndexes();
print_r($response);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Array
(
[nIndexesWas] => 1
[msg] => all indexes deleted for collection
[ok] => 1
)
]]>
</screen>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><methodname>MongoCollection::createIndex</methodname></member>
<member><methodname>MongoCollection::deleteIndex</methodname></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
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
-->

156
reference/mongo/mongocollection/distinct.xml
View file

@ -1,156 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.distinct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::distinct</refname>
<refpurpose>Retrieve a list of distinct values for the given key across a collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type class="union"><type>array</type><type>false</type></type><methodname>MongoCollection::distinct</methodname>
<methodparam><type>string</type><parameter>key</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>query</parameter></methodparam>
</methodsynopsis>
<para>
The distinct command returns a list of distinct values for the given key
across a collection.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>key</parameter></term>
<listitem>
<para>
The key to use.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>query</parameter></term>
<listitem>
<para>
An optional query parameters
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an array of distinct values, &return.falseforfailure;
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example xml:id="mongocollection.distinct.basic">
<title><methodname>MongoCollection::distinct</methodname> example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo;
$db = $m->selectDB("test");
$db->dropCollection("distinct");
$c = $db->distinct;
$c->insert(array("stuff" => "bar", "zip-code" => 10010));
$c->insert(array("stuff" => "foo", "zip-code" => 10010));
$c->insert(array("stuff" => "bar", "zip-code" => 99701), array("w" => 1));
$retval = $c->distinct("zip-code");
var_dump($retval);
$retval = $c->distinct("zip-code", array("stuff" => "foo"));
var_dump($retval);
$retval = $c->distinct("zip-code", array("stuff" => "bar"));
var_dump($retval);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(2) {
[0]=>
int(10010)
[1]=>
int(99701)
}
array(1) {
[0]=>
int(10010)
}
array(2) {
[0]=>
int(10010)
[1]=>
int(99701)
}
]]>
</screen>
</example>
<example xml:id="mongocollection.distinct.basic-embedded">
<title><methodname>MongoCollection::distinct</methodname> example on a embedded document</title>
<programlisting role="php">
<![CDATA[
<?php
$c->insert(array("user" => array("points" => 25)));
$c->insert(array("user" => array("points" => 31)));
$c->insert(array("user" => array("points" => 25)));
$retval = $c->distinct("user.points");
var_dump($retval);
$retval = $c->distinct("user.nonexisting");
var_dump($retval);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(2) {
[0]=>
int(25)
[1]=>
int(31)
}
array(0) {
}
]]>
</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
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
-->

82
reference/mongo/mongocollection/drop.xml
View file

@ -1,82 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.drop" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::drop</refname>
<refpurpose>Drops this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::drop</methodname>
<void/>
</methodsynopsis>
<para>
Drops this collection and deletes its indices.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the database response.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::drop</function> example</title>
<para>This example demonstrates how to drop a collection and the response to expect.</para>
<programlisting role="php">
<![CDATA[
<?php
$collection = $mongo->my_db->articles;
$response = $collection->drop();
print_r($response);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Array
(
[nIndexesWas] => 1
[msg] => all indexes deleted for collection
[ns] => my_db.articles
[ok] => 1
)
]]>
</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
-->

347
reference/mongo/mongocollection/ensureindex.xml
View file

@ -1,347 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.ensureindex" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::ensureIndex</refname>
<refpurpose>
Creates an index on the specified field(s) if it does not already exist
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>MongoCollection::ensureIndex</methodname>
<methodparam><type class="union"><type>string</type><type>array</type></type><parameter>key|keys</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
</methodsynopsis>
<warning>
<para>
This method is deprecated since version 1.5.0. Please use
<methodname>MongoCollection::createIndex</methodname> instead.
</para>
</warning>
<para>
Creates an index on the specified field(s) if it does not already exist.
Fields may be indexed with a direction (e.g. ascending or descending) or a
special type (e.g. text, geospatial, hashed).
</para>
<note>
<para>
This method will use the
<link xlink:href="&url.mongodb.docs.command;createIndexes">createIndexes</link>
database command when communicating with MongoDB 2.6+. For previous database
versions, the method will perform an insert operation on the
special <literal>system.indexes</literal> collection.
</para>
</note>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>keys</parameter>
</term>
<listitem>
<para>
An array specifying the index's fields as its keys. For each field, the
value is either the index direction or
<link xlink:href="&url.mongodb.dochub.indexes.types;">index type</link>.
If specifying direction, specify <literal>1</literal> for ascending or
<literal>-1</literal> for descending.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>options</parameter>
</term>
<listitem>
<para>
An array of options for the index creation. Currently available options
include:
<itemizedlist>
&mongo.index.parameters.unique;
&mongo.index.parameters.sparse;
&mongo.index.parameters.expireafterseconds;
&mongo.index.parameters.name;
&mongo.index.parameters.background;
&mongo.writes.parameters.sockettimeoutms;
</itemizedlist>
</para>
<para>
The following option may be used with MongoDB 2.6+:
<itemizedlist>
&mongo.command.parameters.maxtimems;
</itemizedlist>
</para>
<para>
The following options may be used with MongoDB versions before 2.8:
<itemizedlist>
&mongo.index.parameters.dropdups;
</itemizedlist>
</para>
<para>
The following options may be used with MongoDB versions before 2.6:
<itemizedlist>
&mongo.writes.parameters.writeconcern;
&mongo.writes.parameters.writeconcerntimeoutms;
</itemizedlist>
</para>
<para>
The following options are deprecated and should no longer be used:
<itemizedlist>
&mongo.writes.parameters.safe;
&mongo.writes.parameters.timeout;
&mongo.writes.parameters.writeconcerntimeout;
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an array containing the status of the index creation. The array
contains whether the operation succeeded (<literal>"ok"</literal>), the
number of indexes before and after the operation
(<literal>"numIndexesBefore"</literal> and
<literal>"numIndexesAfter"</literal>), and whether the collection that the
index belongs to has been created
(<literal>"createdCollectionAutomatically"</literal>). If the index already
existed and did not need to be created, a <literal>"note"</literal> field may
be present in lieu of <literal>"numIndexesAfter"</literal>.
</para>
<para>
With MongoDB 2.4 and earlier, a status document is only returned if the
<link linkend="mongo.writeconcerns">write concern</link> is at least
<literal>1</literal>. Otherwise, &true; is returned. The fields in the status
document are different, except for the <literal>"ok"</literal> field, which
signals whether the index creation was successful. Additional fields are
described in the documentation for
<function>MongoCollection::insert</function>.
</para>
</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 mongo 1.5.0</entry>
<entry>
<para>
Renamed the <literal>"wtimeout"</literal> option to
<literal>"wTimeoutMS"</literal>. Emits
<constant>E_DEPRECATED</constant> when <literal>"wtimeout"</literal> is
used.
</para>
<para>
Renamed the <literal>"timeout"</literal> option to
<literal>"socketTimeoutMS"</literal>. Emits
<constant>E_DEPRECATED</constant> when <literal>"timeout"</literal> is
used.
</para>
<para>
Emits <constant>E_DEPRECATED</constant> when <literal>"safe"</literal>
is used.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.3.4</entry>
<entry>Added <literal>"wtimeout"</literal> option.</entry>
</row>
<row>
<entry>PECL mongo 1.3.0</entry>
<entry>
<para>Added <literal>"w"</literal> option.</para>
<para>
The <parameter>options</parameter> parameter no longer accepts a
boolean to signify a unique index. Instead, this now has to be done
with <literal>array('unique' => true)</literal>.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.2.11</entry>
<entry>
Emits <constant>E_DEPRECATED</constant> when
<parameter>options</parameter> is <type>scalar</type>.
</entry>
</row>
<row>
<entry>PECL mongo 1.2.0</entry>
<entry>Added <literal>"timeout"</literal> option.</entry>
</row>
<row>
<entry>PECL mongo 1.0.11</entry>
<entry>
<para>
The <literal>"safe"</literal> option will trigger a primary failover,
if necessary.
</para>
<para>
<classname>MongoException</classname> will be thrown if the index name
(either generated or set) is longer than 128 bytes.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.0.5</entry>
<entry>
Added the <literal>"name"</literal> option to override index name
creation.
</entry>
</row>
<row>
<entry>PECL mongo 1.0.2</entry>
<entry>
Changed <parameter>options</parameter> parameter from boolean to array.
Pre-1.0.2, the second parameter was an optional boolean value specifying
a unique index.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoException</classname> if the index name is longer
than 128 bytes, or if the index specification is not an array.
</para>
<para>
Throws <classname>MongoDuplicateKeyException</classname> if the server could not
create the unique index due to conflicting documents.
</para>
<para>
Throws <classname>MongoResultException</classname> if the server could not
create the index due to an error.
</para>
&mongo.errors.exceptions.writeconcern;
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::ensureIndex</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$c = new MongoCollection($db, 'foo');
// create an index on 'x' ascending
$c->ensureIndex(array('x' => 1));
// create a unique index on 'y'
$c->ensureIndex(array('y' => 1), array('unique' => true));
// create a compound index on 'za' ascending and 'zb' descending
$c->ensureIndex(array('za' => 1, 'zb' => -1));
?>
]]>
</programlisting>
</example>
<example>
<title>Geospatial Indexing</title>
<para>
Mongo supports geospatial indexes, which allow you to search for documents
near a given location or within a shape. The following example creates a
geospatial index on the <literal>"loc"</literal> field:
</para>
<programlisting role="php">
<![CDATA[
<?php
$collection->ensureIndex(array('loc' => '2dsphere'));
?>
]]>
</programlisting>
</example>
<example>
<title>Drop duplicates example</title>
<programlisting role="php">
<![CDATA[
<?php
$collection->insert(array('username' => 'joeschmoe'));
$collection->insert(array('username' => 'joeschmoe'));
/* Index creation fails, since you cannot create a unique index on a field when
* duplicates exist.
*/
$collection->ensureIndex(array('username' => 1), array('unique' => 1));
/* MongoDB will one of the conflicting documents and allow the unique index to
* be created.
*/
$collection->ensureIndex(array('username' => 1), array('unique' => 1, 'dropDups' => 1));
/* We now have a unique index and subsequent inserts with the same username will
* fail.
*/
$collection->insert(array('username' => 'joeschmoe'));
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><methodname>MongoCollection::createIndex</methodname></member>
<member><methodname>MongoCollection::deleteIndex</methodname></member>
<member><methodname>MongoCollection::deleteIndexes</methodname></member>
<member>
The MongoDB
<link xlink:href="&url.mongodb.dochub.indexes;">index</link> and
<link xlink:href="&url.mongodb.dochub.indexes.types;">index type</link>
documentation.
</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
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
-->

392
reference/mongo/mongocollection/find.xml
View file

@ -1,392 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.find" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::find</refname>
<refpurpose>Queries this collection, returning a <classname>MongoCursor</classname>
for the result set</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>MongoCursor</type><methodname>MongoCollection::find</methodname>
<methodparam choice="opt"><type>array</type><parameter>query</parameter><initializer>array()</initializer></methodparam>
<methodparam choice="opt"><type>array</type><parameter>fields</parameter><initializer>array()</initializer></methodparam>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>query</parameter>
</term>
<listitem>
<para>
The fields for which to search. MongoDB's query language is quite
extensive. The PHP driver will in almost all cases pass the query
straight through to the server, so reading the MongoDB core docs on
<link xlink:href="&url.mongodb.dochub.find;">find</link> is a good idea.
</para>
<warning>
<para>
Please make sure that for all special query operators (starting with
<literal>$</literal>) you use single quotes so that PHP doesn't try to
replace <literal>"$exists"</literal> with the value of the variable
<literal>$exists</literal>.
</para>
</warning>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>fields</parameter>
</term>
<listitem>
<para>
Fields of the results to return. The array is in the format
<literal>array('fieldname' => true, 'fieldname2' => true)</literal>.
The <literal>_id</literal> field is always returned.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a cursor for the search results.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::find</function> example</title>
<para>This example demonstrates basic search options.</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'produce');
// search for fruits
$fruitQuery = array('Type' => 'Fruit');
$cursor = $collection->find($fruitQuery);
foreach ($cursor as $doc) {
var_dump($doc);
}
// search for produce that is sweet. Taste is a child of Details.
$sweetQuery = array('Details.Taste' => 'Sweet');
echo "Sweet\n";
$cursor = $collection->find($sweetQuery);
foreach ($cursor as $doc) {
var_dump($doc);
}
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(4) {
["_id"]=>
object(MongoId)#7 (1) {
["$id"]=>
string(24) "50a87dd084f045a19b220dd6"
}
["Name"]=>
string(5) "Apple"
["Type"]=>
string(5) "Fruit"
["Details"]=>
array(2) {
["Taste"]=>
string(5) "Sweet"
["Colour"]=>
string(3) "Red"
}
}
array(4) {
["_id"]=>
object(MongoId)#8 (1) {
["$id"]=>
string(24) "50a87de084f045a19b220dd7"
}
["Name"]=>
string(5) "Lemon"
["Type"]=>
string(5) "Fruit"
["Details"]=>
array(2) {
["Taste"]=>
string(4) "Sour"
["Colour"]=>
string(5) "Green"
}
}
Sweet:
array(4) {
["_id"]=>
object(MongoId)#7 (1) {
["$id"]=>
string(24) "50a87dd084f045a19b220dd6"
}
["Name"]=>
string(5) "Apple"
["Type"]=>
string(5) "Fruit"
["Details"]=>
array(2) {
["Taste"]=>
string(5) "Sweet"
["Colour"]=>
string(3) "Red"
}
}
]]>
</screen>
<para>
See <classname>MongoCursor</classname> for more information how to work with cursors.
</para>
</example>
<example>
<title><function>MongoCollection::find</function> example</title>
<para>This example demonstrates how to search for a range.</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');
// search for documents where 5 < x < 20
$rangeQuery = array('x' => array( '$gt' => 5, '$lt' => 20 ));
$cursor = $collection->find($rangeQuery);
foreach ($cursor as $doc) {
var_dump($doc);
}
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(2) {
["_id"]=>
object(MongoId)#10 (1) {
["$id"]=>
string(24) "4ebc3e3710b89f2349000000"
}
["x"]=>
int(12)
}
array(2) {
["_id"]=>
object(MongoId)#11 (1) {
["$id"]=>
string(24) "4ebc3e3710b89f2349000001"
}
["x"]=>
int(12)
}
]]>
</screen>
<para>
See <classname>MongoCursor</classname> for more information how to work with cursors.
</para>
</example>
<example>
<title><function>MongoCollection::find</function> example using $where</title>
<para>This example demonstrates how to search a collection using javascript code to reduce the resultset.</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');
$js = "function() {
return this.name == 'Joe' || this.age == 50;
}";
$cursor = $collection->find(array('$where' => $js));
foreach ($cursor as $doc) {
var_dump($doc);
}
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(3) {
["_id"]=>
object(MongoId)#7 (1) {
["$id"]=>
string(24) "4ebc3e3710b89f2349000002"
}
["name"]=>
string(3) "Joe"
["age"]=>
int(20)
}
]]>
</screen>
</example>
<example>
<title><function>MongoCollection::find</function> example using $in</title>
<para>This example demonstrates how to search a collection using the $in operator.</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');
$cursor = $collection->find(array(
'name' => array('$in' => array('Joe', 'Wendy'))
));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(3) {
["_id"]=>
object(MongoId)#7 (1) {
["$id"]=>
string(24) "4ebc3e3710b89f2349000002"
}
["name"]=>
string(3) "Joe"
["age"]=>
int(20)
}
]]>
</screen>
</example>
<example>
<title>Getting results as an array</title>
<para>
This returns a <classname>MongoCursor</classname>. Often, when people are
starting out, they are more comfortable using an array. To turn a cursor
into an array, use the <function>iterator_to_array</function> function.
</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$db = $m->selectDB('test');
$collection = new MongoCollection($db, 'phpmanual');
$cursor = $collection->find();
$array = iterator_to_array($cursor);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(3) {
["4ebc40af10b89f5149000000"]=>
array(2) {
["_id"]=>
object(MongoId)#6 (1) {
["$id"]=>
string(24) "4ebc40af10b89f5149000000"
}
["x"]=>
int(12)
}
["4ebc40af10b89f5149000001"]=>
array(2) {
["_id"]=>
object(MongoId)#11 (1) {
["$id"]=>
string(24) "4ebc40af10b89f5149000001"
}
["x"]=>
int(12)
}
["4ebc40af10b89f5149000002"]=>
array(3) {
["_id"]=>
object(MongoId)#12 (1) {
["$id"]=>
string(24) "4ebc40af10b89f5149000002"
}
["name"]=>
string(3) "Joe"
["age"]=>
int(20)
}
}
]]>
</screen>
<para>
Using <function>iterator_to_array</function> forces the driver to load all of
the results into memory, so do not do this for result sets that are larger
than memory!
</para>
<para>
Also, certain system collections do not have an <literal>_id</literal>
field. If you are dealing with a collection that might have documents
without <literal>_id</literal>s, pass &false; as the second argument to
<function>iterator_to_array</function> (so that it will not try to use the
non-existent <literal>_id</literal> values as keys).
</para>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>MongoCollection::findOne</function></member>
<member><function>MongoCollection::insert</function></member>
<member>MongoDB core docs on <link xlink:href="&url.mongodb.dochub.find;">find</link>.</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
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
-->

288
reference/mongo/mongocollection/findandmodify.xml
View file

@ -1,288 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.findandmodify" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::findAndModify</refname>
<refpurpose>Update a document and return it</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::findAndModify</methodname>
<methodparam><type>array</type><parameter>query</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>update</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>fields</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
The findAndModify command atomically modifies and returns a single document.
By default, the returned document does not include the modifications made on
the update. To return the document with the modifications made on the
update, use the <varname>new</varname> option.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>query</parameter></term>
<listitem>
<para>
The query criteria to search for.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>update</parameter></term>
<listitem>
<para>
The update criteria.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>fields</parameter></term>
<listitem>
<para>
Optionally only return these fields.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>options</parameter></term>
<listitem>
<para>
An array of options to apply, such as remove the match document from the
DB and return it.
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Option</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry><varname>sort</varname> <type>array</type></entry>
<entry>
Determines which document the operation will modify if the
query selects multiple documents. findAndModify will modify the
first document in the sort order specified by this argument.
</entry>
</row>
<row>
<entry><varname>remove</varname> <type>bool</type></entry>
<entry>
Optional if <varname>update</varname> field exists. When &true;, removes the selected
document. The default is &false;.
</entry>
</row>
<row>
<entry><varname>update</varname> <type>array</type></entry>
<entry>
Optional if <varname>remove</varname> field exists.
Performs an update of the selected document.
</entry>
</row>
<row>
<entry><varname>new</varname> <type>bool</type></entry>
<entry>
Optional. When &true;, returns the modified document rather than the
original. The findAndModify method ignores the <varname>new</varname> option for
remove operations. The default is &false;.
</entry>
</row>
<row>
<entry><varname>upsert</varname> <type>bool</type></entry>
<entry>
Optional. Used in conjunction with the <varname>update</varname> field. When &true;, the
findAndModify command creates a new document if the query returns
no documents. The default is false. In MongoDB 2.2, the
findAndModify command returns &null; when upsert is &true;.
</entry>
</row>
<row>
<entry><varname></varname></entry>
<entry>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the original document, or the modified document when
<varname>new</varname> is set.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoResultException</classname> on failure.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example xml:id="mongocollection.findandmodify.example.basic">
<title><methodname>MongoCollection::findAndModify</methodname> example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo;
$col = $m->selectDB("test")->jobs;
$col->insert(array(
"name" => "Next promo",
"inprogress" => false,
"priority" => 0,
"tasks" => array( "select product", "add inventory", "do placement"),
) );
$col->insert(array(
"name" => "Biz report",
"inprogress" => false,
"priority" => 1,
"tasks" => array( "run sales report", "email report" )
) );
$col->insert(array(
"name" => "Biz report",
"inprogress" => false,
"priority" => 2,
"tasks" => array( "run marketing report", "email report" )
),
array("w" => 1)
);
$retval = $col->findAndModify(
array("inprogress" => false, "name" => "Biz report"),
array('$set' => array('inprogress' => true, "started" => new MongoDate())),
null,
array(
"sort" => array("priority" => -1),
"new" => true,
)
);
var_dump($retval);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
array(6) {
["_id"]=>
object(MongoId)#7 (1) {
["$id"]=>
string(24) "5091b5b244415e8cc3000002"
}
["inprogress"]=>
bool(true)
["name"]=>
string(10) "Biz report"
["priority"]=>
int(2)
["started"]=>
object(MongoDate)#8 (2) {
["sec"]=>
int(1351726514)
["usec"]=>
int(925000)
}
["tasks"]=>
array(2) {
[0]=>
string(20) "run marketing report"
[1]=>
string(12) "email report"
}
}
]]>
</screen>
</example>
<example xml:id="mongocollection.findandmodify.example.error">
<title><methodname>MongoCollection::findAndModify</methodname> error handling</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo;
$col = $m->selectDB("test")->jobs;
try {
$retval = $col->findAndModify(
array("inprogress" => false, "name" => "Next promo"),
array('$pop' => array("tasks" => -1)),
array("tasks" => array('$pop' => array("stuff"))),
array("new" => true)
);
} catch(MongoResultException $e) {
echo $e->getCode(), " : ", $e->getMessage(), "\n";
var_dump($e->getDocument());
}
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
13097 : exception: Unsupported projection option: $pop
array(3) {
["errmsg"]=>
string(46) "exception: Unsupported projection option: $pop"
["code"]=>
int(13097)
["ok"]=>
float(0)
}
]]>
</screen>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member>The MongoDB <link xlink:href="&url.mongodb.docs.command;findAndModify/">findAndModify command</link> docs</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
-->

196
reference/mongo/mongocollection/findone.xml
View file

@ -1,196 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.findone" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::findOne</refname>
<refpurpose>Queries this collection, returning a single element</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::findOne</methodname>
<methodparam choice="opt"><type>array</type><parameter>query</parameter><initializer>array()</initializer></methodparam>
<methodparam choice="opt"><type>array</type><parameter>fields</parameter><initializer>array()</initializer></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
</methodsynopsis>
<para>
As opposed to <function>MongoCollection::find</function>, this method
will return only the <emphasis>first</emphasis> result from the result set,
and not a <classname>MongoCursor</classname> that can be iterated over.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>query</parameter>
</term>
<listitem>
<para>
The fields for which to search. MongoDB's query language is quite
extensive. The PHP driver will in almost all cases pass the query
straight through to the server, so reading the MongoDB core docs on
<link xlink:href="&url.mongodb.dochub.find;">find</link> is a good idea.
</para>
<warning>
<para>
Please make sure that for all special query operaters (starting with
<literal>$</literal>) you use single quotes so that PHP doesn't try to
replace <literal>"$exists"</literal> with the value of the variable
<literal>$exists</literal>.
</para>
</warning>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>fields</parameter>
</term>
<listitem>
<para>
Fields of the results to return. The array is in the format
<literal>array('fieldname' => true, 'fieldname2' => true)</literal>.
The <literal>_id</literal> field is always returned.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>options</parameter>
</term>
<listitem>
<para>
This parameter is an associative array of the form
<literal>array("name" => &lt;value&gt;, ...)</literal>. Currently
supported options are:
</para>
<itemizedlist>
&mongo.command.parameters.maxtimems;
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns record matching the search or &null;.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoConnectionException</classname> if it cannot reach the
database.
</para>
</refsect1>
<refsect1 role="changelog"><!-- {{{ -->
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>PECL mongo 1.5.0</entry>
<entry>
Added optional <parameter>options</parameter> argument.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1><!-- }}} -->
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><methodname>MongoCollection::findOne</methodname> document by its id.</title>
<para>This example demonstrates how to find a single document in a collection by its id.</para>
<programlisting role="php">
<![CDATA[
<?php
$articles = $mongo->my_db->articles;
$article = $articles->findOne(array('_id' => new MongoId('47cc67093475061e3d9536d2')));
?>
]]>
</programlisting>
</example>
<example>
<title><methodname>MongoCollection::findOne</methodname> document by some condition.</title>
<para>This example demonstrates how to find a single document in a collection by some condition and limiting the returned fields.</para>
<programlisting role="php">
<![CDATA[
<?php
$users = $mongo->my_db->users;
$user = $users->findOne(array('username' => 'jwage'), array('password'));
print_r($user);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Array
(
[_id] => MongoId Object
(
)
[password] => test
)
]]>
</screen>
<para>
Notice how even though the document does have a username field, we limited the results
to only contain the password field.
</para>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>MongoCollection::find</function></member>
<member><function>MongoCollection::insert</function></member>
<member>MongoDB core docs on <link xlink:href="&url.mongodb.dochub.find;">find</link>.</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
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
-->

76
reference/mongo/mongocollection/get.xml
View file

@ -1,76 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.get" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::__get</refname>
<refpurpose>Gets a collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>MongoCollection</type><methodname>MongoCollection::__get</methodname>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
</methodsynopsis>
<para>
A concise syntax for getting a collection with a dot-separated name. If a
collection name contains strange characters, you may have to use
<function>MongoDB::selectCollection</function> instead.
<programlisting role="php">
<![CDATA[
<?php
$mongo = new MongoClient();
// the following two lines are equivalent
$collection = $mongo->selectDB("foo")->selectCollection("bar.baz");
$collection = $mongo->foo->bar->baz;
?>
]]>
</programlisting>
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>name</parameter>
</term>
<listitem>
<para>
The next string in the collection name.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the collection.
</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
-->

113
reference/mongo/mongocollection/getdbref.xml
View file

@ -1,113 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.getdbref" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::getDBRef</refname>
<refpurpose>Fetches the document pointed to by a database reference</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::getDBRef</methodname>
<methodparam><type>array</type><parameter>ref</parameter></methodparam>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>ref</parameter>
</term>
<listitem>
<para>
A database reference.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the database document pointed to by the reference.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><methodname>MongoCollection::getDBRef</methodname> example</title>
<programlisting role="php">
<![CDATA[
<?php
$playlists = $db->playlists;
$myList = $playlists->findOne(array('username' => 'me'));
// fetch each song in the playlist
foreach ($myList['songlist'] as $songRef) {
$song = $playlists->getDBRef($songRef);
echo $song['title'] . "\n";
}
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Dazed and Confused
Ma na ma na
Bohemian Rhapsody
]]>
</screen>
<screen>
In the above example each $songRef looks something like the following:
<![CDATA[
Array
(
[$ref] => songs
[$id] => 49902cde5162504500b45c2c
)
]]>
</screen>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><methodname>MongoCollection::createDBRef</methodname></member>
</simplelist>
</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
-->

149
reference/mongo/mongocollection/getindexinfo.xml
View file

@ -1,149 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.getindexinfo" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::getIndexInfo</refname>
<refpurpose>Returns information about indexes on this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::getIndexInfo</methodname>
<void/>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
This function returns an array in which each element describes an index.
Elements will contain the values <literal>name</literal> for the name of
the index, <literal>ns</literal> for the namespace (a combination of the
database and collection name), and <literal>key</literal> for a list of all
fields in the index and their ordering. Additional values may be present for
special indexes, such as <literal>unique</literal> or
<literal>sparse</literal>.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::getIndexInfo</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$c = $m->selectCollection('test', 'venues');
var_dump($c->getIndexInfo());
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
array(4) {
[0]=>
array(4) {
["v"]=>
int(1)
["key"]=>
array(1) {
["_id"]=>
int(1)
}
["name"]=>
string(4) "_id_"
["ns"]=>
string(11) "test.venues"
}
[1]=>
array(4) {
["v"]=>
int(1)
["key"]=>
array(1) {
["name"]=>
float(1)
}
["name"]=>
string(6) "name_1"
["ns"]=>
string(11) "test.venues"
}
[2]=>
array(4) {
["v"]=>
int(1)
["key"]=>
array(2) {
["type"]=>
float(1)
["createdAt"]=>
float(-1)
}
["name"]=>
string(19) "type_1_createdAt_-1"
["ns"]=>
string(11) "test.venues"
}
[3]=>
array(5) {
["v"]=>
int(1)
["key"]=>
array(1) {
["location"]=>
string(8) "2dsphere"
}
["name"]=>
string(17) "location_2dsphere"
["ns"]=>
string(11) "test.venues"
["2dsphereIndexVersion"]=>
int(2)
}
}
]]>
</screen>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
MongoDB core docs on
<link xlink:href="&url.mongodb.dochub.indexes;">vanilla indexes</link> and
<link xlink:href="&url.mongodb.dochub.geo;">geospatial indexes</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
-->

77
reference/mongo/mongocollection/getname.xml
View file

@ -1,77 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.getname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::getName</refname>
<refpurpose>Returns this collection&apos;s name</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>string</type><methodname>MongoCollection::getName</methodname>
<void />
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the name of this collection.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>MongoCollection::getName</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$c = $m->foo->bar->baz;
echo "Working with collection " . $c->getName() . ".\n";
// the full namespace is given by the MongoCollection::__toString() method
echo "Working in namespace $c.\n";
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Working with collection bar.baz.
Working in namespace foo.bar.baz.
]]>
</screen>
</example>
</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
-->

135
reference/mongo/mongocollection/getreadpreference.xml
View file

@ -1,135 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.getreadpreference" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::getReadPreference</refname>
<refpurpose>Get the read preference for this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::getReadPreference</methodname>
<void />
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
&mongo.getreadpreference.returnvalues;
</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 mongo 1.3.3</entry>
<entry>
The return value has changed to be consistent with
<methodname>MongoCollection::setReadPreference</methodname>. The
<literal>type</literal> value was changed from a number to a string,
<literal>type_string</literal> was removed, and
<literal>tagsets</literal> now expresses tags as key/value pairs instead
of colon-delimited strings.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><methodname>MongoCollection::getReadPreference</methodname> return value example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$c = $m->test->users;
$c->setReadPreference(MongoClient::RP_SECONDARY, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
array(),
));
var_dump($c->getReadPreference());
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(2) {
["type"]=>
string(9) "secondary"
["tagsets"]=>
array(3) {
[0]=>
array(2) {
["dc"]=>
string(4) "east"
["use"]=>
string(9) "reporting"
}
[1]=>
array(1) {
["dc"]=>
string(7) "west"
}
[2]=>
array(0) {
}
}
}
]]>
</screen>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member>The <link linkend="mongo.readpreferences">read preferences</link> documentation.</member>
<member><function>MongoCollection::setReadPreference</function></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
-->

84
reference/mongo/mongocollection/getslaveokay.xml
View file

@ -1,84 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.getslaveokay" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::getSlaveOkay</refname>
<refpurpose>Get slaveOkay setting for this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>MongoCollection::getSlaveOkay</methodname>
<void/>
</methodsynopsis>
<para>
See <link linkend="mongo.queries">the query section</link> of this manual for
information on distributing reads to secondaries.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the value of slaveOkay for this instance.
</para>
</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 mongo 1.2.11</entry>
<entry>Emits <constant>E_DEPRECATED</constant> when used.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="seealso"><!-- {{{ -->
&reftitle.seealso;
<simplelist>
<member><xref linkend="mongo.readpreferences" /></member>
<member><methodname>MongoCollection::getReadPreference</methodname></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
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
-->

94
reference/mongo/mongocollection/getwriteconcern.xml
View file

@ -1,94 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.getwriteconcern" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::getWriteConcern</refname>
<refpurpose>Get the write concern for this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::getWriteConcern</methodname>
<void />
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
&mongo.getwriteconcern.returnvalues;
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><methodname>MongoCollection::getWriteConcern</methodname> return value example</title>
<programlisting role="php">
<![CDATA[
<?php
$mc = new MongoClient('mongodb://localhost:27017', array('wTimeoutMS' => 500));
$coll = $mc->selectCollection('test', 'foo');
var_dump($coll->getWriteConcern());
$coll->setWriteConcern(1, 1000);
var_dump($coll->getWriteConcern());
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(2) {
["w"]=>
int(1)
["wtimeout"]=>
int(500)
}
array(2) {
["w"]=>
int(1)
["wtimeout"]=>
int(1000)
}
]]>
</screen>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member>The <link linkend="mongo.writeconcerns">write concern</link> documentation.</member>
<member><function>MongoCollection::setWriteConcern</function></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
-->

274
reference/mongo/mongocollection/group.xml
View file

@ -1,274 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.group" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::group</refname>
<refpurpose>Performs an operation similar to SQL's GROUP BY command</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::group</methodname>
<methodparam><type>mixed</type><parameter>keys</parameter></methodparam>
<methodparam><type>array</type><parameter>initial</parameter></methodparam>
<methodparam><type>MongoCode</type><parameter>reduce</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>keys</parameter>
</term>
<listitem>
<para>
Fields to group by. If an array or non-code object is passed, it will be
the key used to group results.
</para>
<para>1.0.4+: If <parameter>keys</parameter> is an instance of
<classname>MongoCode</classname>, <parameter>keys</parameter> will be treated as
a function that returns the key to group by (see the "Passing a
<parameter>keys</parameter> function" example below).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>initial</parameter>
</term>
<listitem>
<para>
Initial value of the aggregation counter object.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>reduce</parameter>
</term>
<listitem>
<para>
A function that takes two arguments (the current document and the
aggregation to this point) and does the aggregation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>options</parameter>
</term>
<listitem>
<para>
Optional parameters to the group command. Valid options include:
</para>
<itemizedlist>
<listitem>
<para>
<literal>"condition"</literal>
</para>
<para>
Criteria for including a document in the aggregation.
</para>
</listitem>
<listitem>
<para>
<literal>"finalize"</literal>
</para>
<para>
Function called once per unique key that takes the final output of the
reduce function.
</para>
</listitem>
&mongo.command.parameters.maxtimems;
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an array containing the result.
</para>
</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 mongo 1.5.0</entry>
<entry>Added <literal>"maxTimeMS"</literal> option.</entry>
</row>
<row>
<entry>PECL mongo 1.2.11</entry>
<entry>
Emits <constant>E_DEPRECATED</constant> when
<parameter>options</parameter> is <type>scalar</type>.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::group</function> example</title>
<para>
This groups documents by category and creates a list of names within that
category.
</para>
<programlisting role="php">
<![CDATA[
<?php
$collection->insert(array("category" => "fruit", "name" => "apple"));
$collection->insert(array("category" => "fruit", "name" => "peach"));
$collection->insert(array("category" => "fruit", "name" => "banana"));
$collection->insert(array("category" => "veggie", "name" => "corn"));
$collection->insert(array("category" => "veggie", "name" => "broccoli"));
$keys = array("category" => 1);
$initial = array("items" => array());
$reduce = "function (obj, prev) { prev.items.push(obj.name); }";
$g = $collection->group($keys, $initial, $reduce);
echo json_encode($g['retval']);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
[{"category":"fruit","items":["apple","peach","banana"]},{"category":"veggie","items":["corn","broccoli"]}]
]]>
</screen>
</example>
<example>
<title><function>MongoCollection::group</function> example</title>
<para>
This example doesn't use any key, so every document will be its own group.
It also uses a condition: only documents that match this condition will be
processed by the grouping function.
</para>
<programlisting role="php">
<![CDATA[
<?php
$collection->save(array("a" => 2));
$collection->save(array("b" => 5));
$collection->save(array("a" => 1));
// use all fields
$keys = array();
// set intial values
$initial = array("count" => 0);
// JavaScript function to perform
$reduce = "function (obj, prev) { prev.count++; }";
// only use documents where the "a" field is greater than 1
$condition = array('condition' => array("a" => array( '$gt' => 1)));
$g = $collection->group($keys, $initial, $reduce, $condition);
var_dump($g);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
array(4) {
["retval"]=>
array(1) {
[0]=>
array(1) {
["count"]=>
float(1)
}
}
["count"]=>
float(1)
["keys"]=>
int(1)
["ok"]=>
float(1)
}
]]>
</screen>
</example>
<example>
<title>Passing a <parameter>keys</parameter> function</title>
<para>
If you want to group by something other than a field name, you can pass
a function as the first parameter of
<function>MongoCollection::group</function> and it will be run against each
document. The return value of the function will be used as its grouping
value.
</para>
<para>
This example demonstrates grouping by the num field modulo 4.
</para>
<programlisting role="php">
<![CDATA[
<?php
$c->group(new MongoCode('function(doc) { return {mod : doc.num % 4}; }'),
array("count" => 0),
new MongoCode('function(current, total) { total.count++; }'));
?>
]]>
</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
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
-->

453
reference/mongo/mongocollection/insert.xml
View file

@ -1,453 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.insert" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::insert</refname>
<refpurpose>Inserts a document into the collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type class="union"><type>bool</type><type>array</type></type><methodname>MongoCollection::insert</methodname>
<methodparam><type class="union"><type>array</type><type>object</type></type><parameter>document</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
</methodsynopsis>
<para>
All strings sent to the database must be UTF-8. If a string is not UTF-8, a
<classname>MongoException</classname> will be thrown. To insert
(or query for) a non-UTF-8 string, use <classname>MongoBinData</classname>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>document</parameter>
</term>
<listitem>
<para>
An array or object. If an object is used, it may not have protected or
private properties.
</para>
<note>
<para>
If the parameter does not have an <literal>_id</literal> key or
property, a new <classname>MongoId</classname> instance will be created
and assigned to it. This special behavior does not mean that the
parameter is passed by reference.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>options</parameter>
</term>
<listitem>
<para>
An array of options for the insert operation. Currently available options
include:
<itemizedlist>
&mongo.writes.parameters.fsync;
&mongo.writes.parameters.journal;
&mongo.writes.parameters.sockettimeoutms;
&mongo.writes.parameters.writeconcern;
&mongo.writes.parameters.writeconcerntimeoutms;
</itemizedlist>
</para>
<para>
The following options are deprecated and should no longer be used:
<itemizedlist>
&mongo.writes.parameters.safe;
&mongo.writes.parameters.timeout;
&mongo.writes.parameters.writeconcerntimeout;
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an array containing the status of the insertion if the
<literal>"w"</literal> option is set. Otherwise, returns &true; if the
inserted array is not empty (a <classname>MongoException</classname> will be
thrown if the inserted array is empty).
</para>
<para>
If an array is returned, the following keys may be present:
<variablelist>
<varlistentry>
<term>
<parameter>ok</parameter>
</term>
<listitem>
<para>
This should almost always be 1 (unless last_error itself failed).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>err</parameter>
</term>
<listitem>
<para>
If this field is non-null, an error occurred on the previous operation.
If this field is set, it will be a string describing the error that
occurred.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>code</parameter>
</term>
<listitem>
<para>
If a database error occurred, the relevant error code will be passed
back to the client.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>errmsg</parameter>
</term>
<listitem>
<para>
This field is set if something goes wrong with a database command. It
is coupled with <literal>ok</literal> being 0. For example, if
<literal>w</literal> is set and times out, errmsg will be set to "timed
out waiting for slaves" and <literal>ok</literal> will be 0. If this
field is set, it will be a string describing the error that occurred.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>n</parameter>
</term>
<listitem>
<para>
If the last operation was an update, upsert, or a remove, the number
of documents affected will be returned. For insert operations, this value
is always <literal>0</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>wtimeout</parameter>
</term>
<listitem>
<para>
If the previous option timed out waiting for replication.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>waited</parameter>
</term>
<listitem>
<para>
How long the operation waited before timing out.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>wtime</parameter>
</term>
<listitem>
<para>
If <literal>w</literal> was set and the operation succeeded, how long it took to
replicate to <literal>w</literal> servers.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>upserted</parameter>
</term>
<listitem>
<para>
If an upsert occurred, this field will contain the new record's
<literal>_id</literal> field. For upserts, either this field or
<literal>updatedExisting</literal> will be present (unless an error
occurred).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>updatedExisting</parameter>
</term>
<listitem>
<para>
If an upsert updated an existing element, this field will be true. For
upserts, either this field or upserted will be present (unless an error
occurred).
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoException</classname> if the inserted document is
empty or if it contains zero-length keys. Attempting to insert an object with
protected and private properties will cause a zero-length key error.
</para>
&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>PECL mongo 1.5.0</entry>
<entry>
<para>
Added the <literal>"wTimeoutMS"</literal> option, which replaces
<literal>"wtimeout"</literal>. Emits <constant>E_DEPRECATED</constant>
when <literal>"wtimeout"</literal> is used.
</para>
<para>
Added the <literal>"socketTimeoutMS"</literal> option, which replaces
<literal>"timeout"</literal>. Emits <constant>E_DEPRECATED</constant>
when <literal>"timeout"</literal> is used.
</para>
<para>
Emits <constant>E_DEPRECATED</constant> when <literal>"safe"</literal>
is used.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.3.4</entry>
<entry>Added <literal>"wtimeout"</literal> option.</entry>
</row>
<row>
<entry>PECL mongo 1.3.0</entry>
<entry>
<para>Added <literal>"w"</literal> option.</para>
<para>
The <parameter>options</parameter> parameter no longer accepts a
boolean to signify an acknowledged write. Instead, this now has to be
done with <literal>array('w' => 1)</literal> (the default behaviour of
<classname>MongoClient</classname>).
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.2.0</entry>
<entry>Added <literal>"timeout"</literal> option.</entry>
</row>
<row>
<entry>PECL mongo 1.0.11</entry>
<entry>
Disconnects on "not master" errors if <literal>"safe"</literal> is set.
</entry>
</row>
<row>
<entry>PECL mongo 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>PECL mongo 1.0.2</entry>
<entry>
Changed second parameter to be an array of options. Pre-1.0.2, the
second parameter was a boolean indicating the <literal>"safe"</literal>
option.
</entry>
</row>
<row>
<entry>PECL mongo 1.0.1</entry>
<entry>
Throw a <classname>MongoCursorException</classname> if the
<literal>"safe"</literal> option is set and the insert fails.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::insert</function> <literal>_id</literal> example</title>
<para>
An <literal>_id</literal> field will be added to the inserted document if
not already present. Depending on how the parameter is passed, a generated
<literal>_id</literal> may or may not be available to calling code.
</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$collection = $m->selectCollection('test', 'phpmanual');
// If an array literal is used, there is no way to access the generated _id
$collection->insert(array('x' => 1));
// The _id is available on an array passed by value
$a = array('x' => 2);
$collection->insert($a);
var_dump($a);
// The _id is not available on an array passed by reference
$b = array('x' => 3);
$ref = &$b;
$collection->insert($ref);
var_dump($ref);
// The _id is available if a wrapping function does not trigger copy-on-write
function insert_no_cow($collection, $document)
{
$collection->insert($document);
}
$c = array('x' => 4);
insert_no_cow($collection, $c);
var_dump($c);
// The _id is not available if a wrapping function triggers copy-on-write
function insert_cow($collection, $document)
{
$document['y'] = 1;
$collection->insert($document);
}
$d = array('x' => 5);
insert_cow($collection, $d);
var_dump($d);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
array(2) {
["x"]=>
int(2)
["_id"]=>
object(MongoId)#4 (0) {
}
}
array(1) {
["x"]=>
int(3)
}
array(2) {
["x"]=>
int(4)
["_id"]=>
object(MongoId)#5 (0) {
}
}
array(1) {
["x"]=>
int(5)
}
]]>
</screen>
</example>
<example>
<title><function>MongoCollection::insert</function> acknowledged write example</title>
<para>
This example shows inserting two elements with the same _id, which causes
a <classname>MongoCursorException</classname> to be thrown, as
<parameter>w</parameter> was set.
</para>
<programlisting role="php">
<![CDATA[
<?php
$person = array("name" => "Joe", "age" => 20);
$collection->insert($person);
// now $person has an _id field, so if we save it
// again, we will get an exception
try {
$collection->insert($person, array("w" => 1));
} catch(MongoCursorException $e) {
echo "Can't save the same person twice!\n";
}
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>MongoCollection::batchInsert</function></member>
<member><function>MongoCollection::update</function></member>
<member><function>MongoCollection::find</function></member>
<member><function>MongoCollection::remove</function></member>
<member>MongoDB core docs on <link xlink:href="&url.mongodb.dochub.insert;">insert</link>.</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
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
-->

122
reference/mongo/mongocollection/parallelcollectionscan.xml
View file

@ -1,122 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.parallelcollectionscan" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::parallelCollectionScan</refname>
<refpurpose>Returns an array of cursors to iterator over a full collection in parallel</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array[MongoCommandCursor]</type><methodname>MongoCollection::parallelCollectionScan</methodname>
<methodparam><type>int</type><parameter>num_cursors</parameter></methodparam>
</methodsynopsis>
<para>
This method returns an array of a maximum of <literal>num_cursors</literal>
cursors. An iteration over one of the returned cursors results in a partial
set of documents for a collection. Iteration over all the returned cursors
results in getting every document back from the collection.
</para>
<para>
This method is a wrapper for the <literal>parallelCollectionScan</literal>
MongoDB command.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>num_cursors</parameter>
</term>
<listitem>
<para>
The number of cursors to request from the server. Please note, that the
server can return less cursors than you requested.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an array of <classname>MongoCommandCursor</classname> objects.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::parallelCollectionScan</function> example</title>
<para>
Returning all documents in a collection by using multiple cursors.
</para>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient;
$c = $m->demo->cities;
/* Request three cursors */
$cursors = $c->parallelCollectionScan( 3 );
/* Add all the cursors to the MultipleIterator */
$mi = new MultipleIterator( MultipleIterator::MIT_NEED_ANY );
foreach ( $cursors as $cursor )
{
$mi->attachIterator( $cursor );
}
/* Iterate over all the associated cursors */
foreach ( $mi as $items )
{
foreach ( $items as $item )
{
if ( $item !== NULL )
{
echo $item['name'], "\n";
}
}
}
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><classname>MultipleIterator</classname></member>
<member><classname>MongoCommandCursor</classname></member>
<member><methodname>MongoDB::command</methodname></member>
</simplelist>
</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
-->

239
reference/mongo/mongocollection/remove.xml
View file

@ -1,239 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.remove" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::remove</refname>
<refpurpose>Remove records from this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type class="union"><type>bool</type><type>array</type></type><methodname>MongoCollection::remove</methodname>
<methodparam choice="opt"><type>array</type><parameter>criteria</parameter><initializer>array()</initializer></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry xml:id="mongocollection.remove.criteria">
<term>
<parameter>criteria</parameter>
</term>
<listitem>
<para>
Query criteria for the documents to delete.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>options</parameter>
</term>
<listitem>
<para>
An array of options for the remove operation. Currently available options
include:
<itemizedlist>
&mongo.writes.parameters.writeconcern;
<listitem xml:id="mongocollection.remove.justone">
<para>
<literal>"justOne"</literal>
</para>
<para>
Specify &true; to limit deletion to just one document. If &false; or
omitted, all documents matching the criteria will be deleted.
</para>
</listitem>
&mongo.writes.parameters.fsync;
&mongo.writes.parameters.journal;
&mongo.writes.parameters.sockettimeoutms;
&mongo.writes.parameters.writeconcern;
&mongo.writes.parameters.writeconcerntimeoutms;
</itemizedlist>
</para>
<para>
The following options are deprecated and should no longer be used:
<itemizedlist>
&mongo.writes.parameters.safe;
&mongo.writes.parameters.timeout;
&mongo.writes.parameters.writeconcerntimeout;
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns an array containing the status of the removal 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>PECL mongo 1.5.0</entry>
<entry>
<para>
Added <literal>"wTimeoutMS"</literal> option, which replaces
<literal>"wtimeout"</literal>. Emits <constant>E_DEPRECATED</constant>
when <literal>"wtimeout"</literal> is used.
</para>
<para>
Added <literal>"socketTimeoutMS"</literal> option, which replaces
<literal>"timeout"</literal>. Emits <constant>E_DEPRECATED</constant>
when <literal>"timeout"</literal> is used.
</para>
<para>
Emits <constant>E_DEPRECATED</constant> when <literal>"safe"</literal>
is used.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.3.4</entry>
<entry>Added <literal>"wtimeout"</literal> option.</entry>
</row>
<row>
<entry>PECL mongo 1.3.0</entry>
<entry>
<para>Added <literal>"w"</literal> option.</para>
<para>
The <parameter>options</parameter> parameter no longer accepts a
boolean to signify <literal>"justOne"</literal>. Instead, this now has
to be done with <literal>array('justOne' => true)</literal>.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.2.11</entry>
<entry>
Emits <constant>E_DEPRECATED</constant> when
<parameter>options</parameter> is <type>scalar</type>.
</entry>
</row>
<row>
<entry>PECL mongo 1.2.0</entry>
<entry>Added <literal>"timeout"</literal> option.</entry>
</row>
<row>
<entry>PECL mongo 1.0.11</entry>
<entry>
Disconnects on "not master" errors if <literal>"safe"</literal> is set.
</entry>
</row>
<row>
<entry>PECL mongo 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>PECL mongo 1.0.5</entry>
<entry>
Changed second parameter to be an array of options. Pre-1.0.5, the
second parameter was a boolean indicating the <literal>"safe"</literal>
option.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::remove</function> with justOne example</title>
<programlisting role="php">
<![CDATA[
<?php
$radioactive = $db->radioactive;
// count how much more plutonium there is
$remaining = $radioactive->count(array('type' => 94));
$halflife = $remaining/2;
// remove half of it
while ($halflife > 0) {
$radioactive->remove(array('type' => 94), array("justOne" => true));
$halflife--;
}
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>MongoCollection::insert</function></member>
<member><function>MongoCollection::update</function></member>
<member>MongoDB core docs on <link xlink:href="&url.mongodb.dochub.remove;">remove</link>.</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
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
-->

210
reference/mongo/mongocollection/save.xml
View file

@ -1,210 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.save" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::save</refname>
<refpurpose>Saves a document to this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>mixed</type><methodname>MongoCollection::save</methodname>
<methodparam><type class="union"><type>array</type><type>object</type></type><parameter>document</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
</methodsynopsis>
<para>
If the object is from the database, update the existing database object, otherwise
insert this object.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>document</parameter>
</term>
<listitem>
<para>
Array or object to save. If an object is used, it may not have protected
or private properties.
</para>
<note>
<para>
If the parameter does not have an <literal>_id</literal> key or
property, a new <classname>MongoId</classname> instance will be created
and assigned to it. See <function>MongoCollection::insert</function> for
additional information on this behavior.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>options</parameter>
</term>
<listitem>
<para>
Options for the save.
<itemizedlist>
&mongo.writes.parameters.fsync;
&mongo.writes.parameters.journal;
&mongo.writes.parameters.sockettimeoutms;
&mongo.writes.parameters.writeconcern;
&mongo.writes.parameters.writeconcerntimeout;
&mongo.writes.parameters.writeconcerntimeoutms;
&mongo.writes.parameters.safe;
&mongo.writes.parameters.timeout;
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
If <parameter>w</parameter> was set, returns an array containing the status of the save.
Otherwise, returns a boolean representing if the array was not empty (an empty array will not
be inserted).
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws <classname>MongoException</classname> if the inserted document is
empty or if it contains zero-length keys. Attempting to insert an object with
protected and private properties will cause a zero-length key error.
</para>
&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>PECL mongo 1.5.0</entry>
<entry>
<para>
Added <literal>"wTimeoutMS"</literal> option, which replaces
<literal>"wtimeout"</literal>. Emits <constant>E_DEPRECATED</constant>
when <literal>"wtimeout"</literal> is used.
</para>
<para>
Added <literal>"socketTimeoutMS"</literal> option, which replaces
<literal>"timeout"</literal>. Emits <constant>E_DEPRECATED</constant>
when <literal>"timeout"</literal> is used.
</para>
<para>
Emits <constant>E_DEPRECATED</constant> when <literal>"safe"</literal>
is used.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.2.0</entry>
<entry>Added <literal>"timeout"</literal> option.</entry>
</row>
<row>
<entry>PECL mongo 1.0.11</entry>
<entry>
Disconnects on "not master" errors if <literal>"safe"</literal> is set.
</entry>
</row>
<row>
<entry>PECL mongo 1.0.9</entry>
<entry>
<para>
Added <literal>"fsync"</literal> option.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.0.5</entry>
<entry>Added <parameter>options</parameter> parameter.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::save</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$obj = array('x' => 1);
// insert $obj into the db
$collection->save($obj);
var_dump($obj);
// add another field
$obj['foo'] = 'bar';
// $obj cannot be inserted again, causes duplicate _id error
$collection->insert($obj);
// save updates $obj with the new field
$collection->save($obj);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
array(2) {
["x"]=>
int(1)
["_id"]=>
object(MongoId)#4 (1) {
["$id"]=>
string(24) "50b6afe544415ed606000000"
}
}
]]>
</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
-->

86
reference/mongo/mongocollection/setreadpreference.xml
View file

@ -1,86 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.setreadpreference" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::setReadPreference</refname>
<refpurpose>Set the read preference for this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>MongoCollection::setReadPreference</methodname>
<methodparam><type>string</type><parameter>read_preference</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>tags</parameter></methodparam>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&mongo.setreadpreference.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
&mongo.setreadpreference.returnvalues;
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
&mongo.setreadpreference.errors;
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><methodname>MongoCollection::setReadPreference</methodname> tag set array syntax example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$c = $m->test->users;
// Prefer the nearest server in the "east" data center also used for reporting,
// but fall back to a server in the "west" data center
$c->setReadPreference(MongoClient::RP_NEAREST, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
));
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member>The <link linkend="mongo.readpreferences">read preferences</link> documentation.</member>
<member><function>MongoCollection::getReadPreference</function></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
-->

99
reference/mongo/mongocollection/setslaveokay.xml
View file

@ -1,99 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.setslaveokay" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::setSlaveOkay</refname>
<refpurpose>Change slaveOkay setting for this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>MongoCollection::setSlaveOkay</methodname>
<methodparam choice="opt"><type>bool</type><parameter>ok</parameter><initializer>&true;</initializer></methodparam>
</methodsynopsis>
<para>
See <link linkend="mongo.queries">the query section</link> of this manual for
information on distributing reads to secondaries.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>ok</parameter>
</term>
<listitem>
<para>
If reads should be sent to secondary members of a replica set for all
possible queries using this <classname>MongoCollection</classname>
instance.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the former value of slaveOkay for this instance.
</para>
</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 mongo 1.2.11</entry>
<entry>Emits <constant>E_DEPRECATED</constant> when used.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="seealso"><!-- {{{ -->
&reftitle.seealso;
<simplelist>
<member><xref linkend="mongo.readpreferences" /></member>
<member><methodname>MongoCollection::setReadPreference</methodname></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
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
-->

83
reference/mongo/mongocollection/setwriteconcern.xml
View file

@ -1,83 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.setwriteconcern" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::setWriteConcern</refname>
<refpurpose>Set the write concern for this database</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>MongoCollection::setWriteConcern</methodname>
<methodparam><type>mixed</type><parameter>w</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>wtimeout</parameter></methodparam>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&mongo.setwriteconcern.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
&mongo.setwriteconcern.returnvalues;
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
&mongo.setwriteconcern.errors;
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><methodname>MongoDB::setWriteConcern</methodname> example</title>
<programlisting role="php">
<![CDATA[
<?php
$mc = new MongoClient('mongodb://rs1.example.com,rs2.example.com');
$coll = $mc->selectCollection('test', 'foo');
// Require that the majority of servers in the replica set acknowledge writes
// within three seconds.
$coll->setWriteConcern('majority', 3000);
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member>The <link linkend="mongo.writeconcerns">write concern</link> documentation.</member>
<member><function>MongoCollection::getWriteConcern</function></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
-->

128
reference/mongo/mongocollection/toindexstring.xml
View file

@ -1,128 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.toindexstring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::toIndexString</refname>
<refpurpose>Converts keys specifying an index to its identifying string</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>static protected</modifier> <type>string</type><methodname>MongoCollection::toIndexString</methodname>
<methodparam><type>mixed</type><parameter>keys</parameter></methodparam>
</methodsynopsis>
<warning>
<para>
This method is deprecated since version 1.5.0.
</para>
</warning>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>keys</parameter>
</term>
<listitem>
<para>
Field or fields to convert to the identifying string
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a string that describes the index.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::toIndexString</function> example</title>
<para>This example shows how you can create an index name out of keys.
Because this is a protected (static) method, you need to overload it in a
child class first.</para>
<programlisting role="php">
<![CDATA[
<?php
// Create inherited class to make the method "public".
class MyCollection extends MongoCollection
{
static public function toIndexString($a)
{
return parent::toIndexString($a);
}
}
echo MyCollection::toIndexString("foo"), "\n";
// Outputs: foo_1
echo MyCollection::toIndexString(array('name' => 1, 'age' => -1)), "\n";
// Outputs: name_1_age_-1
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
MongoDB core docs on <link xlink:href="&url.mongodb.dochub.indexes;">indexes</link>.
</para>
</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 mongo 1.5.0</entry>
<entry>
This method has been deprecated.
</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
-->

77
reference/mongo/mongocollection/tostring.xml
View file

@ -1,77 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.--tostring" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::__toString</refname>
<refpurpose>String representation of this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>string</type><methodname>MongoCollection::__toString</methodname>
<void />
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the full name of this collection.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>MongoCollection::__toString</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient();
$c1 = $m->foo->bar->baz;
echo "Working with collection $c1.";
$c2 = $m->selectCollection('[]', '&');
echo "Working with collection $c2.";
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
Working with collection foo.bar.baz.
Working with collection [].&.
]]>
</screen>
</example>
</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
-->

395
reference/mongo/mongocollection/update.xml
View file

@ -1,395 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<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 class="union"><type>bool</type><type>array</type></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 xml:id="mongocollection.update.criteria">
<term>
<parameter>criteria</parameter>
</term>
<listitem>
<para>
Query criteria for the documents to update.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="mongocollection.update.new_object">
<term>
<parameter>new_object</parameter>
</term>
<listitem>
<para>
The object used to update the matched documents. This may either contain
update operators (for modifying specific fields) or be a replacement
document.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>options</parameter>
</term>
<listitem>
<para>
An array of options for the update operation. Currently available options
include:
<itemizedlist>
<listitem xml:id="mongocollection.update.upsert">
<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 xml:id="mongocollection.update.multiple">
<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.writeconcerntimeoutms;
</itemizedlist>
</para>
<para>
The following options are deprecated and should no longer be used:
<itemizedlist>
&mongo.writes.parameters.safe;
&mongo.writes.parameters.timeout;
&mongo.writes.parameters.writeconcerntimeout;
</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>PECL mongo 1.5.0</entry>
<entry>
<para>
Added the <literal>"wTimeoutMS"</literal> option, which replaces
<literal>"wtimeout"</literal>. Emits <constant>E_DEPRECATED</constant>
when <literal>"wtimeout"</literal> is used.
</para>
<para>
Added the <literal>"socketTimeoutMS"</literal> option, which replaces
<literal>"timeout"</literal>. Emits <constant>E_DEPRECATED</constant>
when <literal>"timeout"</literal> is used.
</para>
<para>
Emits <constant>E_DEPRECATED</constant> when <literal>"safe"</literal>
is used.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.3.4</entry>
<entry>Added <literal>"wtimeout"</literal> option.</entry>
</row>
<row>
<entry>PECL mongo 1.3.0</entry>
<entry>
<para>Added <literal>"w"</literal> option.</para>
<para>
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>.
</para>
</entry>
</row>
<row>
<entry>PECL mongo 1.2.11</entry>
<entry>
Emits <constant>E_DEPRECATED</constant> when
<parameter>options</parameter> is <type>scalar</type>.
</entry>
</row>
<row>
<entry>PECL mongo 1.2.0</entry>
<entry>Added <literal>"timeout"</literal> option.</entry>
</row>
<row>
<entry>PECL mongo 1.0.11</entry>
<entry>
Disconnects on "not master" errors if <literal>"safe"</literal> is set.
</entry>
</row>
<row>
<entry>PECL mongo 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>PECL mongo 1.0.5</entry>
<entry>Added <literal>"safe"</literal> option.</entry>
</row>
<row>
<entry>PECL mongo 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
-->

61
reference/mongo/mongocollection/validate.xml
View file

@ -1,61 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.validate" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::validate</refname>
<refpurpose>Validates this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::validate</methodname>
<methodparam choice="opt"><type>bool</type><parameter>scan_data</parameter><initializer>&false;</initializer></methodparam>
</methodsynopsis>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>scan_data</parameter>
</term>
<listitem>
<para>
Only validate indices, not the base collection.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the database&apos;s evaluation of this object.
</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
-->

132
reference/mongo/mongocommandcursor.xml
View file

@ -1,132 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<phpdoc:classref xml:id="class.mongocommandcursor" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>The MongoCommandCursor class</title>
<titleabbrev>MongoCommandCursor</titleabbrev>
<partintro>
<!-- {{{ MongocommandCursor intro -->
<section xml:id="mongocommandcursor.intro">
&reftitle.intro;
<para>
A command cursor is similar to a <classname>MongoCursor</classname> except
that you use it for iterating through the results of a database command
instead of a normal query. Command cursors are useful for iterating over
large result sets that might exceed the document size limit (currently 16MB)
of a single <function>MongoDB::command</function> response.
</para>
<para>
While you can create command cursors using
<function>MongoCommandCursor::__construct</function> or the
<function>MongoCommandCursor::createFromDocument</function> factory method,
you will generally want to use command-specific helpers such as
<function>MongoCollection::aggregateCursor</function>.
</para>
<para>
Note that the cursor does not "contain" the database command's results; it
just manages iteration through them. Thus, if you print a cursor (f.e. with
<function>var_dump</function> or <function>print_r</function>), you will see
the cursor object but not the result documents.
</para>
</section>
<section>
<title>Cursor Stages</title>
<para>
A <classname>MongoCommandCursor</classname> has two "life stages": pre-
and post- command. When a cursor is created, it has not yet contacted the
database, so it is in its pre-command state. When the client first attempts
to get a result (by calling <function>MongoCommandCursor::rewind</function>,
directly or indirectly), the cursor moves into the post-command state.
</para>
<para>
The command cursor's batch size and socket timeout may be configured in both
the pre- and post- command states.
</para>
<para>
<example xml:id="mongocommandcursor.stages.adding-options">
<title>Adding options to <classname>MongoCommandCursor</classname></title>
<programlisting role="php">
<![CDATA[
<?php
$cursor = new MongoCommandCursor(...);
$cursor = $cursor->batchSize( 4 );
foreach ($cursor as $result) {
var_dump($result);
}
?>
]]>
</programlisting>
</example>
</para>
</section>
<!-- }}} -->
<section xml:id="mongocommandcursor.synopsis">
&reftitle.classsynopsis;
<!-- {{{ Synopsis -->
<classsynopsis>
<ooclass><classname>MongoCommandCursor</classname></ooclass>
<!-- {{{ Class synopsis -->
<classsynopsisinfo>
<ooclass>
<classname>MongoCommandCursor</classname>
</ooclass>
<oointerface>
<interfacename>MongoCursorInterface</interfacename>
</oointerface>
<oointerface>
<interfacename>Iterator</interfacename>
</oointerface>
</classsynopsisinfo>
<!-- }}} -->
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongocommandcursor')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
</classsynopsis>
<!-- }}} -->
</section>
<section role="seealso">
&reftitle.seealso;
<simplelist>
<member><methodname>MongoDB::command</methodname></member>
<member><methodname>MongoCollection::aggregateCursor</methodname></member>
</simplelist>
</section>
</partintro>
&reference.mongo.entities.mongocommandcursor;
</phpdoc:classref>
<!-- 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
-->

93
reference/mongo/mongocommandcursor/batchsize.xml
View file

@ -1,93 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocommandcursor.batchsize" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCommandCursor::batchSize</refname>
<refpurpose>Limits the number of elements returned in one batch</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>MongoCommandCursor</type><methodname>MongoCommandCursor::batchSize</methodname>
<methodparam><type>int</type><parameter>batchSize</parameter></methodparam>
</methodsynopsis>
<para>
A cursor typically fetches a batch of result objects and store them
locally. This method sets the batchSize value to configure the amount of
documents retrieved from the server in one round trip.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>batchSize</parameter>
</term>
<listitem>
<para>
The number of results to return per batch. Each batch requires a
round-trip to the server.
</para>
<para>
This cannot override MongoDB's limit on the amount of data it will return to
the client (i.e., if you set batch size to 1,000,000,000, MongoDB will still
only return 4-16MB of results per batch).
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns this cursor.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCommandCursor::batchSize</function></title>
<programlisting role="php">
<![CDATA[
<?php
$commandCursor->batchSize(20);
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><methodname>MongoCursorInterface::batchSize</methodname></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
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
-->

142
reference/mongo/mongocommandcursor/construct.xml
View file

@ -1,142 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocommandcursor.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCommandCursor::__construct</refname>
<refpurpose>Create a new command cursor</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <methodname>MongoCommandCursor::__construct</methodname>
<methodparam><type>MongoClient</type><parameter>connection</parameter></methodparam>
<methodparam><type>string</type><parameter>ns</parameter></methodparam>
<methodparam><type>array</type><parameter>command</parameter><initializer>array()</initializer></methodparam>
</methodsynopsis>
<para>
Generally, you should not have to construct a
<classname>MongoCommandCursor</classname> manually, as there are helper
functions such as <methodname>MongoCollection::aggregateCursor</methodname>
and <methodname>MongoCollection::parallelCollectionScan</methodname>;
however, if the server introduces new commands that can return cursors, this
constructor will be useful in the absence of specific helper methods. You may
also consider using
<methodname>MongoCommandCursor::createFromDocument</methodname>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>connection</parameter>
</term>
<listitem>
<para>
Database connection.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>ns</parameter>
</term>
<listitem>
<para>
Full name of the database and collection (e.g.
<literal>"test.foo"</literal>)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>command</parameter>
</term>
<listitem>
<para>
Database command.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the new cursor.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><classname>MongoCommandCursor</classname> example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient;
// Define the aggregation pipeline
$pipeline = [
[ '$group' => [
'_id' => '$country_code',
'timezones' => [ '$addToSet' => '$timezone' ]
] ],
[ '$sort' => [ '_id' => 1 ] ],
];
// Construct a MongoCommandCursor object
$cursor = new MongoCommandCursor(
$m, // MongoClient object
'demo.cities', // namespace
[
'aggregate' => 'cities',
'pipeline' => $pipeline,
'cursor' => [ 'batchSize' => 0 ],
]
);
foreach($cursor as $result) {
…
}
?>
]]>
</programlisting>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>MongoCommandCursor::createFromDocument</function></member>
<member><function>MongoCollection::aggregateCursor</function></member>
<member><function>MongoCollection::parallelCollectionScan</function></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
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
-->

182
reference/mongo/mongocommandcursor/createfromdocument.xml
View file

@ -1,182 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocommandcursor.createfromdocument" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCommandCursor::createFromDocument</refname>
<refpurpose>Create a new command cursor from an existing command response document</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <modifier>static</modifier> <type>MongoCommandCursor</type><methodname>MongoCommandCursor::createFromDocument</methodname>
<methodparam><type>MongoClient</type><parameter>connection</parameter></methodparam>
<methodparam><type>string</type><parameter>hash</parameter></methodparam>
<methodparam><type>array</type><parameter>document</parameter></methodparam>
</methodsynopsis>
<para>
Use this method if you have a raw command result with cursor information in
it. Note that cursors created with this method cannot be iterated multiple
times, as they will lack the original command necessary for re-execution.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term>
<parameter>connection</parameter>
</term>
<listitem>
<para>
Database connection.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>hash</parameter>
</term>
<listitem>
<para>
The connection hash, as obtained through the third by-reference argument
to <methodname>MongoDB::command</methodname>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<parameter>document</parameter>
</term>
<listitem>
<para>
Document with cursor information in it. This document needs to contain
the <literal>id</literal>, <literal>ns</literal> and
<literal>firstBatch</literal> fields. Such a document is obtained by
calling the <methodname>MongoDB::command</methodname> with appropriate
arguments to return a cursor, and not just an inline result. See the
example below.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the new cursor.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCommandCursor::createFromDocument</function></title>
<programlisting role="php">
<![CDATA[
<?php
$m = new MongoClient;
$d = $m->demo;
// Define the aggregation pipeline
$pipeline = [
[ '$group' => [
'_id' => '$country_code',
'timezones' => [ '$addToSet' => '$timezone' ]
] ],
[ '$sort' => [ '_id' => 1 ] ],
];
// Execute the command. The "cursor" option instructs the server to return
// cursor information in the response instead of inline results.
$r = $d->command(
[
'aggregate' => 'cities',
'pipeline' => $pipeline,
'cursor' => [ 'batchSize' => 1 ],
],
null,
$hash
);
// Show result and hash
var_dump( $r, $hash );
// Construct the command cursor
$cursor = MongoCommandCursor::createFromDocument( $m, $hash, $r );
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
array(2) {
["cursor"]=>
array(3) {
["id"]=>
object(MongoInt64)#5 (1) {
["value"]=>
string(12) "392143983421"
}
["ns"]=>
string(11) "demo.cities"
["firstBatch"]=>
array(1) {
[0]=>
array(2) {
["_id"]=>
string(2) "AD"
["timezones"]=>
array(1) {
[0]=>
string(14) "Europe/Andorra"
}
}
}
}
["ok"]=>
float(1)
}
string(25) "localhost:27017;-;.;17617"
]]>
</screen>
<para>
As you can see, the returned cursor information has the
<literal>id</literal>, <literal>ns</literal> and
<literal>firstBatch</literal> fields.
</para>
</example>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>MongoCommandCursor::__construct</function></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
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
-->

59
reference/mongo/mongocommandcursor/current.xml
View file

@ -1,59 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocommandcursor.current" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCommandCursor::current</refname>
<refpurpose>Returns the current element</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCommandCursor::current</methodname>
<void/>
</methodsynopsis>
<para>
This returns &null; until <function>MongoCommandCursor::rewind</function> is called.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The current result document as an associative array. &null; will be returned
if there is no result.
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><methodname>Iterator::current</methodname></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
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
-->

62
reference/mongo/mongocommandcursor/dead.xml
View file

@ -1,62 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocommandcursor.dead" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCommandCursor::dead</refname>
<refpurpose>Checks if there are results that have not yet been sent from the database</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>MongoCommandCursor::dead</methodname>
<void/>
</methodsynopsis>
<para>
This method checks whether the <classname>MongoCommandCursor</classname>
cursor has been exhausted and the database has no more results to send to the
client. A cursor being "dead" does not necessarily mean that there are no
more results available for iteration.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns &true; if there are more results that have not yet been sent to the
client, and &false; otherwise.
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><methodname>MongoCursorInterface::dead</methodname></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
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
-->

Some files were not shown because too many files have changed in this diff Show more