From 65e2f60b40feaad8cbce1eb2ef3c7df3c54374e1 Mon Sep 17 00:00:00 2001
From: Benjamin Eberlei <kontakt@beberlei.de>
Date: Sat, 16 Jun 2012 11:57:56 +0200
Subject: [PATCH] Rework configuration and tools section to include Composer

---
 en/reference/configuration.rst | 126 ++++++++++++++++++++---------
 en/reference/tools.rst         | 143 ++++++++++++---------------------
 2 files changed, 138 insertions(+), 131 deletions(-)

diff --git a/en/reference/configuration.rst b/en/reference/configuration.rst
index fe0b7bb0c..6d4f291a7 100644
--- a/en/reference/configuration.rst
+++ b/en/reference/configuration.rst
@@ -1,18 +1,40 @@
 Configuration
 =============
 
-Bootstrapping
--------------
-
 Bootstrapping Doctrine is a relatively simple procedure that
-roughly exists of just 2 steps:
-
+roughly exists of four steps:
 
+-  Installation
 -  Making sure Doctrine class files can be loaded on demand.
 -  Obtaining an EntityManager instance.
+-  Optional: Configuration of the Console Tool
+
+Installation
+------------
+
+`Composer <http://www.getcomposer.org>`_ is the suggested installation method for Doctrine.
+Define the following requirement in your ``composer.json`` file:
+
+    {
+        "require": {
+            "doctrine/orm": "*"
+        }
+    }
+
+Then run the composer command. 
 
 Class loading
-~~~~~~~~~~~~~
+-------------
+
+Autoloading is taken care of by Composer. You just have to include the composer autoload file in your project:
+
+.. code-block:: php
+
+    <?php
+    // Include Composer Autoload
+    require_once "vendor/autoload.php";
+
+Skip the rest of this section unless you are using another installation method.
 
 Lets start with the class loading setup. We need to set up some
 class loaders (often called "autoloader") so that Doctrine class
@@ -42,7 +64,6 @@ different types of Doctrine Installations:
     This assumes you've created some kind of script to test
     the following code in. Something like a ``test.php`` file.
 
-
 PEAR
 ^^^^
 
@@ -91,12 +112,45 @@ the autoloading of the Symfony Console and YAML component,
 which are optional dependencies for Doctrine 2.
 
 Obtaining an EntityManager
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 Once you have prepared the class loading, you acquire an
 *EntityManager* instance. The EntityManager class is the primary
 access point to ORM functionality provided by Doctrine.
 
+Quick Configuration Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The above example is a complete setup of the required options for Doctrine.
+You can have this step of your code much simpler and use one of the predefined
+setup methods:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Tools\Setup;
+    use Doctrine\ORM\EntityManager;
+
+    $paths = array("/path/to/entities-or-mapping-files");
+    $isDevMode = false;
+
+    $config = Setup::createAnnotationMetadataConfiguration($paths, $isDevMode);
+    $em = EntityManager::create($dbParams, $config);
+
+    // or if you prefer yaml or xml
+    $config = Setup::createXMLMetadataConfiguration($paths, $isDevMode);
+    $config = Setup::createYAMLMetadataConfiguration($paths, $isDevMode);
+
+These setup commands make several assumptions:
+
+-  If `$devMode` is true always use an ``ArrayCache`` and set ``setAutoGenerateProxyClasses(true)``.
+-  If `$devMode` is false, check for Caches in the order APC, Xcache, Memcache (127.0.0.1:11211), Redis (127.0.0.1:6379) unless `$cache` is passed as fourth argument.
+-  If `$devMode` is false, set ``setAutoGenerateProxyClasses(false)``
+-  If third argument `$proxyDir` is not set, use the systems temporary directory.
+
+Full Configuration Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 The configuration of the EntityManager requires a
 ``Doctrine\ORM\Configuration`` instance as well as some database
 connection parameters. This example shows all the potential
@@ -140,7 +194,7 @@ steps of configuration.
 .. note::
 
     Do not use Doctrine without a metadata and query cache!
-    Doctrine is highly optimized for working with caches. The main
+    Doctrine is optimized for working with caches. The main
     parts in Doctrine that are optimized for caching are the metadata
     mapping information with the metadata cache and the DQL to SQL
     conversions with the query cache. These 2 caches require only an
@@ -151,36 +205,6 @@ steps of configuration.
     fast in-memory cache storage that you can use for the metadata and
     query caches as seen in the previous code snippet.
 
-Configuration Shortcuts
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The above example is a complete setup of the required options for Doctrine.
-You can have this step of your code much simpler and use one of the predefined
-setup methods:
-
-.. code-block:: php
-
-    <?php
-    use Doctrine\ORM\Tools\Setup;
-    use Doctrine\ORM\EntityManager;
-
-    $paths = array("/path/to/entities-or-mapping-files");
-    $isDevMode = false;
-
-    $config = Setup::createAnnotationMetadataConfiguration($paths, $isDevMode);
-    $em = EntityManager::create($dbParams, $config);
-
-    // or if you prefer yaml or xml
-    $config = Setup::createXMLMetadataConfiguration($paths, $isDevMode);
-    $config = Setup::createYAMLMetadataConfiguration($paths, $isDevMode);
-
-These setup commands make several assumptions:
-
--  If `$devMode` is true always use an ``ArrayCache`` and set ``setAutoGenerateProxyClasses(true)``.
--  If `$devMode` is false, check for Caches in the order APC, Xcache, Memcache (127.0.0.1:11211), Redis (127.0.0.1:6379) unless `$cache` is passed as fourth argument.
--  If `$devMode` is false, set ``setAutoGenerateProxyClasses(false)``
--  If third argument `$proxyDir` is not set, use the systems temporary directory.
-
 Configuration Options
 ---------------------
 
@@ -536,3 +560,27 @@ That will be available for all entities without a custom repository class.
 
 The default value is ``Doctrine\ORM\EntityRepository``.
 Any repository class must be a subclass of EntityRepository otherwise you got an ORMException
+
+Setting up the Console
+----------------------
+
+Doctrine uses the Symfony Console component for generating the command
+line interface. You can take a look at the ``bin/doctrine.php``
+script and the ``Doctrine\ORM\Tools\Console\ConsoleRunner`` command
+for inspiration how to setup the cli.
+
+If you installed Doctrine 2 through Composer, then the Doctrine command is
+available to you in the bin-dir, by default at ``vendor/.bin/doctrine``.
+
+If you installed Doctrine 2 through PEAR, the ``doctrine`` command
+line tool should already be available to you.
+
+In general the required code looks like this:
+
+.. code-block:: php
+
+    $cli = new Application('Doctrine Command Line Interface', \Doctrine\ORM\Version::VERSION);
+    $cli->setCatchExceptions(true);
+    $cli->setHelperSet($helperSet);
+    Doctrine\ORM\Tools\Console\ConsoleRunner::addCommands($cli);
+    $cli->run();
diff --git a/en/reference/tools.rst b/en/reference/tools.rst
index 25d591df7..69babfc27 100644
--- a/en/reference/tools.rst
+++ b/en/reference/tools.rst
@@ -8,15 +8,8 @@ The Doctrine Console is a Command Line Interface tool for
 simplifying common tasks during the development of a project that
 uses Doctrine 2.
 
-Installation
-~~~~~~~~~~~~
-
-If you installed Doctrine 2 through PEAR, the ``doctrine`` command
-line tool should already be available to you. Y
-
-In any other case you should create a project specific doctrine command
-on your own. This is a combination of the PEAR ``doctrine`` commands
-code and some of your own bootstrap code.
+Take a look at the `Configuration <reference/configuration>` for more
+information how to setup the console command.
 
 Getting Help
 ~~~~~~~~~~~~
@@ -30,23 +23,6 @@ about the use of generate entities for example, you can call:
 
     doctrine orm:generate-entities --help
 
-Setting up the Console
-----------------------
-
-Doctrine uses the Symfony Console component for generating the command
-line interface. You can take a look at the ``bin/doctrine.php``
-script and the ``Doctrine\ORM\Tools\Console\ConsoleRunner`` command
-for inspiration how to setup the cli.
-
-In general the required code looks like this:
-
-.. code-block:: php
-
-        $cli = new Application('Doctrine Command Line Interface', \Doctrine\ORM\Version::VERSION);
-        $cli->setCatchExceptions(true);
-        $cli->setHelperSet($helperSet);
-        Doctrine\ORM\Tools\Console\ConsoleRunner::addCommands($cli);
-        $cli->run();
 
 Configuration (PEAR)
 ~~~~~~~~~~~~~~~~~~~~
@@ -94,18 +70,10 @@ sample ``cli-config.php`` file looks as follows:
 
     <?php
     // cli-config.php
-    use Doctrine\ORM\Tools\Setup;
-    use Doctrine\ORM\EntityManager;
+    require_once 'my_bootstrap.php';
 
-    require 'Doctrine/ORM/Tools/Setup.php';
-
-    Doctrine\ORM\Tools\Setup::registerAutoloadPEAR();
-
-    $paths = array("/path/to/entities-or-mapping-files");
-    $isDevMode = false;
-
-    $config = Setup::createAnnotationMetadataConfiguration($paths, $isDevMode);
-    $em = EntityManager::create($dbParams, $config);
+    // 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()),
@@ -117,7 +85,6 @@ script will ultimately use. The Doctrine Binary will automatically
 find the first instance of HelperSet in the global variable
 namespace and use this.
 
-
 .. note:: 
 
     You have to adjust this snippet for your specific application or framework
@@ -136,22 +103,15 @@ there whenever you want to access the Doctrine console.
     <?php
     // doctrine.php - Put in your application root
 
-    use Doctrine\ORM\Tools\Setup;
-    use Doctrine\ORM\EntityManager;
     use Doctrine\DBAL\Tools\Console\Helper\ConnectionHelper;
     use Doctrine\DBAL\Tools\Console\Helper\EntityManagerHelper;
     use Doctrine\ORM\Tools\Console\ConsoleRunner;
     use Symfony\Component\Console\Helper\HelperSet;
 
-    $lib = "/path/to/doctrine2-orm/lib";
-    require $lib . '/Doctrine/ORM/Tools/Setup.php';
-    Setup::registerAutoloadDirectory($lib);
+    require_once 'my_bootstrap.php';
 
-    $paths = array("/path/to/entities-or-mapping-files");
-    $isDevMode = false;
-
-    $config = Setup::createAnnotationMetadataConfiguration($paths, $isDevMode);
-    $em = EntityManager::create($dbParams, $config);
+    // Any way to access the EntityManager from  your application
+    $em = GetMyEntityManager();
     
     $helperSet = new HelperSet(array(
         'db' => new ConnectionHelper($em->getConnection()),
@@ -160,50 +120,6 @@ there whenever you want to access the Doctrine console.
 
     ConsoleRunner::run($helperSet);
  
-Adding own commands
-~~~~~~~~~~~~~~~~~~~
-
-You can also add your own commands on-top of the Doctrine supported
-tools if you are using a manually built (Non-PEAR) binary.
-
-To include a new command on Doctrine Console, you need to do modify the
-``doctrine.php`` file a little:
-
-.. code-block:: php
-
-    <?php
-    // doctrine.php
-    use Symfony\Component\Console\Helper\Application;
-
-    // as before ...
-
-    // replace the ConsoleRunner::run() statement with:
-    $cli = new Application('Doctrine Command Line Interface', \Doctrine\ORM\Version::VERSION);
-    $cli->setCatchExceptions(true);
-    $cli->setHelperSet($helperSet);
-
-    // Register All Doctrine Commands
-    ConsoleRunner::addCommands($cli);
-
-    // Register your own command
-    $cli->addCommand(new \MyProject\Tools\Console\Commands\MyCustomCommand);
-
-    // Runs console application
-    $cli->run();
-
-Additionally, include multiple commands (and overriding previously
-defined ones) is possible through the command:
-
-.. code-block:: php
-
-    <?php
-
-    $cli->addCommands(array(
-        new \MyProject\Tools\Console\Commands\MyCustomCommand(),
-        new \MyProject\Tools\Console\Commands\SomethingCommand(),
-        new \MyProject\Tools\Console\Commands\AnotherCommand(),
-        new \MyProject\Tools\Console\Commands\OneMoreCommand(),
-    ));
 
 Command Overview
 ~~~~~~~~~~~~~~~~
@@ -518,4 +434,47 @@ You can also reverse engineer a database using the
     a useful domain model.
 
 
+Adding own commands
+-------------------
 
+You can also add your own commands on-top of the Doctrine supported
+tools if you are using a manually built (Non-PEAR) binary.
+
+To include a new command on Doctrine Console, you need to do modify the
+``doctrine.php`` file a little:
+
+.. code-block:: php
+
+    <?php
+    // doctrine.php
+    use Symfony\Component\Console\Helper\Application;
+
+    // as before ...
+
+    // replace the ConsoleRunner::run() statement with:
+    $cli = new Application('Doctrine Command Line Interface', \Doctrine\ORM\Version::VERSION);
+    $cli->setCatchExceptions(true);
+    $cli->setHelperSet($helperSet);
+
+    // Register All Doctrine Commands
+    ConsoleRunner::addCommands($cli);
+
+    // Register your own command
+    $cli->addCommand(new \MyProject\Tools\Console\Commands\MyCustomCommand);
+
+    // Runs console application
+    $cli->run();
+
+Additionally, include multiple commands (and overriding previously
+defined ones) is possible through the command:
+
+.. code-block:: php
+
+    <?php
+
+    $cli->addCommands(array(
+        new \MyProject\Tools\Console\Commands\MyCustomCommand(),
+        new \MyProject\Tools\Console\Commands\SomethingCommand(),
+        new \MyProject\Tools\Console\Commands\AnotherCommand(),
+        new \MyProject\Tools\Console\Commands\OneMoreCommand(),
+    ));