RetailCRM-Mirror/doctrine2
1
0
Fork 0
mirror of synced 2024-12-13 22:56:04 +03:00
Code Issues Projects Releases Wiki Activity

Rework configuration and tools section to include Composer

Browse Source
This commit is contained in:
Benjamin Eberlei 2012-06-16 11:57:56 +02:00
parent feeef689f3
commit 65e2f60b40
2 changed files with 138 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
en/reference/configuration.rst
View File

@ -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();

143
en/reference/tools.rst
View File

@ -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(),
));