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

updated connection doc for 1.0.2, added MongoId::getTimestamp

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@291996 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Kristina Chodorow 2009-12-11 17:15:46 +00:00
parent 79bb907445
commit d9a4e178e9
6 changed files with 310 additions and 68 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

70
reference/mongo/mongo.xml
View file

@ -14,8 +14,8 @@
The connection point between MongoDB and PHP.
</para>
<para>
This class is used to initiate a connection and for database server commands.
A typical use is:
This class is used to initiate a connection and for database server commands.
A typical use is:
<programlisting role="php">
<![CDATA[
<?php
@ -27,6 +27,56 @@ $db = $m->selectDatabase(); // get a database object
]]>
</programlisting>
</para>
<para>
This class has two static fields: <varname>Mongo::$connections</varname> and
<varname>Mongo::$pconnections</varname> which track the number of open
connections and persistent connections, respectively.
<varname>Mongo::$connections</varname> is inclusive, it basically counts all
open sockets, including persistent connections.
</para>
<para>
An example of how different types of connections affect these variables:
<programlisting>
<![CDATA[
<?php
/*
* start:
* Mongo::$connections is 0
* Mongo::$pconnections is 0
*/
$m1 = new Mongo();
/*
* Mongo::$connections is 1
* Mongo::$pconnections is 0
*/
$m2 = new Mongo("localhost", array("persist" => "foo"));
/*
* Mongo::$connections is 2
* Mongo::$pconnections is 1
*/
// reuse persistent connection
$m3 = new Mongo("localhost", array("persist" => "foo"));
/*
* Mongo::$connections is 2
* Mongo::$pconnections is 1
*/
?>
]]>
</programlisting>
</para>
<para>
See <function>Mongo::__construct</function> for more information about
creating connections.
</para>
</section>
<!-- }}} -->
@ -64,6 +114,22 @@ $db = $m->selectDatabase(); // get a database object
<initializer>27017</initializer>
</fieldsynopsis>
<classsynopsisinfo role="comment">Static Fields</classsynopsisinfo>
<fieldsynopsis>
<modifier>public</modifier>
<modifier>static</modifier>
<type>int</type>
<varname>connections</varname>
<initializer>0</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>public</modifier>
<modifier>static</modifier>
<type>int</type>
<varname>pconnections</varname>
<initializer>0</initializer>
</fieldsynopsis>
<classsynopsisinfo role="comment">Fields</classsynopsisinfo>
<fieldsynopsis>
<modifier>public</modifier>

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

@ -11,19 +11,33 @@
&reftitle.description;
<methodsynopsis>
<methodname>Mongo::__construct</methodname>
<methodparam choice="opt"><type>string</type><parameter>server</parameter><initializer>&null;</initializer></methodparam>
<methodparam choice="opt"><type>boolean</type><parameter>connect</parameter><initializer>&true;</initializer></methodparam>
<methodparam choice="opt"><type>boolean</type><parameter>persistent</parameter><initializer>&false;</initializer></methodparam>
<methodparam choice="opt"><type>boolean</type><parameter>paired</parameter><initializer>&false;</initializer></methodparam>
<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>
</methodsynopsis>
<para>
If no parameters are passed, this connects to "localhost:27017" and returns.
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>
If you elect not to connect immediately (<parameter>$connect</parameter> is
&false;), you will need to call <function>connect</function>,
<function>persistConnect</function>, <function>pairConnect</function>, or
<function>pairPersistConnect</function> before doing any database operations.
As of version 1.0.2, <parameter>server</parameter> can have a special form:
<literal>mongodb://[username:password@]host1[:port1][,host2[:port2:],...]</literal>.
Breaking this down, it starts with <literal>mongodb://</literal>, to indicate
it is in this form. If <literal>username</literal> and <literal>password</literal>
are specified, the constructor will attempt to authenticate the connection
with the admin database before returning. Username and password are optional
and must be followed by an <literal>@</literal>, if specified. 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>.
</para>
<para>
If you elect not to connect immediately (you pass the option
<literal>array("connect" => false)</literal>), you will need to call
<function>Mongo::connect</function> before doing any database operations.
</para>
<informalexample>
@ -31,7 +45,7 @@
<![CDATA[
<?php
$mongo = new Mongo("localhost", false);
$mongo = new Mongo("mongodb://localhost", array("connect" => false);
// throws a MongoException, as $mongo has not been fully initialized yet
$mongo->selectDB("foo")->command(array("distinct" => "bar", "key" => "age"));
@ -62,32 +76,38 @@ $mongo->selectDB("foo")->command(array("distinct" => "bar", "key" => "age"));
</varlistentry>
<varlistentry>
<term>
<parameter>connect</parameter>
<parameter>options</parameter>
</term>
<listitem>
<para>
If the constructor should connect to the database now. If this is
&false;, the constructor will return without connecting to the database.
</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.
An array of options for the connection. Currently available options
include:
<itemizedlist>
<listitem>
<para>
<literal>"connect"</literal>
</para>
<para>
If the constructor should connect before returning. Default is
&true;.
</para>
</listitem>
<listitem>
<para>
<literal>"persist"</literal>
</para>
<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>Mongo</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>
</itemizedlist>
</para>
</listitem>
</varlistentry>
@ -105,7 +125,78 @@ $mongo->selectDB("foo")->command(array("distinct" => "bar", "key" => "age"));
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws MongoConnectionException if it tries and fails to connect to the database.
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.
</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>1.0.2</entry>
<entry>
Changed constructor to take an array of options. Pre-1.0.2, the
constructor took the following parameters:
<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>
@ -122,16 +213,14 @@ $mongo->selectDB("foo")->command(array("distinct" => "bar", "key" => "age"));
<?php
// pass a comma-separated list of server names to the constructor
$m = new Mongo("www.example1.com,www.example2.com", false);
$m->pairConnect();
$m1 = new Mongo("mongodb://www.example1.com,www.example2.com");
// if the database servers are not running on the default port (27017),
// you'll need to specify the port
$m2 = new Mongo("www.example1.com:12345,www.example.com:54321", false);
$m2->pairConnect();
$m2 = new Mongo("mongodb://www.example1.com:12345,www.example.com:54321");
// you can also do a paired connection in one line of code
$m3 = new Mongo("www.example1.com,www.example.com", true, false, true);
// you can connect to more that two, as well
$m3 = new Mongo("mongodb://localhost:27017,localhost:27018,localhost:27019");
?>
]]>
@ -145,41 +234,63 @@ $m3 = new Mongo("www.example1.com,www.example.com", true, false, true);
reuse connections, as creating a connection is a time-intensive process.
</para>
<para>
A persistent connection is identified by the server string and optional
"username" and "password" strings. These strings are arbitrary and should
not be sensitive (i.e., a real password). They are merely indended as
unique identifiers for a connection.
A persistent connection is identified by the server string and and id
string.
</para>
<programlisting role="php">
<![CDATA[
<?php
// creates a persistent connection
$m1 = new Mongo("localhost", true, true);
$m1 = new Mongo("mongodb://localhost", array("persist" => ""));
// uses the same connection as $m1
$m2 = new Mongo("localhost", false);
$m2->persistConnect();
$m2 = new Mongo("mongodb://localhost", array("persist" => ""));
// creates a new connection
$m3 = new Mongo("127.0.0.1", false);
$m3->persistConnect();
$m3 = new Mongo("mongodb://127.0.0.1", array("persist" => ""));
// creates a new connection
$m4 = new Mongo("127.0.0.1:27017", false);
$m4->persistConnect();
$m4 = new Mongo("mongodb://127.0.0.1:27017", array("persist" => ""));
// creates a new connection
$m5 = new Mongo("localhost", false);
$m5->persistConnect("foo");
$m5 = new Mongo("mongodb://localhost", array("persist" => "foo"));
// uses the $m5 connection
$m6 = new Mongo("localhost", false);
$m6->persistConnect("foo");
$m6 = new Mongo("mongodb://localhost", array("persist" => "foo"));
// creates a new connection
$m7 = new Mongo("localhost", false);
$m7->persistConnect("foo", "bar");
?>
]]>
</programlisting>
</example>
<example>
<title><function>Mongo::__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>
<![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 Mongo("mongodb://testUser:testPass@localhost");
?>
]]>

9
reference/mongo/mongo/pairconnect.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="mongo.pairconnect" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Mongo::pairConnect</refname>
<refpurpose>Connects to paired database server</refpurpose>
<refpurpose>Connects to paired database server [deprecated]</refpurpose>
</refnamediv>
<refsect1 role="description">
@ -14,8 +14,8 @@
<void/>
</methodsynopsis>
<para>
To successfully create a paired connection, <literal>$this->server</literal> must be a string
of the form "server1,server2".
Pass a string of the form "mongodb://server1,server2" to the constructor
instead of using this method.
</para>
</refsect1>
@ -34,7 +34,8 @@
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws MongoConnectionException if it fails to connect to the databases.
Throws <classname>MongoConnectionException</classname> if it fails to connect
to the databases.
</para>
</refsect1>

9
reference/mongo/mongo/pairpersistconnect.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="mongo.pairpersistconnect" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Mongo::pairPersistConnect</refname>
<refpurpose>Creates a persistent connection with paired database servers</refpurpose>
<refpurpose>Creates a persistent connection with paired database servers [deprecated]</refpurpose>
</refnamediv>
<refsect1 role="description">
@ -14,6 +14,10 @@
<methodparam choice="opt"><type>string</type><parameter>username</parameter><initializer>""</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>password</parameter><initializer>""</initializer></methodparam>
</methodsynopsis>
<para>
Pass "mongodb://server1,server2" and <literal>array("persist" => $id)</literal>
to the constructor instead of using this method.
</para>
</refsect1>
<refsect1 role="parameters">
@ -54,7 +58,8 @@
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws MongoConnectionException if it fails to connect to the databases.
Throws <classname>MongoConnectionException</classname> if it fails to
connect to the databases.
</para>
</refsect1>

8
reference/mongo/mongo/persistconnect.xml
View file

@ -4,7 +4,7 @@
<refentry xml:id="mongo.persistconnect" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Mongo::persistConnect</refname>
<refpurpose>Creates a persistent connection with a database server</refpurpose>
<refpurpose>Creates a persistent connection with a database server [deprecated]</refpurpose>
</refnamediv>
<refsect1 role="description">
@ -14,6 +14,9 @@
<methodparam choice="opt"><type>string</type><parameter>username</parameter><initializer>""</initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>password</parameter><initializer>""</initializer></methodparam>
</methodsynopsis>
<para>
Pass <literal>array("persist" => $id)</literal> to the constructor instead of using this method.
</para>
</refsect1>
<refsect1 role="parameters">
@ -54,7 +57,8 @@
<refsect1 role="errors">
&reftitle.errors;
<para>
Throws MongoConnectionException if it fails to connect to the databases.
Throws <classname>MongoConnectionException</classname> if it fails to connect
to the databases.
</para>
</refsect1>

55
reference/mongo/mongoid/gettimestamp.xml Normal file
View file

@ -0,0 +1,55 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongoid.gettimestamp" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoId::getTimestamp</refname>
<refpurpose>Gets the number of seconds since the epoch that this id was created</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>int</type><methodname>MongoId::getTimestamp</methodname>
<void/>
</methodsynopsis>
<para>
This returns the same thing as running <function>time()</function> when the id is created.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the number of seconds since the epoch that this id was created. There are only
four bytes of timestamp stored, so <classname>MongoDate</classname> is a better choice
for storing exact or wide-ranging times.
</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
-->