doctrine2/manual/new/docs/en/getting-started.txt

++ Requirements
Doctrine requires PHP >= 5.1. it doesn't require any external libraries. For database function call abstraction Doctrine uses PDO which is bundled with php by default.

++ Installation
++ Compiling
Doctrine is quite big framework and usually dozens of files are being included on each request. This brings a lot of overhead. In fact these file operations are as time consuming as sending multiple queries to database server. The clean separation of class per file works well in developing environment, however when project goes commercial distribution the speed overcomes the clean separation of class per file -convention.

Doctrine offers method called {{compile()}} to solve this issue. The compile method makes a single file of most used Doctrine components which can then be included on top of your script. By default the file is created into Doctrine root by the name {{Doctrine.compiled.php}}.

Compiling is a method for making a single file of most used doctrine runtime components including the compiled file instead of multiple files (in worst cases dozens of files) can improve performance by an order of magnitude. In cases where this might fail, a {{Doctrine_Exception}} is throw detailing the error.

<code type='php'>
Doctrine::compile();
// on some other script:
require_once('path_to_doctrine/Doctrine.compiled.php');
</code>
++ Starting new project
++ Working with existing databases
++ Exporting classes
+++ Introduction

Doctrine supports exporting record classes into database. This means that based on the definitions given in your record definitions Doctrine will alter your database schema.

Lets say we have a classes called User and Phonenumber with the following definitions:

<code type='php'>
// file User.php
class User extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('name', 'string', 20);
    }
    public function setUp()
    {
        $this->hasMany('Phonenumber', array('local' => 'id',
                                            'foreign' => 'user_id'));
    }
}
// file Phonenumber.php
class Phonenumber extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('phonenumber', 'string', 20);
        $this->hasColumn('user_id', 'integer');
    }
    public function setUp()
    {
        $this->hasOne('User', array('local' => 'user_id',
                                    'foreign' => 'id',
                                    'onDelete' => 'CASCADE'));
    }
}
</code>

Now lets say these classes are in directory 'models/'. We can make Doctrine to iterate through this directory and attach these classes into your database structure with the following script:

<code type='php'>

require_once('path-to-doctrine/lib/Doctrine.php');

spl_autoload_register(array('Doctrine', 'autoload'));

// in order to export we need a database connection
$manager = Doctrine_Manager::getInstance();
$conn    = $manager->openConnection('pgsql://user:pass@localhost/test');

Doctrine::export('models');
</code>

This would execute the following queries on mysql.

<code>
CREATE TABLE user (id BIGINT AUTO_INCREMENT, name VARCHAR(20), PRIMARY KEY(id), INDEX(id));
CREATE TABLE phonenumber (id INT AUTO_INCREMENT, phonenumber VARCHAR(20), user_id BIGINT, PRIMARY KEY(id), INDEX(user_id));
ALTER TABLE phonenumber ADD CONSTRAINT FOREIGN KEY (user_id) REFERENCES user(id) ON DELETE CASCADE;
</code>

Pay attention to the following things:

# The autoincrement primary key columns are auto-added since we didn't specify any primary key columns
# Doctrine auto-adds indexes to the referenced relation columns (this is needed in mysql)

+++ Getting export queries

There might be situations where you don't want to execute the export queries immediately rather you want to get the query strings and maybe attach them to a build.sql file. This can be easily achieved as follows:

<code type='php'>
require_once('path-to-doctrine/lib/Doctrine.php');

spl_autoload_register(array('Doctrine', 'autoload'));

$manager = Doctrine_Manager::getInstance();
$conn    = $manager->openConnection('pgsql://user:pass@localhost/test');

$queries = Doctrine::exportSql('models');

print_r($queries);
</code>

Notice that the methods Doctrine::export() and Doctrine::exportSql() are just short cuts for Doctrine_Export::export() and Doctrine_Export::exportSql(). So the following code is equivalent with the previous example:
<code type='php'>
require_once('path-to-doctrine/lib/Doctrine.php');

spl_autoload_register(array('Doctrine', 'autoload'));

$manager = Doctrine_Manager::getInstance();
$conn    = $manager->openConnection('pgsql://user:pass@localhost/test');

$queries = $conn->export->exportSql('models');

print_r($queries);
</code>



+++ Convenience methods

In the previous example we exported all record classes within a directory. Sometimes you may want to export specific classes. It can be achieved by giving exportClasses() an array of class names:
<code type='php'>
require_once('path-to-doctrine/lib/Doctrine.php');

spl_autoload_register(array('Doctrine', 'autoload'));

$manager = Doctrine_Manager::getInstance();
$conn    = $manager->openConnection('pgsql://user:pass@localhost/test');


$conn->export->exportClasses(array('User', 'Phonenumber'));
</code>

Consider the same situation and you want to get the array of sql queries needed to perform the exporting. It can be achieved with Doctrine_Export::exportClassesSql().


+++ Export options

<code type='php'>
// export everything, table definitions and constraints

$manager->setAttribute(Doctrine::ATTR_EXPORT, Doctrine::EXPORT_ALL);

// export classes without constraints

$manager->setAttribute(Doctrine::ATTR_EXPORT, Doctrine::EXPORT_TABLES ^ 
                                              Doctrine::EXPORT_CONSTRAINTS);

// turn off exporting

$manager->setAttribute(Doctrine::ATTR_EXPORT, Doctrine::EXPORT_NONE);
</code>