Tools

Doctrine Console

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

For the following examples, we will set up the CLI as bin/doctrine.

1
#!/usr/bin/env php
<?php

use Doctrine\ORM\Tools\Console\ConsoleRunner;
use Doctrine\ORM\Tools\Console\EntityManagerProvider\SingleManagerProvider;

// replace with path to your own project bootstrap file
require_once 'bootstrap.php';

// replace with mechanism to retrieve EntityManager in your app
$entityManager = GetEntityManager();

$commands = [
    // If you want to add your own custom console commands,
    // you can do so here.
];

ConsoleRunner::run(
    new SingleManagerProvider($entityManager),
    $commands
);
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

$ > php bin/doctrine orm:generate-entities --help

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 ClassMetadata instances.

1
<?php
$tool = new \Doctrine\ORM\Tools\SchemaTool($em);
$classes = array(
  $em->getClassMetadata('Entities\User'),
  $em->getClassMetadata('Entities\Profile')
);
$tool->createSchema($classes);
2
3
4
5
6
7

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

1
<?php
$tool->dropSchema($classes);
2

This drops all the tables that are currently used by your metadata model. When you are changing your metadata a lot 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.

1
<?php
$tool->dropSchema($classes, \Doctrine\ORM\Tools\SchemaTool::DROP_DATABASE);
2

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 ClassMetadata instances.

1
<?php
$tool->updateSchema($classes);
2

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:

1
$ php bin/doctrine orm:schema-tool:create

To drop the schema use the drop command:

1
$ php bin/doctrine orm:schema-tool:drop

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

1
$ php bin/doctrine orm:schema-tool:drop
$ php bin/doctrine orm:schema-tool:create
2

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

1
$ php bin/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.

1
$ php bin/doctrine orm:schema-tool:create --dump-sql

Entity Generation

Generate entity classes and method stubs from your mapping information.

1
$ php bin/doctrine orm:generate-entities
$ php bin/doctrine orm:generate-entities --update-entities
$ php bin/doctrine orm:generate-entities --regenerate-entities
2
3

This command is not suited for constant usage. It is a little helper and does not support all the mapping edge cases very well. You still have to put work in your entities after using this command.

It is possible to use the EntityGenerator on code that you have already written. It will not be lost. The EntityGenerator will only append new code to your file and will not delete the old code. However this approach may still be prone to error and we suggest you use code repositories such as GIT or SVN to make backups of your code.

It makes sense to generate the entity code if you are using entities as Data Access Objects only and don't put much additional logic on them. If you are however putting much more logic on the entities you should refrain from using the entity-generator and code your entities manually.

Convert Mapping Information

Convert mapping information between supported formats.

This is an execute one-time command. It should not be necessary for you to call this method multiple times, especially when using the --from-database flag.

Converting an existing database schema into mapping files only solves about 70-80% of the necessary mapping information. Additionally the detection from an existing database cannot detect inverse associations, inheritance types, entities with foreign keys as primary keys and many of the semantical operations on associations such as cascade.

To convert some mapping information between the various supported formats you can use the ClassMetadataExporter to get exporter instances for the different formats:

1
<?php
$cme = new \Doctrine\ORM\Tools\Export\ClassMetadataExporter();
2

Once you have a instance you can use it to get an exporter. For example, the yml exporter:

1
<?php
$exporter = $cme->getExporter('yml', '/path/to/export/yml');
2

Now you can export some ClassMetadata instances:

1
<?php
$classes = array(
  $em->getClassMetadata('Entities\User'),
  $em->getClassMetadata('Entities\Profile')
);
$exporter->setMetadata($classes);
$exporter->export();
2
3
4
5
6
7

This functionality is also available from the command line to convert your loaded mapping information to another format. The orm:convert-mapping command accepts two arguments, the type to convert to and the path to generate it:

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

Reverse Engineering

You can use the DatabaseDriver to reverse engineer a database to an array of ClassMetadata instances and generate YAML, XML, etc. from them.

First you need to retrieve the metadata instances with the DatabaseDriver:

1
<?php
$em->getConfiguration()->setMetadataDriverImpl(
    new \Doctrine\ORM\Mapping\Driver\DatabaseDriver(
        $em->getConnection()->getSchemaManager()
    )
);

$cmf = new \Doctrine\ORM\Tools\DisconnectedClassMetadataFactory();
$cmf->setEntityManager($em);
$metadata = $cmf->getAllMetadata();
2
3
4
5
6
7
8
9
10

Now you can get an exporter instance and export the loaded metadata to yml:

1
<?php
$cme = new \Doctrine\ORM\Tools\Export\ClassMetadataExporter();
$exporter = $cme->getExporter('yml', '/path/to/export/yml');
$exporter->setMetadata($metadata);
$exporter->export();
2
3
4
5

You can also reverse engineer a database using the orm:convert-mapping command:

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

Runtime vs Development Mapping Validation

For performance reasons Doctrine ORM has to skip some of the necessary validation of metadata mappings. You have to execute this validation in your development workflow to verify the associations are correctly defined.

You can either use the Doctrine Command Line Tool:

1
doctrine orm:validate-schema

If the validation fails, you can change the verbosity level to check the detected errors:

doctrine orm:validate-schema -v

Or you can trigger the validation manually:

1
<?php
use Doctrine\ORM\Tools\SchemaValidator;

$validator = new SchemaValidator($entityManager);
$errors = $validator->validateMapping();

if (count($errors) > 0) {
    // Lots of errors!
    echo implode("\n\n", $errors);
}
2
3
4
5
6
7
8
9
10

If the mapping is invalid the errors array contains a positive number of elements with error messages.

Adding own commands

You can also add your own commands on-top of the Doctrine supported tools if you are using a manually built console script.

To include a new command on Doctrine Console, you need to do modify the doctrine.php file a little:

1
<?php
// doctrine.php
use Symfony\Component\Console\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();
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

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

1
<?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(),
));
2
3
4
5
6
7
8

Re-use console application

You are also able to retrieve and re-use the default console application. Just call ConsoleRunner::createApplication(...) with an appropriate HelperSet, like it is described in the configuration section.

1
<?php

// Retrieve default console application
$cli = ConsoleRunner::createApplication($helperSet);

// Runs console application
$cli->run();
2
3
4
5
6
7