Revise console application and documentation

Replace trivial odm:query example with an explanation of where to find the reference implementation and how to proceed with configuration.

Author: jmikola

docs/en/reference/console-commands.rst

@@ -1,7 +1,8 @@
 Console Commands
 ================
 
-Doctrine MongoDB ODM offers some console commands to ease your development process:
+Doctrine MongoDB ODM offers some console commands, which utilize Symfony2's
+Console component, to ease your development process:
 
 - ``odm:clear-cache:metadata`` - Clear all metadata cache of the various cache drivers.
 - ``odm:query`` - Query mongodb and inspect the outputted results from your document classes.
@@ -11,45 +12,41 @@ Doctrine MongoDB ODM offers some console commands to ease your development proce
 - ``odm:generate:repositories`` -  Generate repository classes from your mapping information.
 - ``odm:schema:create`` - Allows you to create databases, collections and indexes for your documents
 - ``odm:schema:drop`` - Allows you to drop databases, collections and indexes for your documents
+- ``odm:schema:update`` - Allows you to update indexes for your documents
 
-You can setup a console command easily with the following code. You just need an existing
-``DocumentManager`` instance:
+Provided you have an existing ``DocumentManager`` instance, you can setup a
+console command easily with the following code:
 
 .. code-block:: php
 
     <?php
 
     // mongodb.php
 
-    // ...
+    // ... include Composer autoloader and configure DocumentManager instance
 
-    $helpers = array(
-        'dm' => new Doctrine\ODM\MongoDB\Tools\Console\Helper\DocumentManagerHelper($dm),
-    );
-
-    $helperSet = isset($helperSet) ? $helperSet : new \Symfony\Component\Console\Helper\HelperSet();
-    foreach ($helpers as $name => $helper) {
-        $helperSet->set($helper, $name);
-    }
+    $helperSet = \Symfony\Component\Console\Helper\HelperSet(array(
+        'dm' => new \Doctrine\ODM\MongoDB\Tools\Console\Helper\DocumentManagerHelper($dm),
+    ));
 
-    $cli = new \Symfony\Component\Console\Application('Doctrine ODM MongoDB Command Line Interface');
-    $cli->setCatchExceptions(true);
-    $cli->setHelperSet($helperSet);
-    $cli->addCommands(array(
-        new \Doctrine\ODM\MongoDB\Tools\Console\Command\QueryCommand(),
+    $app = new Application('Doctrine MongoDB ODM');
+    $app->setHelperSet($helperSet);
+    $app->addCommands(array(
         new \Doctrine\ODM\MongoDB\Tools\Console\Command\GenerateDocumentsCommand(),
-        new \Doctrine\ODM\MongoDB\Tools\Console\Command\GenerateRepositoriesCommand(),
-        new \Doctrine\ODM\MongoDB\Tools\Console\Command\GenerateProxiesCommand(),
         new \Doctrine\ODM\MongoDB\Tools\Console\Command\GenerateHydratorsCommand(),
+        new \Doctrine\ODM\MongoDB\Tools\Console\Command\GenerateProxiesCommand(),
+        new \Doctrine\ODM\MongoDB\Tools\Console\Command\GenerateRepositoriesCommand(),
+        new \Doctrine\ODM\MongoDB\Tools\Console\Command\QueryCommand(),
         new \Doctrine\ODM\MongoDB\Tools\Console\Command\ClearCache\MetadataCommand(),
         new \Doctrine\ODM\MongoDB\Tools\Console\Command\Schema\CreateCommand(),
-        new \Doctrine\ODM\MongoDB\Tools\Console\Command\Schema\UpdateCommand(),
         new \Doctrine\ODM\MongoDB\Tools\Console\Command\Schema\DropCommand(),
+        new \Doctrine\ODM\MongoDB\Tools\Console\Command\Schema\UpdateCommand(),
     ));
-    $cli->run();
-
-Now you can run commands like the following:
 
-    $ php mongodb.php odm:query User "{ username : 'jwage' }"
+    $app->run();
 
-The above would output the results from the query.
+A reference implementation of the console command may be found in the
+``tools/sandbox`` directory of the project repository. That command is
+configured to store generated hydrators and proxies in the same directory, and
+relies on the main project's Composer dependencies. You will want to customize
+its configuration files if you intend to use it in your own project.

tools/sandbox/mongodb.php

@@ -1,21 +1,20 @@
 <?php
 
-use Symfony\Component\Console\Application;
-
 require __DIR__ . '/cli-config.php';
 
-$app = new Application('Doctrine MongoDB ODM');
+$app = new \Symfony\Component\Console\Application('Doctrine MongoDB ODM');
 
 if (isset($helperSet)) {
     $app->setHelperSet($helperSet);
 }
 
 $app->addCommands(array(
-    new \Doctrine\ODM\MongoDB\Tools\Console\Command\QueryCommand(),
     new \Doctrine\ODM\MongoDB\Tools\Console\Command\GenerateDocumentsCommand(),
-    new \Doctrine\ODM\MongoDB\Tools\Console\Command\GenerateRepositoriesCommand(),
-    new \Doctrine\ODM\MongoDB\Tools\Console\Command\GenerateProxiesCommand(),
     new \Doctrine\ODM\MongoDB\Tools\Console\Command\GenerateHydratorsCommand(),
+    new \Doctrine\ODM\MongoDB\Tools\Console\Command\GenerateProxiesCommand(),
+    new \Doctrine\ODM\MongoDB\Tools\Console\Command\GenerateRepositoriesCommand(),
+    new \Doctrine\ODM\MongoDB\Tools\Console\Command\QueryCommand(),
+    new \Doctrine\ODM\MongoDB\Tools\Console\Command\ClearCache\MetadataCommand(),
     new \Doctrine\ODM\MongoDB\Tools\Console\Command\Schema\CreateCommand(),
     new \Doctrine\ODM\MongoDB\Tools\Console\Command\Schema\DropCommand(),
     new \Doctrine\ODM\MongoDB\Tools\Console\Command\Schema\UpdateCommand(),