doctrine2/manual/en/tools.txt

++ The Doctrine Console

The Doctrine Console is a Command Line Interface tool for simplifying many common commands during the development of a project that uses Doctrine.

+++ Installation

If you installed Doctrine 2 through PEAR, the `doctrine` command line tool should already be available to you.

If you use Doctrine through SVN or a release package you need to copy the `doctrine` and `doctrine.php` files from the `tools/sandbox` or `bin` folder, respectively, to a location of your choice, for example a `tools` folder of your project.
In addition you may need to edit `doctrine.php` and adjust some paths to the new environment. You may want to add require_once() statement at the top of doctrine.php to set up the include_path for Doctrine classes.

+++ Getting Help

Type `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:

    doctrine orm:generate-entities --help

+++ Configuration

Whenever the `doctrine` command line tool is invoked, it is only able to access Commands that were defined by developer. Dependency Injection (DI) is the responsable to inject support into this utility, but it is up to the developer define it.
The Doctrine CLI tool from the bin/ folder already defines all the DBAL and ORM commands shipped with Doctrine.

All the commands of the Doctrine Console require either the `db` or the `em` helpers to be defined in order to work correctly. Doctrine Console requires the definition of a HelperSet that is the DI tool to be injected in the Console.
In case of a project that is dealing exclusively with DBAL, the ConnectionHelper is required:

    [php]
    $helperSet = new \Symfony\Components\Console\Helper\HelperSet(array(
        'db' => new \Doctrine\DBAL\Tools\Console\Helper\ConnectionHelper($conn)
    ));
    $cli->setHelperSet($helperSet);

When dealing with the ORM package, the EntityManagerHelper is required:

    [php]
    $helperSet = new \Symfony\Components\Console\Helper\HelperSet(array(
        'em' => new \Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper($em)
    ));
    $cli->setHelperSet($helperSet);

The HelperSet instance has to be generated in a separate file (ie. `cli-config.php`) that contains typical Doctrine
bootstrap code and predefines the needed HelperSet attributes mentioned above. A typical `cli-config.php` file looks as follows:

    [php]
    require_once __DIR__ . '/../../lib/Doctrine/Common/ClassLoader.php';

    $classLoader = new \Doctrine\Common\ClassLoader('Entities', __DIR__);
    $classLoader->register();

    $classLoader = new \Doctrine\Common\ClassLoader('Proxies', __DIR__);
    $classLoader->register();

    $config = new \Doctrine\ORM\Configuration();
    $config->setMetadataCacheImpl(new \Doctrine\Common\Cache\ArrayCache);
    $config->setProxyDir(__DIR__ . '/Proxies');
    $config->setProxyNamespace('Proxies');

    $connectionOptions = array(
        'driver' => 'pdo_sqlite',
        'path' => 'database.sqlite'
    );

    $em = \Doctrine\ORM\EntityManager::create($connectionOptions, $config);

    $helperSet = new \Symfony\Components\Console\Helper\HelperSet(array(
        'db' => new \Doctrine\DBAL\Tools\Console\Helper\ConnectionHelper($em->getConnection()),
        'em' => new \Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper($em)
    ));

It is important to define a correct HelperSet that doctrine.php script will ultimately use. The Doctrine Binary
will automatically find the first instance of HelperSet in the global variable namespace and use this.

You can also add your own commands on-top of the Doctrine supported tools.
To include a new command on Doctrine Console, you need to do:

    [php]
    $cli->addCommand(new \MyProject\Tools\Console\Commands\MyCustomCommand());

Additionally, include multiple commands (and overriding previously defined ones) is possible through the command:

    [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

The following Commands are currently available:

 * `help`                            Displays help for a command (?)
 * `list`                            Lists commands
 * `dbal:import`                     Import SQL file(s) directly to Database.
 * `dbal:run-sql`                    Executes arbitrary SQL directly from the command line.
 * `orm:clear-cache:metadata`        Clear all metadata cache of the various cache drivers.
 * `orm:clear-cache:query`           Clear all query cache of the various cache drivers.
 * `orm:clear-cache:result`          Clear result cache of the various cache drivers.
 * `orm:convert-d1-schema`           Converts Doctrine 1.X schema into a Doctrine 2.X schema.
 * `orm:convert-mapping`             Convert mapping information between supported formats.
 * `orm:ensure-production-settings`  Verify that Doctrine is properly configured for a production environment.
 * `orm:generate-entities`           Generate entity classes and method stubs from your mapping information.
 * `orm:generate-proxies`            Generates proxy classes for entity classes.
 * `orm:generate-repositories`       Generate repository classes from your mapping information.
 * `orm:run-dql`                     Executes arbitrary DQL directly from the command line.
 * `orm:schema-tool:create`          Processes the schema and either create it directly on EntityManager Storage Connection or generate the SQL output.
 * `orm:schema-tool:drop`            Processes the schema and either drop the database schema of EntityManager Storage Connection or generate the SQL output.
 * `orm:schema-tool:update`          Processes the schema and either update the database schema of EntityManager Storage Connection or generate the SQL output.

++ Database Schema Generation

To generate your database schema from your Doctrine mapping files you can use the
`SchemaTool` class or the `schema-tool` Console Command.

When using the SchemaTool class directly, create your schema using the `createSchema()` method. First create an instance of the `SchemaTool` and pass it an instance of the `EntityManager` that you want to use to create the schema. This method receives an array of `ClassMetadataInfo` instances.

    [php]
    $tool = new \Doctrine\ORM\Tools\SchemaTool($em);
    $classes = array(
      $em->getClassMetadata('Entities\User'),
      $em->getClassMetadata('Entities\Profile')
    );
    $tool->createSchema($classes);

To drop the schema you can use the `dropSchema()` method.

    [php]
    $tool->dropSchema($classes);

This drops all the tables that are currently used by your metadata model.
When you are changing your metadata alot during development you might want
to drop the complete database instead of only the tables of the current model
to clean up with orphaned tables.

    [php]
    $tool->dropSchema($classes, \Doctrine\ORM\Tools\SchemaTool::DROP_DATABASE);

You can also use database introspection to update your schema easily with the 
`updateSchema()` method. It will compare your existing database schema to the 
passed array of `ClassMetdataInfo` instances.

    [php]
    $tool->updateSchema($classes);

If you want to use this functionality from the command line you can use the
`schema-tool` command.

To create the schema use the `create` command:

    $ php doctrine orm:schema-tool:create

To drop the schema use the `drop` command:

    $ php doctrine orm:schema-tool:drop

If you want to drop and then recreate the schema then use both options:

    $ php doctrine orm:schema-tool:drop
    $ php doctrine orm:schema-tool:create

As you would think, if you want to update your schema use the `update` command:

    $ php doctrine orm:schema-tool:update

All of the above commands also accept a `--dump-sql` option that will output the SQL
for the ran operation.

    $ php doctrine orm:schema-tool:create --dump-sql

Before using the orm:schema-tool commands, remember to configure your cli-config.php properly.

++ Convert Mapping Information

Doctrine comes with some special tools for working with the various supported
formats for specifying mapping information.

You have the ability to convert from a few different sources.

* An existing database
* A directory of YAML schema files
* A directory of XML schema files
* A directory of PHP scripts which populate `ClassMetadataInfo` instances
* A directory of PHP classes defining Doctrine entities with annotations

To convert a mapping source you can do everything you need with the `ClassMetadataExporter`.

    [php]
    $cme = new \Doctrine\ORM\Tools\Export\ClassMetadataExporter();

Once you have an instance you can start adding mapping sources to convert.

    [php]
    $cme->addMappingSource('/path/to/yml', 'yml');
    $cme->addMappingSource('/path/to/xml', 'xml');
    $cme->addMappingSource('/path/to/php', 'php');
    $cme->addMappingSource('/path/to/annotations', 'annotation');

Now to convert the added mapping sources you can do so by using the exporter drivers.

    [php]
    $metadatas = $cme->getMetadatasForMappingSources();
    
    $exporter = $cme->getExporter('yml', '/path/to/export/yml');
    $exporter->setMetadatas($metadatas);
    $exporter->export();

This functionality functionality is also available from the command line to for 
example convert some YAML mapping files to XML.

    $ php doctrine orm:convert-mapping /path/to/mapping-path xml /path/to/mapping-path-converted-to-xml

It is even possible to define more than one path as source:

    $ php doctrine orm:convert-mapping --from /path/to/mapping-path1 --from /path/to/mapping-path2 /path/to/mapping-path3 xml /path/to/mapping-path-converted-to-xml

++ Reverse Engineering

You can use the same `ClassMetadataExporter` to reverse engineer a database and 
generate YAML, XML, etc. from your existing databases.

    [php]
    $sm = $em->getConnection()->getSchemaManager();

    $cme->addMappingSource($sm, 'database');
    $metadatas = $cme->getMetadatasForMappingSources();

    $exporter = $cme->getExporter('yml', '/path/to/export/yml');
    $exporter->setMetadatas($metadatas);
    $exporter->export();

From the command line it is very simple to do something like reverse engineer
your existing database to set of YAML mapping files.

    $ php doctrine orm:convert-mapping database yml /path/to/mapping-path-converted-to-yml

> **CAUTION**
> Reverse Engineering is not always working perfectly depending on special cases.
> It will only detect Many-To-One relations (even if they are One-To-One) and
> will try to create entities from Many-To-Many tables. It also has problems
> with naming of foreign keys that have multiple column names. Any Reverse Engineered
> Database-Schema needs considerable manual work to become a useful domain model.