Skip to content

M
mongo-php-library
Commit a887e0e3 authored by Jeremy Mikola's avatar Jeremy Mikola
Browse files
Options

Merge pull request #17 from jmikola/0.2-docs 

Update docs and code examples for 0.2
parents 34bdc8a7 f13161a9
Hide whitespace changes
Inline Side-by-side
Showing with 154 additions and 115 deletions
Makefile
View file @ a887e0e3
.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
View file @ a887e0e3
......@@ -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
View file @ a887e0e3
# 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 → 100644
View file @ a887e0e3
<?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
View file @ a887e0e3
<?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 deleted 100644 → 0
View file @ 34bdc8a7
<?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
View file @ a887e0e3
<?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;
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment