php-doc-en/reference/mongo/tutorial.xml

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

<chapter xml:id="mongo.tutorial" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Tutorial</title>
 <para>
  This is the 10gen-supported PHP driver for MongoDB.
 </para>
 <para>Here's a quick code sample that connects, inserts documents, queries for
  documents, iterates through query results, and disconnects from MongoDB.
  There are more details on each step in the tutorial below.
 </para>
 <example xml:id="mongo.tutorial.basics">
  <programlisting role="php">
<![CDATA[
<?php

// connect
$m = new MongoClient();

// select a database
$db = $m->comedy;

// select a collection (analogous to a relational database's table)
$collection = $db->cartoons;

// add a record
$obj = array( "title" => "Calvin and Hobbes", "author" => "Bill Watterson" );
$collection->insert($obj);

// add another record, with a different "shape"
$obj = array( "title" => "XKCD", "online" => true );
$collection->insert($obj);

// find everything in the collection
$cursor = $collection->find();

// iterate through the results
foreach ($cursor as $obj) {
    echo $obj["title"] . "\n";
}

?>
]]>
  </programlisting>
  &example.outputs;
  <screen>
<![CDATA[
Calvin and Hobbes
XKCD
]]>
  </screen>
 </example>


 <section xml:id="mongo.tutorial.connecting">
  <title>Making a Connection</title>
  <para>
   To connect to the database server, use one of the following:
  </para>

  <example xml:id="mongo.tutorial.connecting-example">
   <programlisting role="php">
<![CDATA[
<?php

$connection = new MongoClient(); // connects to localhost:27017
$connection = new MongoClient( "example.com" ); // connect to a remote host (default port: 27017)
$connection = new MongoClient( "example.com:65432" ); // connect to a remote host at a given port

?>
]]>
   </programlisting>
  </example>
  <para>
   You do not have to explicitly disconnect from the database.  When
   <literal>$connection</literal> goes out of scope, the connection will be
   closed automatically and any database resources it was using will be freed.
  </para>
  <section xml:id="mongo.tutorial.connecting.seealso">
   <title>See Also</title>
   <para>
    The chapter on <link linkend="mongo.connecting">connecting</link>
    covers different types of connections.
   </para>
   <para>
    The API documentation on the <classname>MongoClient</classname> class and
    <function>MongoClient::__construct</function> give a comprehensive look at
    all possible options with a number of examples.
   </para>
  </section>
 </section>

  <section xml:id="mongo.tutorial.selectdb">
   <title>Getting a Database</title>
   <para>
    To select a database, use:
   </para>
   <example xml:id="mongo.tutorial.selectdb-example">
    <programlisting role="php">
<![CDATA[
<?php

$db = $connection->dbname;

?>
]]>
    </programlisting>
   </example>
   <para>
    The database does not need to be created in advance, you can create new
    databases by selecting them.
   </para>
   <para>
    Be careful of typos! You can inadvertently create a new database, which can
    cause confusing errors:

    <example xml:id="mongo.tutorial.selectdb.typo">
     <programlisting role="php">
<![CDATA[
<?php

$db = $connection->mybiglongdbname;
// do some stuff
$db = $connection->mybiglongdbanme;
// now connected to a different database!

?>
]]>
     </programlisting>
    </example>
   </para>
   <section xml:id="mongo.tutorial.selectdb.seealso">
    <title>See Also</title>
    <para>
     The API documentation on the <classname>MongoDB</classname> class contains
     more information about database objects.
    </para>
   </section>
  </section>

  <section xml:id="mongo.tutorial.collection">
   <title>Getting A Collection</title>
   <para>
    Getting a collection has the same syntax as getting a database:
   </para>
   <example xml:id="mongo.tutorial.collection-example">
    <programlisting role="php">
<![CDATA[
<?php

$db = $connection->baz;
$collection = $db->foobar;

// or, more succinctly
$collection = $connection->baz->foobar;

?>
]]>
    </programlisting>
   </example>
   <para>
    A collection is analogous to a table (if you are familiar with relational
    databases).
   </para>
   <section xml:id="mongo.tutorial.collection.seealso">
    <title>See Also</title>
    <para>
     The API documentation on the <classname>MongoCollection</classname> class
     contains more information about collection objects.
    </para>
   </section>
  </section>

  <section xml:id="mongo.tutorial.insert">
   <title>Inserting a Document</title>
   <para>
    Associative arrays are the basic object that can be saved to a collection in
    the database. A somewhat random "document" might be:
   </para>
   <example xml:id="mongo.tutorial.insert-data-example">
    <programlisting role="php">
<![CDATA[
<?php

$doc = array( "name" => "MongoDB",
   "type" => "database",
   "count" => 1,
   "info" => (object)array( "x" => 203, "y" => 102),
   "versions" => array("0.9.7", "0.9.8", "0.9.9")
);

?>
]]>
    </programlisting>
   </example>
   <para>
    Note that you can have nested arrays and objects.
   </para>
   <para>
    To insert this document, use <function>MongoCollection::insert</function>:
   </para>
   <example xml:id="mongo.tutorial.insert-example-2">
    <programlisting role="php">
<![CDATA[
<?php

$collection->insert( $doc );

?>
]]>
    </programlisting>
   </example>
   <section xml:id="mongo.tutorial.insert.seealso">
    <title>See Also</title>
    <para>
     The API documentation on <function>MongoCollection::insert</function>
     contains more information about inserting data.
    </para>
   </section>
  </section>

  <section xml:id="mongo.tutorial.findone">
   <title>
    Finding Documents using <function>MongoCollection::findOne</function>
   </title>
   <para>
    To show that the document we inserted in the previous step is there, we can
    do a simple <function>MongoCollection::findOne</function> operation to get a
    single document from the collection. This method is useful when there only is
    one document matching the query or you are only interested in one result.
   </para>
   <example xml:id="mongo.tutorial.findone-example">
    <programlisting role="php">
<![CDATA[
<?php

$obj = $collection->findOne();
var_dump( $obj );

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(6) {
  ["_id"]=>
  object(MongoId)#8 (1) {
    ["$id"]=>
    string(24) "4e2995576803fab768000000"
  }
  ["name"]=>
  string(7) "MongoDB"
  ["type"]=>
  string(8) "database"
  ["count"]=>
  int(1)
  ["info"]=>
  array(2) {
    ["x"]=>
    int(203)
    ["y"]=>
    int(102)
  }
  ["versions"]=>
  array(3) {
    [0]=>
    string(5) "0.9.7"
    [1]=>
    string(5) "0.9.8"
    [2]=>
    string(5) "0.9.9"
  }
}
]]>
    </screen>
   </example>
   <para>
    Note that there is an <literal>_id</literal> field that has been added
    automatically to your document. <literal>_id</literal> is the "primary key"
    field.  If your document does not specify one, the driver will add one
    automatically.
   </para>
   <para>
    If you specify your own <literal>_id</literal> field, it must be unique to
    the collection.  See the example here:
   </para>
   <example xml:id="mongo.tutorial.findone-example-2">
    <programlisting role="php">
<![CDATA[
<?php

$db->foo->insert(array("_id" => 1), array("w" => 1));
// this will throw an exception
$db->foo->insert(array("_id" => 1), array("w" => 1));

// this is fine, as it is a different collection
$db->bar->insert(array("_id" => 1), array("w" => 1));

?>
]]>
    </programlisting>
   </example>
   <para>
    Note that these inserts pass a second array:
    <literal>array("safe" => true)</literal>.  This second field specifies
    options for the insert.  By default, the driver does not wait for a database
    response for writes, so the driver would not catch the the
    <literal>_id</literal>.  As we specify that this is a "safe" write, the
    driver will wait for a database response and see that the write did not go
    through.  In general, all writes should use the "safe" option (it is omitted
    in previous examples for simplicity).
   </para>
   <section xml:id="mongo.tutorial.findone.seealso">
    <title>See Also</title>
    <para>
     <function>MongoCollection::findOne</function> for more information about
     finding data.
    </para>
    <para>
     <classname>MongoId</classname> goes into more detail on unique ids.
    </para>
    <para>
     The <link linkend="mongo.writes">writes</link> section covers safe
     writes in more depth, as do the writing functions such as
     <function>MongoCollection::insert</function>,
     <function>MongoCollection::update</function>, and
     <function>MongoCollection::remove</function>.
    </para>
   </section>
  </section>

  <section xml:id="mongo.tutorial.insert.multiple">
   <title>Adding Multiple Documents</title>
   <para>
    In order to do more interesting things with queries, let's add multiple
    simple documents to the collection. These documents will just be of the form
    <literal>array( "i" => <replaceable>value</replaceable> );</literal> and we
    can do this fairly efficiently in a loop:
   </para>
   <example xml:id="mongo.tutorial.insert.multiple-example">
    <programlisting role="php">
<![CDATA[
<?php

for($i=0; $i<100; $i++) {
    $collection->insert( array( "i" => $i ) );
}

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

   <para>
    Notice that we can insert arrays with different key sets into the same
    collection. This aspect is what we mean when we say that MongoDB is
    "schema-free".
   </para>
  </section>

  <section xml:id="mongo.tutorial.counting">
   <title>Counting Documents in A Collection</title>
   <para>
    Now that we've inserted 101 documents (the 100 we did in the loop, plus the
    first one), we can check to see if we have them all using the
    <function>MongoCollection::count</function> method.
    <example xml:id="mongo.tutorial.counting-example">
     <programlisting role="php">
<![CDATA[
<?php

echo $collection->count();

?>
]]>
     </programlisting>
    </example>
    and it should print 101.
   </para>
  </section>

  <section xml:id="mongo.tutorial.cursor">
   <title>Using a Cursor to Get All of the Documents</title>
   <para>
    In order to get all the documents in the collection, we will use
    <function>MongoCollection::find</function>. The find() method returns a
    <classname>MongoCursor</classname> object which allows us to iterate over the
    set of documents that matched our query. So to query all of the documents and
    print them out:

    <example xml:id="mongo.tutorial.cursor-example">
     <programlisting role="php">
<![CDATA[
<?php

$cursor = $collection->find();
foreach ($cursor as $id => $value) {
    echo "$id: ";
    var_dump( $value );
}

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

    and that should print all 101 documents in the collection.
    <literal>$id</literal> is the <literal>_id</literal> field of a document
    (cast to a string) and <literal>$value</literal> is the document itself.
   </para>
   <section xml:id="mongo.tutorial.cursor.seealso">
    <title>See Also</title>
    <para>
     The API documentation on <function>MongoCollection::find</function>
     contains more information about finding data.
    </para>
   </section>
  </section>

  <section xml:id="mongo.tutorial.criteria">
   <title>Setting Criteria for a Query</title>
   <para>
    We can create a query to pass to the
    <function>MongoCollection::find</function> method to get a subset of the
    documents in our collection. For example, if we wanted to find the document
    for which the value of the "i" field is 71, we would do the following:
   </para>
   <example xml:id="mongo.tutorial.criteria-example">
    <programlisting role="php">
<![CDATA[
<?php

$query = array( "i" => 71 );
$cursor = $collection->find( $query );

while( $cursor->hasNext() ) {
    var_dump( $cursor->getNext() );
}

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(2) {
  ["_id"]=>
  object(MongoId)#6 (0) {
  }
  ["i"]=>
  int(71)
  ["_ns"]=>
  "testCollection"
}
]]>
    </screen>
   </example>
  </section>

  <section xml:id="mongo.tutorial.multi.query">
   <title>Getting A Set of Documents With a Query</title>
   <para>
    We can use the query to get a set of documents from our collection. For
    example, if we wanted to get all documents where "i" &gt; 50, we could write:
   </para>
   <example xml:id="mongo.tutorial.multi.query-example">
    <programlisting role="php">
<![CDATA[
<?php

$query = array( "i" => array( '$gt' => 50 ) ); //note the single quotes around '$gt'
$cursor = $coll->find( $query );

while( $cursor->hasNext() ) {
    var_dump( $cursor->getNext() );
}

?>
]]>
    </programlisting>
    <para>
     which should print the documents where i &gt; 50. We could also get a range, say
     20 &lt; i &lt;= 30:
    </para>
    <screen>
<![CDATA[
<?php

$query = array( "i" => array( "\$gt" => 20, "\$lte" => 30 ) );
$cursor = $coll->find( $query );

while( $cursor->hasNext() ) {
    var_dump( $cursor->getNext() );
}

?>
]]>
    </screen>
   </example>
   <para>
    Remember to always escape the $-symbol or use single quotes.  Otherwise PHP
    will interpret it to be the variable <varname>$gt</varname>.
   </para>
  </section>

  <section xml:id="mongo.tutorial.indexes">
   <title>Creating An Index</title>
   <para>
    MongoDB supports indexes, and they are very easy to add on a collection. To
    create an index, you specify the field name and direction: ascending (1) or
    descending (-1). The following creates an ascending index on the "i" field:
   </para>
   <example xml:id="mongo.tutorial.indexes-example">
    <programlisting role="php">
<![CDATA[
<?php

$coll->ensureIndex( array( "i" => 1 ) );  // create index on "i"
$coll->ensureIndex( array( "i" => -1, "j" => 1 ) );  // index on "i" descending, "j" ascending

?>
]]>
    </programlisting>
   </example>
   <para>
    Indexing is critical for good read performance as your data grows.  If you
    are not familiar with indexing, check out the
    <function>MongoCollection::ensureIndex</function> documentation and the core
    <link xlink:href="&url.mongodb.dochub.indexes;">MongoDB indexing documentation</link>.
   </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
-->