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

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

<section xml:id="mongo.tutorial" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Tutorial</title>
 <section>
  <title>Introduction</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>
  <programlisting role="php">
<![CDATA[
<?php

// connect
$m = new Mongo();

// 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>
  <para>
   This would output:
  </para>
  <screen>
<![CDATA[
Calvin and Hobbes
XKCD
]]>
  </screen>
 </section>
 <section>
  <title>Making a Connection</title>
  <para>
   To connect to the database server, use one of the following:

   <programlisting role="php">
    <![CDATA[
<?php

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

?>
]]>
   </programlisting>

   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>
   <title>See Also</title>
   <para>
    The manual chapter on <link linkend="mongo.connecting">connecting</link> 
    covers different types of connections.  
   </para>
   <para>
    The API documentation on the <classname>Mongo</classname> class and 
    <function>Mongo::__construct</function> give a comprehensive look at all 
    possible options with a number of examples.
   </para>
  </section>

  <section>
   <title>Getting a Database</title>
   <para>
    To select a database, use:

    <programlisting role="php">
     <![CDATA[
<?php

$db = $connection->dbname;

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

    <programlisting role="php">
     <![CDATA[
<?php

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

?>
]]>
    </programlisting>
   </para>
   <section>
    <title>See Also</title>
    <para>
     The API documentation on the <classname>MongoDB</classname> class contains 
     more information about database objects.
    </para>
   </section>
  </section>

  <section>
   <title>Getting A Collection</title>
   <para>
    Getting a collection has the same syntax as getting a database:

    <programlisting role="php">
     <![CDATA[
<?php

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

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

?>
]]>
    </programlisting>
   </para>
   <section>
    <title>See Also</title>
    <para>
     The API documentation on the <classname>MongoCollection</classname> class 
     contains more information about collection objects.
    </para>
   </section>
  </section>

  <section>
   <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:

    <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>

    Note that you can have nested arrays and objects.
   </para>
   <para>
    To insert this document, use <function>MongoCollection::insert</function>:

    <programlisting role="php">
     <![CDATA[
<?php

$collection->insert( $doc );

?>
]]>
    </programlisting>
   </para>
   <section>
    <title>See Also</title>
    <para>
     The API documentation on <function>MongoCollection::insert</function> 
     contains more information about inserting data.
    </para>
   </section>
  </section>

  <section>
   <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.

    <programlisting role="php">
     <![CDATA[
<?php

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

?>
]]>
    </programlisting>

    This should print:

    <programlisting>
     <![CDATA[
array(5) {
  ["_id"]=>
  object(MongoId)#6 (0) {
  }
  ["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"
  }
}
]]>
    </programlisting>
   </para>
   <para>
    Note the <literal>_id</literal> field has been added automatically to your 
    document. <literal>_id</literal> is the "primary key" field that is 
    automatically populate for almost all documents in MongoDB.
   </para>
   <section>
    <title>See Also</title>
    <para>
     The API documentation on <function>MongoCollection::findOne</function> 
     contains more information about finding data.
    </para>
   </section>
  </section>

  <section>
   <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

    <programlisting role="php">
     <![CDATA[
<?php

array( "i" => value );

?>
]]>
    </programlisting>

    and we can do this fairly efficiently in a loop

    <programlisting role="php">
     <![CDATA[
<?php

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

?>
]]>
    </programlisting>
   </para>

   <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>
   <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.
    <programlisting role="php">
     <![CDATA[
<?php

echo $collection->count();

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

  <section>
   <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:

    <programlisting role="php">
     <![CDATA[
<?php

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

?>
]]>
    </programlisting>

    and that should print all 101 documents in the collection.  
    <literal>$id</literal> is the <literal>_id</literal> field of a document, 
    and <literal>$value</literal> is the document itself.
   </para>
   <section>
    <title>See Also</title>
    <para>
     The API documentation on <function>MongoCollection::find</function> 
     contains more information about finding data.
    </para>
   </section>
  </section>

  <section>
   <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:

    <programlisting role="php">
     <![CDATA[
<?php

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

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

?>
]]>
    </programlisting>

    and it should just print just one document

    <programlisting>
     <![CDATA[
array(2) {
  ["_id"]=>
  object(MongoId)#6 (0) {
  }
  ["i"]=>
  int(71)
  ["_ns"]=>
  "testCollection"
}
]]>
    </programlisting>
   </para>
  </section>

  <section>
   <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:

    <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>

    which should print the documents where i &gt; 50. We could also get a range, say 
    20 &lt; i &lt;= 30:

    <programlisting role="php">
     <![CDATA[
<?php

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

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

?>
]]>
    </programlisting>

    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. ":", and add the following line to php.ini:

    <programlisting>
     <![CDATA[
mongo.cmd = ":"
]]>
    </programlisting>

    Then the example above would look like:

    <programlisting role="php">
     <![CDATA[
<?php

$query = array( "i" => array( ":gt" => 20, ":lte" => 30 ) );

?>
]]>
    </programlisting>

    You can also change it in your code using ini_set("mongo.cmd", ":").  Of 
    course, you can also just use single quotes around the $.
   </para>
  </section>

  <section>
   <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:

    <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>
   </para>
  </section>
 </section>
</section>