Merge pull request #17 from jmikola/0.2-docs

Update docs and code examples for 0.2

Author: jmikola

Makefile

@@ -1,6 +1,5 @@
 .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,33 +42,30 @@ 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
 
 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

@@ -1,20 +1,33 @@
 # 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

@@ -0,0 +1,11 @@
+<?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 renamed to examples/bulkwrite.php

@@ -1,20 +1,29 @@
 <?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 @@ function dumpCollection($collection) {
 ]);
 
 dumpWriteResults($result);
+echo "\n";
 dumpCollection($collection);
-
+echo "\n";
 
 $result = $collection->bulkWrite([
     [
@@ -84,9 +91,10 @@ function dumpCollection($collection) {
     ],
 ]);
 
-echo "\n\n";
 dumpWriteResults($result);
+echo "\n";
 dumpCollection($collection);
+echo "\n";
 
 $result = $collection->bulkWrite([
     [
@@ -96,7 +104,6 @@ function dumpCollection($collection) {
     ],
 ]);
 
-echo "\n\n";
 dumpWriteResults($result);
+echo "\n";
 dumpCollection($collection);
-