doctrine2/manual/docs/en/utilities.txt

++ Facade

+++ Creating & Dropping Databases

Doctrine offers the ability to create and drop your databases from your defined Doctrine connections. The only trick to using it is that the name of your Doctrine connection must be the name of your database. This is required due to the fact that PDO does not offer a method for retrieving the name of the database you are connected to. So in order to create and drop the database Doctrine itself must be aware of the name of the database.

+++ Convenience Methods

Doctrine offers static convenience methods available in the main Doctrine class. These methods perform some of the most used functionality of Doctrine with one method. Most of these methods are using in the Doctrine_Task system. These tasks are also what are executed from the Doctrine_Cli.

<code type="php">
// Turn debug on/off and check for whether it is on/off
Doctrine::debug(true);

if (Doctrine::debug()) {
    echo 'debugging is on';
} else {
    echo 'debugging is off';
}

// Get the path to your Doctrine libraries
$path = Doctrine::getPath();

// Load your models so that they are present and loaded for Doctrine to work with
// Returns an array of the Doctrine_Records that were found and loaded
$models = Doctrine::loadModels('/path/to/models');
print_r($models);

// Get array of all the models loaded and present to Doctrine
$models = Doctrine::getLoadedModels();

// Pass an array of classes to the above method and it will filter out the ones that are not Doctrine_Records
$models = Doctrine::getLoadedModels(array('User', 'Formatter', 'Doctrine_Record'));
print_r($models); // would return array('User') because Formatter and Doctrine_Record are not Doctrine_Records

// Get Doctrine_Connection object for an actual table name
$conn = Doctrine::getConnectionByTableName('user'); // returns the connection object that the table name is associated with

// Generate your models from an existing database
Doctrine::generateModelsFromDb('/path/to/generate/models');

// Generate YAML schema from an existing database
Doctrine::generateYamlFromDb('/path/to/dump/schema.yml');

// Generate your models from YAML schema
Doctrine::generateModelsFromYaml('/path/to/schema.yml', '/path/to/generate/models');

// Create all your tables from an existing set of models
Doctrine::createTablesFromModels('/path/to/models');

// Create the tables supplied in the array
Doctrine::createTablesFromArray(array('User', 'Phoneumber'));

// Generate string of sql commands from an existing set of models
Doctrine::generateSqlFromModels('/path/to/models');

// Generate YAML schema from an existing set of models
Doctrine::generateYamlFromModels('/path/to/schema.yml', '/path/to/models');

// It is required your connection name to be the same as your database name in order for the drop/create functionality below to work.

// Create all databases for connections.
Doctrine::createDatabases();

// Drop all databases for connections
Doctrine::dropDatabases();

// Dump all data for your models to a yaml fixtures file
// 2nd argument is a bool value for whether or not to generate individual fixture files for each model. If true you need to specify a folder instead of a file.
Doctrine::dumpData('/path/to/dump/data.yml', true);

// Load data from yaml fixtures files
// 2nd argument is a bool value for whether or not to append the data when loading or delete all data first before loading
Doctrine::loadData('/path/to/fixture/files', true);

// Run a migration process for a set of migration classes
$num = 5; // migrate to version #5
Doctrine::migration('/path/to/migrations', $num);

// Generate a blank migration class template
Doctrine::generateMigrationClass('ClassName', '/path/to/migrations');

// Generate all migration classes for an existing database
Doctrine::generateMigrationsFromDb('/path/to/migrations');

// Generate all migration classes for an existing set of models
// 2nd argument is optional if you have already loaded your models using loadModels()
Doctrine::generateMigrationsFromModels('/path/to/migrations', '/path/to/models');

// Get Doctrine_Table instance for a model
$userTable = Doctrine::getTable('User');

// Compile doctrine in to a single php file
$drivers = array('mysql'); // specify the array of drivers you want to include in this compiled version
Doctrine::compile('/path/to/write/compiled/doctrine', $drivers);

// Dump doctrine objects for debugging
$conn = Doctrine_Manager::connection();
Doctrine::dump($conn);
</code>

+++ Tasks

Tasks are classes which bundle some of the core convenience methods in to tasks that can be easily executed by setting the required arguments. These tasks are directly used in the Doctrine command line interface.

<code>
BuildAll
BuildAllLoad
BuildAllReload
Compile
CreateDb
CreateTables
Dql
DropDb
DumpData
Exception
GenerateMigration
GenerateMigrationsDb
GenerateMigrationsModels
GenerateModelsDb
GenerateModelsYaml
GenerateSql
GenerateYamlDb
GenerateYamlModels
LoadData
LoadDummyData
Migrate
RebuildDb
</code>

You can read below about how to execute Doctrine Tasks standalone in your own scripts.

++ Command Line Interface

+++ Introduction
The Doctrine Cli is a collection of tasks that help you with your day to do development and testing with your Doctrine implementation. Typically with the examples in this manual, you setup php scripts to perform whatever tasks you may need. This Cli tool is aimed at providing an out of the box solution for those tasks.

+++ Tasks
Below is a list of available tasks for managing your Doctrine implementation.

<code>

./cli build-all
./cli build-all-load
./cli build-all-reload
./cli compile
./cli create-db
./cli create-tables
./cli dql
./cli drop-db
./cli dump-data
./cli generate-migration
./cli generate-migrations-from-db
./cli generate-migrations-from-models
./cli generate-models-from-db
./cli generate-models-from-yaml
./cli generate-sql
./cli generate-yaml-from-db
./cli generate-yaml-from-models
./cli load-data
./cli load-dummy-data
./cli migrate
./cli rebuild-db

</code>

The tasks for the CLI are separate from the CLI and can be used standalone. Below is an example.

<code type="php">
$task = new Doctrine_Task_GenerateModelsFromYaml();

$args = array('yaml_schema_path' => '/path/to/schema',
              'models_path'      => '/path/to/models');

$task->setArguments($args);

try {
  if ($task->validate()) {
    $task->execute();
  }
} catch (Exception $e) {
  throw new Doctrine_Exception($e->getMessage());
}
</code>

+++ Usage

File named "cli" that is set to executable

<code>
#!/usr/bin/env php
<?php
chdir(dirname(__FILE__));
include('cli.php');
</code>

Actual php file named "cli.php" that implements the Doctrine_Cli. 
<code type="php">
// Include your Doctrine configuration/setup here, your connections, models, etc.

// Configure Doctrine Cli
// Normally these are arguments to the cli tasks but if they are set here the arguments will be auto-filled and are not required for you to enter them.

$config = array('data_fixtures_path'  =>  '/path/to/data/fixtures',
                'models_path'         =>  '/path/to/models',
                'migrations_path'     =>  '/path/to/migrations',
                'sql_path'            =>  '/path/to/data/sql',
                'yaml_schema_path'    =>  '/path/to/schema');

$cli = new Doctrine_Cli($config);
$cli->run($_SERVER['argv']);
</code>

Now you can begin executing commands.

<code>
./cli generate-models-from-yaml
./cli create-tables
</code>

++ Sandbox

+++ Installation

Currently the only way you can install and use the sandbox is by svn. It is available by checking out the trunk of Doctrine. The sandbox comes loaded with generated models, sample schema files, data fixtures and a portable sqlite database to play with.

<code>
svn co http://doctrine.pengus.net/svn/trunk doctrine_trunk
cd doctrine_trunk/tools/sandbox
chmod 0777 cli

./cli
</code>

The above steps should give you a functioning sandbox. Execute the ./cli command without specifying a task will show you an index of all the available cli tasks in Doctrine.