Moved tools to Advanced topic, included simple setting up tools in Installation. Reworked CLI tool to print a template when no cli-config.php is defined.

bin/doctrine.php

@@ -13,32 +13,47 @@
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  *
  * This software consists of voluntary contributions made by many individuals
- * and is licensed under the LGPL. For more information, see
+ * and is licensed under the MIT license. For more information, see
  * <http://www.doctrine-project.org>.
  */
 
+use Symfony\Component\Console\Helper\HelperSet;
+use Doctrine\ORM\Tools\Console\ConsoleRunner;
+
 (@include_once __DIR__ . '/../vendor/autoload.php') || @include_once __DIR__ . '/../../../autoload.php';
-$configFile = getcwd() . DIRECTORY_SEPARATOR . 'cli-config.php';
 
-$helperSet = null;
-$commands = array();
-if (file_exists($configFile)) {
-    if ( ! is_readable($configFile)) {
-        trigger_error(
-            'Configuration file [' . $configFile . '] does not have read permission.', E_ERROR
-        );
+$directories = array(getcwd(), getcwd() . DIRECTORY_SEPARATOR . 'config');
+
+$configFile = null;
+foreach ($directories as $directory) {
+    $configFile = $directory . DIRECTORY_SEPARATOR . 'cli-config.php';
+
+    if (file_exists($configFile)) {
+        break;
     }
+}
 
-    require $configFile;
+if ( ! file_exists($configFile)) {
+    ConsoleRunner::printCliConfigTemplate();
+    exit(1);
+}
 
+if ( ! is_readable($configFile)) {
+    echo 'Configuration file [' . $configFile . '] does not have read permission.' . "\n";
+    exit(1);
+}
+
+$commands = array();
+
+$helperSet = require $configFile;
+
+if ( ! ($helperSet instanceof HelperSet)) {
     foreach ($GLOBALS as $helperSetCandidate) {
-        if ($helperSetCandidate instanceof \Symfony\Component\Console\Helper\HelperSet) {
+        if ($helperSetCandidate instanceof HelperSet) {
             $helperSet = $helperSetCandidate;
             break;
         }
     }
 }
 
-$helperSet = ($helperSet) ?: new \Symfony\Component\Console\Helper\HelperSet();
-
 \Doctrine\ORM\Tools\Console\ConsoleRunner::run($helperSet, $commands);

docs/en/index.rst

@@ -27,7 +27,6 @@ Getting Started
 
 * **Setup**:
   :doc:`Installation & Configuration <reference/configuration>` |
-  :doc:`Commandline Tools <reference/tools>`
 
 * **Tutorial**:
   :doc:`Code First <tutorials/getting-started>` |
@@ -71,6 +70,7 @@ Advanced Topics
   * :doc:`Architecture <reference/architecture>`
   * :doc:`Advanced Configuration <reference/advanced-configuration>`
   * :doc:`Limitations and knowns issues <reference/limitations-and-known-issues>`
+  * :doc:`Commandline Tools <reference/tools>`
   * :doc:`Transactions and Concurrency <reference/transactions-and-concurrency>`
   * :doc:`Filters <reference/filters>`
   * :doc:`NamingStrategy <reference/namingstrategy>`

docs/en/reference/configuration.rst

@@ -92,3 +92,31 @@ Configuration <reference/advanced-configuration>` section.
     You can learn more about the database connection configuration in the
     `Doctrine DBAL connection configuration reference <http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html>`_.
 
+Setting up the Commandline Tool
+-------------------------------
+
+Doctrine ships with a number of command line tools that are very helpful
+during development. You can call this command from the Composer binary
+directory:
+
+.. code-block::
+
+    $ php vendor/bin/doctrine
+
+You need to register your applications EntityManager to the console tool
+to make use of the tasks by creating a ``cli-config.php`` file with the
+following content:
+
+.. code-block:: php
+
+    <?php
+    // cli-config.php
+    require_once 'my_bootstrap.php';
+
+    // Any way to access the EntityManager from  your application
+    $em = GetMyEntityManager();
+    
+    $helperSet = new \Symfony\Component\Console\Helper\HelperSet(array(
+        'db' => new \Doctrine\DBAL\Tools\Console\Helper\ConnectionHelper($em->getConnection()),
+        'em' => new \Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper($em)
+    ));

docs/en/reference/tools.rst

@@ -4,30 +4,29 @@ Tools
 Doctrine Console
 ----------------
 
-The Doctrine Console is a Command Line Interface tool for
-simplifying common tasks during the development of a project that
-uses Doctrine 2.
+The Doctrine Console is a Command Line Interface tool for simplifying common
+administration tasks during the development of a project that uses Doctrine 2.
 
-Take a look at the :doc:`Configuration <configuration>` for more
-information how to setup the console command.
+Take a look at the :doc:`Installation and Configuration <configuration>`
+chapter for more information how to setup the console command.
 
-Getting Help
-~~~~~~~~~~~~
+Display Help Information
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-Type ``php vendor/bin/doctrine-orm`` on the command line and you should see an
+Type ``php vendor/bin/doctrine`` on the command line and you should see an
 overview of the available commands or use the --help flag to get
 information on the available commands. If you want to know more
 about the use of generate entities for example, you can call:
 
 .. code-block:: php
 
-    $> php vendor/bin/doctrine-orm orm:generate-entities --help
+    $> php vendor/bin/doctrine orm:generate-entities --help
 
 
 Configuration
 ~~~~~~~~~~~~~
 
-Whenever the ``doctrine-orm`` command line tool is invoked, it can
+Whenever the ``doctrine`` command line tool is invoked, it can
 access all Commands that were registered by developer. There is no
 auto-detection mechanism at work. The Doctrine binary
 already registers all the commands that currently ship with

lib/Doctrine/ORM/Tools/Console/ConsoleRunner.php

@@ -23,8 +23,27 @@ use Symfony\Component\Console\Application;
 use Symfony\Component\Console\Helper\HelperSet;
 use Doctrine\ORM\Version;
 
+use Doctrine\DBAL\Tools\Console\Helper\ConnectionHelper;
+use Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper;
+
+/**
+ * Handles running the Console Tools inside Symfony Console context.
+ */
 class ConsoleRunner
 {
+    /**
+     * Create a Symfony Console HelperSet
+     *
+     * @return HelperSet
+     */
+    public static function createHelperSet(EntityManager $entityManager)
+    {
+        return new HelperSet(array(
+            'db' => new ConnectionHelper($entityManager->getConnection()),
+            'em' => new EntityManagerHelper($entityManager)
+        ));
+    }
+
     /**
      * Runs console with the given helperset.
      *
@@ -73,4 +92,26 @@ class ConsoleRunner
             new \Doctrine\ORM\Tools\Console\Command\InfoCommand()
         ));
     }
+
+    static public function printCliConfigTemplate()
+    {
+        echo <<<'HELP'
+You are missing a "cli-config.php" or "config/cli-config.php" file in your
+project, which is required to get the Doctrine Console working. You can use the
+following sample as a template:
+
+<?php
+use Doctrine\ORM\Tools\Console\ConsoleRunner;
+
+// replace with file to your own project bootstrap
+require_once 'bootstrap.php';
+
+// replace with mechanism to retrieve EntityManager in your app
+$entityManager = GetEntityManager();
+
+return ConsoleRunner::createHelperSet($entityManager);
+
+HELP;
+
+    }
 }