From 8d08c4a28452c53b7b4dbfe28a414d167b9c6276 Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Tue, 12 May 2015 16:05:21 -0400 Subject: [PATCH 1/5] Update code examples for 0.2 --- examples/bootstrap.php | 11 ++ ...Collection-bulkWrite.php => bulkwrite.php} | 37 +++-- examples/import-json.php | 19 --- examples/write.php | 138 ++++++++++-------- 4 files changed, 112 insertions(+), 93 deletions(-) create mode 100644 examples/bootstrap.php rename examples/{Collection-bulkWrite.php => bulkwrite.php} (71%) delete mode 100644 examples/import-json.php diff --git a/examples/bootstrap.php b/examples/bootstrap.php new file mode 100644 index 000000000..fd711e007 --- /dev/null +++ b/examples/bootstrap.php @@ -0,0 +1,11 @@ +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); - diff --git a/examples/import-json.php b/examples/import-json.php deleted file mode 100644 index 7e175cb48..000000000 --- a/examples/import-json.php +++ /dev/null @@ -1,19 +0,0 @@ -insert($document); -} - -$manager = new MongoDB\Manager("mongodb://localhost"); - -$result = $manager->executeWriteBatch("examples.zips", $batch); -printf("Inserted %d documents\n", $result->getInsertedCount()); - -?> diff --git a/examples/write.php b/examples/write.php index 15b67fd42..47ea91999 100644 --- a/examples/write.php +++ b/examples/write.php @@ -1,87 +1,96 @@ "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 { $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 { - 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 { $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 @@ $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 @@ 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; } From 13eafc62b5df0edaf83d268920b38c155627bb59 Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Tue, 12 May 2015 16:24:59 -0400 Subject: [PATCH 2/5] Update docs for 0.2 --- docs/index.md | 2 +- docs/usage.md | 36 ++++++++++++++++++++++++++++++------ 2 files changed, 31 insertions(+), 7 deletions(-) diff --git a/docs/index.md b/docs/index.md index 21fd8ed52..792280932 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/usage.md b/docs/usage.md index b8877cd25..744046eb2 100644 --- a/docs/usage.md +++ b/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 ``` Date: Tue, 12 May 2015 17:25:00 -0400 Subject: [PATCH 3/5] Fix Makefile indentation --- Makefile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index 664a85789..955d0db3d 100644 --- a/Makefile +++ b/Makefile @@ -43,12 +43,12 @@ 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 From 6bb143c293a754e2c9dfb6eca8f1afd7f158166a Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Tue, 12 May 2015 17:25:28 -0400 Subject: [PATCH 4/5] Use dynamic release/VERSION make target --- Makefile | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/Makefile b/Makefile index 955d0db3d..ca004ea8d 100644 --- a/Makefile +++ b/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 @@ -54,15 +53,13 @@ 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 --since="$$(git show -s --format=%ad `git rev-list --tags --max-count=1`)" > RELEASE-$(*) From f13161a9a9490454546e25a3a43f8d56082ba2ae Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Tue, 12 May 2015 17:25:58 -0400 Subject: [PATCH 5/5] Exclude merges from generated release log --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index ca004ea8d..6d954e541 100644 --- a/Makefile +++ b/Makefile @@ -68,4 +68,4 @@ release-docs: docs mkdocs gh-deploy --clean release-log/%: - @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-$(*) + @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-$(*)