Utilities

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.

// Turn debug on/off and check for whether it is on/off
Doctrine_Core::debug( true );

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

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

// Set the path to your Doctrine libraries if it is some non-default location
Doctrine_Core::setPath( '/path/to/doctrine/libs' );

// 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_Core::loadModels( '/path/to/models', Doctrine_Core::MODEL_LOADING_CONSERVATIVE );
// or Doctrine_Core::MODEL_LOADING_AGGRESSIVE
print_r( $models );

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

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

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

// Generate YAML schema from an existing database
Doctrine_Core::generateYamlFromDb( '/path/to/dump/schema.yml', array( 'connection_name' ), $options );

// Generate your models from an existing database
Doctrine_Core::generateModelsFromDb( '/path/to/generate/models', array( 'connection_name' ), $options );

// Array of options and the default values
$options = array(
    'packagesPrefix'       => 'Package',
    'packagesPath'         => '',
    'packagesFolderName'   => 'packages',
    'suffix'               => '.php',
    'generateBaseClasses'  => true,
    'baseClassesPrefix'    => 'Base',
    'baseClassesDirectory' => 'generated',
    'baseClassName'        => 'Doctrine_Record'
);

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

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

// Create all your tables from an existing set of models
// Will generate sql for all loaded models if no directory is given
Doctrine_Core::createTablesFromModels( '/path/to/models' );

// Generate string of sql commands from an existing set of models
// Will generate sql for all loaded models if no directory is given
Doctrine_Core::generateSqlFromModels( '/path/to/models' );

// Generate array of sql statements to create the array of passed models
Doctrine_Core::generateSqlFromArray( array( 'User', 'Phonenumber' ) );

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

// Create all databases for connections.
// Array of connection names is optional
Doctrine_Core::createDatabases( array( 'connection_name' ) );

// Drop all databases for connections
// Array of connection names is optional
Doctrine_Core::dropDatabases( array( 'connection_name' ) );

// 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_Core::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_Core::loadData( '/path/to/fixture/files', true );

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

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

// Generate all migration classes for an existing database
Doctrine_Core::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_Core::generateMigrationsFromModels( '/path/to/migrations', '/path/to/models' );

// Get Doctrine_Table instance for a model
$userTable = Doctrine_Core::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_Core::compile( '/path/to/write/compiled/doctrine', $drivers );

// Dump doctrine objects for debugging
$conn = Doctrine_Manager::connection();
Doctrine_Core::dump( $conn );

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.

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

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.

$ ./doctrine
Doctrine Command Line Interface
./doctrine build-all
./doctrine build-all-load
./doctrine build-all-reload
./doctrine compile
./doctrine create-db
./doctrine create-tables
./doctrine dql
./doctrine drop-db
./doctrine dump-data
./doctrine generate-migration
./doctrine generate-migrations-db
./doctrine generate-migrations-models
./doctrine generate-models-db
./doctrine generate-models-yaml
./doctrine generate-sql
./doctrine generate-yaml-db
./doctrine generate-yaml-models
./doctrine load-data
./doctrine migrate
./doctrine rebuild-db

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

$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() );
}

Usage

File named “doctrine” that is set to executable

#!/usr/bin/env php
[php]

chdir( dirname( __FILE__ ) );
include( 'doctrine.php' );

Actual php file named “doctrine.php” that implements the Doctrine_Cli.

// 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'] );

Now you can begin executing commands.

./doctrine generate-models-yaml
./doctrine create-tables

Sandbox

Installation

You can install the sandbox by downloading the special sandbox package from http://www.doctrine-project.org/download or you can install it via svn below.

svn co http://www.doctrine-project.org/svn/branches/0.11 doctrine
cd doctrine/tools/sandbox
chmod 0777 doctrine

./doctrine

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

Conclusion

I hope some of these utilities discussed in this chapter are of use to you. Now lets discuss how Doctrine maintains stability and avoids regressions by using Unit Testing.