Merge pull request #17 from jmikola/0.2-docs

Update docs and code examples for 0.2

Makefile

 .PHONY: apigen composer test docs mkdocs
 
-MONGODB_LIB_VERSION=`php -r 'require "src/Collection.php"; echo MongoDB\Collection::VERSION, "\n";'`
 COMPOSER_ARGS=update --no-interaction --prefer-source
 PHPUNIT_ARGS=--process-isolation
 
@@ -43,26 +42,24 @@ apigen:
 mkdocs:
 	@command -v mkdocs >/dev/null 2>&1; \
 	if test $$? -eq 0; then \
-        mkdocs build --clean \
-    else \
+		mkdocs build --clean \
+	else \
 		echo "Cannot find mkdocs :("; \
 		echo "Aborting."; \
 		exit 1; \
-    fi
+	fi
 
 docs-api: apigen
 
 docs: mkdocs
 
-
-release: test RELEASE
+release/%: release-log/%
 	@echo "Please run:"
-	@echo "		" git add RELEASE-$(MONGODB_LIB_VERSION)
-	@echo "		" git commit -m \"Add $(MONGODB_LIB_VERSION) release notes\"
-	@echo "		" git tag -a -m \"Release MongoDB library $(MONGODB_LIB_VERSION)\" $(MONGODB_LIB_VERSION)
-	@echo "		" git push --tags
-	@echo "		" make release-docs
-	@echo "And don't forget to bump version in src/Collection.php"
+	@echo "    " git add RELEASE-$(*)
+	@echo "    " git commit -m \"Add $(*) release notes\"
+	@echo "    " git tag -a -m \"Release MongoDB library $(*)\" $(*)
+	@echo "    " git push --tags
+	@echo "    " make release-docs
 
 docs:
 	mkdocs build --clean
@@ -70,6 +67,5 @@ docs:
 release-docs: docs
 	mkdocs gh-deploy --clean
 
-RELEASE:
-	@git log --pretty=format:"%ad  %an  <%ae>%n%x09* %s%n" --date short --since="$$(git show -s --format=%ad `git rev-list --tags --max-count=1`)" > RELEASE-$(MONGODB_LIB_VERSION)
-
+release-log/%:
+	@git log --pretty=format:"%ad  %an  <%ae>%n%x09* %s%n" --date short --no-merges --since="$$(git show -s --format=%ad `git rev-list --tags --max-count=1`)" > RELEASE-$(*)

docs/index.md

@@ -30,7 +30,7 @@ The preferred method of installing this library is with
 [Composer](https://getcomposer.org/) by running the following from your project
 root:
 
-    $ composer require "mongodb/mongodb=0.2.x-dev"
+    $ composer require "mongodb/mongodb=^0.2.0"
 
 ## Generated API Docs
 

docs/usage.md

 # Usage
 
+## Client class
+
+`MongoDB\Client` serves as an entry point for the library and driver. It is
+constructed with the same arguments as the driver's `MongoDB\Driver\Manager`
+class, which it composes. The Client class provides methods for creating a
+Database or Collection class (from the internal manager instance), as well as
+top-level operations, such as enumerating and dropping databases.
+
 ## Collection class
 
 `MongoDB\Collection` is perhaps the most useful class in this library. It
 provides methods for common operations on a collection, such as inserting
 documents, querying, updating, counting, etc.
 
-Constructing a `MongoDB\Collection` requires a `MongoDB\Manager` and a namespace
-for the collection. A [MongoDB namespace](http://docs.mongodb.org/manual/faq/developers/#faq-dev-namespace)
+Constructing a `MongoDB\Collection` requires a `MongoDB\Driver\Manager` and a
+namespace for the collection. A [MongoDB namespace](http://docs.mongodb.org/manual/faq/developers/#faq-dev-namespace)
 consists of a database name and collection name joined by a dot. `examples.zips`
-is on example of a namespace. A [write concern](http://docs.mongodb.org/manual/core/write-concern/)
+is one example of a namespace. Through normal use of the library, a Collection
+will typically be created via the `selectCollection()` method on the Manager or
+Database classes.
+
+A [write concern](http://docs.mongodb.org/manual/core/write-concern/)
 and [read preference](http://docs.mongodb.org/manual/core/read-preference/) may
-also be provided when constructing a Collection (if omitted, the Collection will
-use the Manager's values as its defaults).
+also be provided when constructing a Collection. If these options are omitted,
+the Collection will inherit them from the parent through which it was selected,
+or the Manager.
 
-## Finding a specific document
+### Finding a specific document
 
 ```
 <?php
@@ -51,3 +64,14 @@ array(5) {
   string(2) "CA"
 }
 ```
+
+## Database class
+
+`MongoDB\Database` provides methods for common operations on a database, such
+as creating, enumerating, and dropping collections.
+
+A [write concern](http://docs.mongodb.org/manual/core/write-concern/)
+and [read preference](http://docs.mongodb.org/manual/core/read-preference/) may
+also be provided when constructing a Database. If these options are omitted,
+the Database will inherit them from the Client through which it was selected,
+or the Manager.

examples/bootstrap.php

+<?php
+
+if (file_exists(__DIR__ . '/../vendor/autoload.php')) {
+    // Dependencies were installed with Composer and this is the main project
+    $loader = require_once __DIR__ . '/../vendor/autoload.php';
+} elseif (file_exists(__DIR__ . '/../../../../autoload.php')) {
+    // We're installed as a dependency in another project's `vendor` directory
+    $loader = require_once __DIR__ . '/../../../../autoload.php';
+} else {
+    throw new Exception('Can\'t find autoload.php. Did you install dependencies with Composer?');
+}

examples/Collection-bulkWrite.php → examples/bulkwrite.php

 <?php
-require __DIR__ . "/" . "../vendor/autoload.php";
 
-function dumpWriteResults(MongoDB\WriteResult $result) {
-    printf("Inserted %d documents, upserted %d, updated %d and deleted %d\n",
-        $result->getInsertedCount(), $result->getUpsertedCount(),
-        $result->getModifiedCount(), $result->getDeletedCount()
+require_once __DIR__ . "/bootstrap.php";
+
+$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
+$collection = new MongoDB\Collection($manager, "phplib_demo.bulkwrite");
+
+function dumpWriteResults(MongoDB\BulkWriteResult $result)
+{
+    printf("Inserted %d documents, upserted %d, updated %d, and deleted %d\n",
+        $result->getInsertedCount(),
+        $result->getUpsertedCount(),
+        $result->getModifiedCount(),
+        $result->getDeletedCount()
     );
 
     if ($result->getUpsertedCount()) {
         foreach ($result->getUpsertedIds() as $index => $id) {
-            printf("upsertedId[%d]: %s", $index, $id);
+            printf("upsertedId[%d]: %s\n", $index, $id);
         }
     }
 }
-function dumpCollection($collection) {
-    printf("\n---\nDumping all documents in: %s.%s\n",
+
+function dumpCollection($collection)
+{
+    printf("Dumping all documents in: %s.%s\n",
         $collection->getDatabaseName(),
         $collection->getCollectionName()
     );
@@ -26,9 +35,6 @@ function dumpCollection($collection) {
     printf("Found %d documents\n", $n);
 }
 
-
-$manager = new MongoDB\Manager("mongodb://localhost:27017");
-$collection = new MongoDB\Collection($manager, "crud.bulkWrite");
 $result = $collection->bulkWrite([
     [
         "insertOne" => [
@@ -61,8 +67,9 @@ $result = $collection->bulkWrite([
 ]);
 
 dumpWriteResults($result);
+echo "\n";
 dumpCollection($collection);
-
+echo "\n";
 
 $result = $collection->bulkWrite([
     [
@@ -84,9 +91,10 @@ $result = $collection->bulkWrite([
     ],
 ]);
 
-echo "\n\n";
 dumpWriteResults($result);
+echo "\n";
 dumpCollection($collection);
+echo "\n";
 
 $result = $collection->bulkWrite([
     [
@@ -96,7 +104,6 @@ $result = $collection->bulkWrite([
     ],
 ]);
 
-echo "\n\n";
 dumpWriteResults($result);
+echo "\n";
 dumpCollection($collection);
-

examples/import-json.php

-<?php
-
-$file = "http://media.mongodb.org/zips.json";
-
-$zips = file($file, FILE_IGNORE_NEW_LINES);
-
-
-$batch = new MongoDB\WriteBatch(true);
-foreach($zips as $string) {
-    $document = json_decode($string);
-    $batch->insert($document);
-}
-
-$manager = new MongoDB\Manager("mongodb://localhost");
-
-$result = $manager->executeWriteBatch("examples.zips", $batch);
-printf("Inserted %d documents\n", $result->getInsertedCount());
-
-?>

examples/write.php

 <?php
 
-require __DIR__ . "/../src/QueryFlags.php";
-require __DIR__ . "/../src/CursorType.php";
-require __DIR__ . "/../src/InsertResult.php";
-require __DIR__ . "/../src/DeleteResult.php";
-require __DIR__ . "/../src/UpdateResult.php";
-require __DIR__ . "/../src/Collection.php";
-
-
-$manager = new MongoDB\Manager("mongodb://localhost:27017");
-
-
-$collection = new MongoDB\Collection($manager, "crud.examples");
-$hannes = array(
-	"name"    => "Hannes", 
-	"nick"    => "bjori",
-	"citizen" => "Iceland",
-);
-$hayley = array(
-	"name"    => "Hayley",
-	"nick"    => "Ninja",
-	"citizen" => "USA",
-);
-$bobby = array(
+require_once __DIR__ . "/bootstrap.php";
+
+$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");
+$collection = new MongoDB\Collection($manager, "phplib_demo.write");
+
+$hannes = [
+    "name"    => "Hannes", 
+    "nick"    => "bjori",
+    "citizen" => "Iceland",
+];
+$hayley = [
+    "name"    => "Hayley",
+    "nick"    => "Ninja",
+    "citizen" => "USA",
+];
+$bobby = [
     "name" => "Robert Fischer",
     "nick" => "Bobby Fischer",
     "citizen" => "USA",
-);
-$kasparov = array(
+];
+$kasparov = [
     "name"    => "Garry Kimovich Kasparov",
     "nick"    => "Kasparov",
     "citizen" => "Russia",
-);
-$spassky = array(
+];
+$spassky = [
     "name"    => "Boris Vasilievich Spassky",
     "nick"    => "Spassky",
     "citizen" => "France",
-);
+];
+
 
 try {
     $result = $collection->insertOne($hannes);
-    printf("Inserted _id: %s\n", $result->getInsertedId());
+    printf("Inserted _id: %s\n\n", $result->getInsertedId());
+
     $result = $collection->insertOne($hayley);
-    printf("Inserted _id: %s\n", $result->getInsertedId());
+    printf("Inserted _id: %s\n\n", $result->getInsertedId());
+
     $result = $collection->insertOne($bobby);
-    printf("Inserted _id: %s\n", $result->getInsertedId());
+    printf("Inserted _id: %s\n\n", $result->getInsertedId());
 
-    $count = $collection->count(array("nick" => "bjori"));
-    printf("Searching for nick => bjori, should have only one result: %d\n", $count);
+    $count = $collection->count(["nick" => "bjori"]);
+    printf("Searching for nick => bjori, should have only one result: %d\n\n", $count);
 
     $result = $collection->updateOne(
-        array("citizen" => "USA"),
-        array('$set' => array("citizen" => "Iceland"))
+        ["citizen" => "USA"],
+        ['$set' => ["citizen" => "Iceland"]]
     );
-    printf("Updated: %s (out of expected 1)\n", $result->getModifiedCount());
+    printf("Updated: %s (out of expected 1)\n\n", $result->getModifiedCount());
 
-    $result = $collection->find(array("citizen" => "Iceland"), array("comment" => "Excellent query"));
+    $cursor = $collection->find(
+        ["citizen" => "Iceland"],
+        ["comment" => "Excellent query"]
+    );
     echo "Searching for citizen => Iceland, verify Hayley is now Icelandic\n";
-    foreach($result as $document) {
+    foreach($cursor as $document) {
         var_dump($document);
     }
+    echo "\n";
 } catch(Exception $e) {
     printf("Caught exception '%s', on line %d\n", $e->getMessage(), __LINE__);
     exit;
 }
 
+
 try {
-    $result = $collection->find();
+    $cursor = $collection->find();
     echo "Find all docs, should be 3, verify 1x USA citizen, 2x Icelandic\n";
-    foreach($result as $document) {
+    foreach($cursor as $document) {
         var_dump($document);
     }
+    echo "\n";
+
     $result = $collection->distinct("citizen");
     echo "Distinct countries:\n";
     var_dump($result);
+    echo "\n";
 
     echo "aggregate\n";
-    $aggregate = $collection->aggregate(array(array('$project' => array("name" => 1, "_id" => 0))), array("useCursor" => true, "batchSize" => 2));
+    $result = $collection->aggregate(
+        [
+            ['$project' => ["name" => 1, "_id" => 0]],
+        ],
+        [ "useCursor" => true, "batchSize" => 2 ]
+    );
     printf("Should be 3 different people\n");
-    foreach($aggregate as $person) {
+    foreach($result as $person) {
         var_dump($person);
     }
-
+    echo "\n";
 } catch(Exception $e) {
     printf("Caught exception '%s', on line %d\n", $e->getMessage(), __LINE__);
     exit;
@@ -90,15 +99,15 @@ try {
 
 try {
     $result = $collection->updateMany(
-        array("citizen" => "Iceland"),
-        array('$set' => array("viking" => true))
+        ["citizen" => "Iceland"],
+        ['$set' => ["viking" => true]]
     );
-
     printf("Updated: %d (out of expected 2), verify Icelandic people are vikings\n", $result->getModifiedCount());
     $result = $collection->find();
     foreach($result as $document) {
         var_dump($document);
     }
+    echo "\n";
 } catch(Exception $e) {
     printf("Caught exception '%s', on line %d\n", $e->getMessage(), __LINE__);
     exit;
@@ -106,16 +115,16 @@ try {
 
 
 try {
-    echo "This is the trouble maker\n";
     $result = $collection->replaceOne(
-        array("nick" => "Bobby Fischer"),
-        array("name" => "Magnus Carlsen", "nick" => "unknown", "citizen" => "Norway")
+        ["nick" => "Bobby Fischer"],
+        ["name" => "Magnus Carlsen", "nick" => "unknown", "citizen" => "Norway"]
     );
     printf("Replaced: %d (out of expected 1), verify Bobby has been replaced with Magnus\n", $result->getModifiedCount());
     $result = $collection->find();
     foreach($result as $document) {
         var_dump($document);
     }
+    echo "\n";
 } catch(Exception $e) {
     printf("Caught exception '%s', on line %d\n", $e->getMessage(), __LINE__);
     exit;
@@ -124,34 +133,46 @@ try {
 
 try {
     $result = $collection->deleteOne($document);
-    printf("Deleted: %d (out of expected 1)\n", $result->getDeletedCount());
+    printf("Deleted: %d (out of expected 1)\n\n", $result->getDeletedCount());
 
-    $result = $collection->deleteMany(array("citizen" => "Iceland"));
-    printf("Deleted: %d (out of expected 2)\n", $result->getDeletedCount());
+    $result = $collection->deleteMany(["citizen" => "Iceland"]);
+    printf("Deleted: %d (out of expected 2)\n\n", $result->getDeletedCount());
 } catch(Exception $e) {
     printf("Caught exception '%s', on line %d\n", $e->getMessage(), __LINE__);
     exit;
 }
 
+
 try {
     echo "FindOneAndReplace\n";
-    $result = $collection->findOneAndReplace($spassky, $kasparov, array("upsert" => true));
+    $result = $collection->findOneAndReplace(
+        $spassky,
+        $kasparov,
+        ["upsert" => true]
+    );
     echo "Kasparov\n";
     var_dump($result);
+    echo "\n";
 
     echo "Returning the old document where he was Russian\n";
-    $result = $collection->findOneAndUpdate($kasparov, array('$set' => array("citizen" => "Croatia")));
+    $result = $collection->findOneAndUpdate(
+        $kasparov,
+        ['$set' => ["citizen" => "Croatia"]]
+    );
     var_dump($result);
+    echo "\n";
 
     echo "Deleting him, he isn't Croatian just yet\n";
-    $result = $collection->findOneAndDelete(array("citizen" => "Croatia"));
+    $result = $collection->findOneAndDelete(["citizen" => "Croatia"]);
     var_dump($result);
+    echo "\n";
 
     echo "This should be empty\n";
-    $result = $collection->find(array());
+    $result = $collection->find();
     foreach($result as $document) {
         var_dump($document);
     }
+    echo "\n";
 } catch(Exception $e) {
     printf("Caught exception '%s', on line %d\n", $e->getMessage(), __LINE__);
     exit;
@@ -162,7 +183,7 @@ try {
     $result = $collection->bulkWrite(
         // Required writes param (an array of operations)
         [
-            // Like explain(), operations identified by single key
+            // Operations identified by single key
             [
                 'insertOne' => [
                     ['x' => 1]
@@ -204,11 +225,10 @@ try {
     printf("deletedCount: %d\n", $result->getDeletedCount());
 
     foreach ($result->getUpsertedIds() as $index => $id) {
-        printf("upsertedId[%d]: %s", $index, $id);
+        printf("upsertedId[%d]: %s\n", $index, $id);
     }
 
 } catch(Exception $e) {
     printf("Caught exception '%s', on line %d\n", $e->getMessage(), __LINE__);
-    echo $e->getTraceAsString(), "\n";
     exit;
 }