254 lines
11 KiB
Plaintext
254 lines
11 KiB
Plaintext
++ The 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.
|
|
|
|
+++ 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.
|
|
You probably need to edit `doctrine.php` to adjust some paths to the new environment, most importantly the first line that includes the `Doctrine\Common\ClassLoader`.
|
|
|
|
+++ 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 can access alls Commands that were registered by developer.
|
|
There is no auto-detection mechanism at work. The `bin\doctrine.php` file already registers all the commands that
|
|
currently ship with Doctrine DBAL and ORM. If you want to use additional commands you have to register them yourself.
|
|
|
|
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 (i.e. `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
|
|
|
|
> **Note**
|
|
>
|
|
> SchemaTool can do harm to your database. It will drop or alter tables, indexes, sequences and such. Please use
|
|
> this tool with caution in development and not on a production server. It is meant for helping you develop your
|
|
> Database Schema, but NOT with migrating schema from A to B in production. A safe approach would be generating
|
|
> the SQL on development server and saving it into SQL Migration files that are executed manually on the production
|
|
> server.
|
|
>
|
|
> SchemaTool assumes your Doctrine Project uses the given database on its own. Update and Drop commands will
|
|
> mess with other tables if they are not related to the current project that is using Doctrine. Please be careful!
|
|
|
|
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 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.
|
|
|
|
[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.
|
|
|
|
> **NOTE**
|
|
>
|
|
> When using the Annotation Mapping Driver you have to either setup your autoloader in the cli-config.php
|
|
> correctly to find all the entities, or you can use the second argument of the `EntityManagerHelper` to
|
|
> specify all the paths of your entities (or mapping files), i.e.
|
|
> `new \Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper($em, $mappingPaths);`
|
|
|
|
++ Convert Mapping Information
|
|
|
|
To convert some mapping information between the various supported formats you can
|
|
use the `ClassMetadataExporter` to get exporter instances for the different formats:
|
|
|
|
[php]
|
|
$cme = new \Doctrine\ORM\Tools\Export\ClassMetadataExporter();
|
|
|
|
Once you have a instance you can use it to get an exporter. For example, the yml
|
|
exporter:
|
|
|
|
[php]
|
|
$exporter = $cme->getExporter('yml', '/path/to/export/yml');
|
|
|
|
Now you can export some `ClassMetadata` instances:
|
|
|
|
[php]
|
|
$classes = array(
|
|
$em->getClassMetadata('Entities\User'),
|
|
$em->getClassMetadata('Entities\Profile')
|
|
);
|
|
$exporter->setMetadata($classes);
|
|
$exporter->export();
|
|
|
|
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:
|
|
|
|
$ php 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
|
|
`ClassMetadataInfo` instances and generate YAML, XML, etc. from them.
|
|
|
|
First you need to retrieve the metadata instances with the `DatabaseDriver`:
|
|
|
|
[php]
|
|
$em->getConfiguration()->setMetadataDriverImpl(
|
|
new \Doctrine\ORM\Mapping\Driver\DatabaseDriver(
|
|
$em->getConnection()->getSchemaManager()
|
|
)
|
|
);
|
|
|
|
$cmf = new DisconnectedClassMetadataFactory($em);
|
|
$metadata = $cmf->getAllMetadata();
|
|
|
|
Now you can get an exporter instance and export the loaded metadata to yml:
|
|
|
|
[php]
|
|
$exporter = $cme->getExporter('yml', '/path/to/export/yml');
|
|
$exporter->setMetadata($metadata);
|
|
$exporter->export();
|
|
|
|
You can also reverse engineer a database using the `orm:convert-mapping` command:
|
|
|
|
$ php doctrine orm:convert-mapping --from-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. |