Doctrine¶

About this Version¶

This is the Doctrine 1.2 ORM Manual, covering up to version 1.2.4.

This manual is currently being “transliterated” to use reStructuredText. This will allow it to be built with Sphinx, hosted by readthedocs and hopefully integrated into the new official Doctrine documentation server. Chapters up to and including Working with Models should display properly, but the rest of the manual still hasn’t been fully rewritten. This can make code examples and tables hard to read.

How to Contribute¶

If you’d like to help convert the manual to reST (particularly if you can read Japanese), you can fork and send pull requests via http://github.com/dominics/doctrine1-documentation. It might be a good idea to open an issue if you’re going to work on a page, so that work isn’t duplicated.

Eventually, this version will hopefully end up back in http://github.com/doctrine/doctrine1-documentation

What is Doctrine?¶

Doctrine is an object relational mapper (ORM) for PHP 5.2.3+ that sits on top of a powerful database abstraction layer (DBAL). One of its key features is the option to write database queries in a proprietary object oriented SQL dialect called Doctrine Query Language (DQL), inspired by Hibernates HQL. This provides developers with a powerful alternative to SQL that maintains flexibility without requiring unnecessary code duplication.

What is an ORM?¶

Object relational mapping is a technique used in programming languages when dealing with databases for translating incompatible data types in relational databases. This essentially allows for us to have a “virtual object database,” that can be used from the programming language. Lots of free and commercial packages exist that allow this but sometimes developers chose to create their own ORM.

What is the Problem?¶

We are faced with many problems when building web applications. Instead of trying to explain it all it is best to read what Wikipedia has to say about object relational mappers.

Data management tasks in object-oriented (OO) programming are typically implemented by manipulating objects, which are almost always non-scalar values. For example, consider an address book entry that represents a single person along with zero or more phone numbers and zero or more addresses. This could be modeled in an object-oriented implementation by a “person object” with “slots” to hold the data that comprise the entry: the person’s name, a list (or array) of phone numbers, and a list of addresses. The list of phone numbers would itself contain “phone number objects” and so on. The address book entry is treated as a single value by the programming language (it can be referenced by a single variable, for instance). Various methods can be associated with the object, such as a method to return the preferred phone number, the home address, and so on.

However, many popular database products such as SQL DBMS can only store and manipulate scalar values such as integers and strings organized within tables.

The programmer must either convert the object values into groups of simpler values for storage in the database (and convert them back upon retrieval), or only use simple scalar values within the program. Object-relational mapping is used to implement the first approach.

The height of the problem is translating those objects to forms that can be stored in the database for easy retrieval, while preserving the properties of the objects and their relationships; these objects are then said to be persistent.

—Pulled from Wikipedia

Minimum Requirements¶

Doctrine requires PHP >= 5.2.3+, although it doesn’t require any external libraries. For database function call abstraction Doctrine uses PDO which comes bundled with the PHP official release that you get from www.php.net.

Basic Overview¶

Doctrine is a tool for object-relational mapping in PHP. It sits on top of PDO and is itself divided into two main layers, the DBAL and the ORM. The picture below shows how the layers of Doctrine work together.

The DBAL (Database Abstraction Layer) completes and extends the basic database abstraction/independence that is already provided by PDO. The DBAL library can be used standalone, if all you want is a powerful database abstraction layer on top of PDO. The ORM layer depends on the DBAL and therefore, when you load the ORM package the DBAL is already included.

Doctrine Explained¶

The following section tries to explain where Doctrine stands in the world of ORM tools. The Doctrine ORM is mainly built around the Active Record, Data Mapper and Data Mapping patterns.

Through extending a specific base class named :php:class:`Doctrine_Record`, all the child classes get the typical ActiveRecord interface (save/delete/etc.) and it allows Doctrine to easily participate in and monitor the lifecycles of your records. The real work, however, is mostly forwarded to other components, like the :php:class:`Doctrine_Table` class. This class has the typical Data Mapper interface, :php:meth:`createQuery`, :php:meth:`find(id)`, :php:meth:`findAll`, :php:meth:`findBy*`, :php:meth:`findOneBy*` etc. So the ActiveRecord base class enables Doctrine to manage your records and provides them with the typical ActiveRecord interface whilst the mapping footwork is done elsewhere.

The ActiveRecord approach comes with its typical limitations. The most obvious is the enforcement for a class to extend a specific base class in order to be persistent (a :php:class:`Doctrine_Record`). In general, the design of your domain model is pretty much restricted by the design of your relational model. There is an exception though. When dealing with inheritance structures, Doctrine provides some sophisticated mapping strategies which allow your domain model to diverge a bit from the relational model and therefore give you a bit more freedom.

Doctrine is in a continuous development process and we always try to add new features that provide more freedom in the modeling of the domain. However, as long as Doctrine remains mainly an ActiveRecord approach, there will always be a pretty large, (forced) similarity of these two models.

The current situation is depicted in the following picture.

As you see in the picture, the domain model can’t drift far away from the bounds of the relational model.

After mentioning these drawbacks, it’s time to mention some advantages of the ActiveRecord approach. Apart from the (arguably slightly) simpler programming model, it turns out that the strong similarity of the relational model and the Object Oriented (OO) domain model also has an advantage: It makes it relatively easy to provide powerful generation tools, that can create a basic domain model out of an existing relational schema. Further, as the domain model can’t drift far from the relational model due to the reasons above, such generation and synchronization tools can easily be used throughout the development process. Such tools are one of Doctrine’s strengths.

We think that these limitations of the ActiveRecord approach are not that much of a problem for the majority of web applications because the complexity of the business domains is often moderate, but we also admit that the ActiveRecord approach is certainly not suited for complex business logic (which is often approached using Domain-Driven Design) as it simply puts too many restrictions and has too much influence on your domain model.

Doctrine is a great tool to drive the persistence of simple or moderately complex domain models [1] and you may even find that it’s a good choice for complex domain models if you consider the trade-off between making your domain model more database-centric and implementing all the mapping on your own (because at the time of this writing we are not aware of any powerful ORM tools for PHP that are not based on an ActiveRecord approach).

Now you already know a lot about what Doctrine is and what it is not. If you would like to dive in now and get started right away, jump straight to the next chapter Getting Started.

Notes

Key Concepts¶

The Doctrine Query Language (DQL) is an object query language. It let’s you express queries for single objects or full object graphs, using the terminology of your domain model: class names, field names, relations between classes, etc. This is a powerful tool for retrieving or even manipulating objects without breaking the separation of the domain model (field names, class names, etc) from the relational model (table names, column names, etc). DQL looks very much like SQL and this is intended because it makes it relatively easy to grasp for people knowing SQL. There are, however, a few very important differences you should always keep in mind:

Take this example DQL query:

FROM User u LEFT JOIN u.Phonenumbers where u.level > 1

The things to notice about this query:

• We select from classes and not tables. We are selecting from the :php:class:`User` class/model.
• We join along associations (u.Phonenumbers)
• We can reference fields (u.level)
• There is no join condition (ON x.y = y.x). The associations between your classes and how these are expressed in the database are known to Doctrine (You need to make this mapping known to Doctrine, of course. How to do that is explained later in the Defining Models chapter.).

It’s very important that we speak about classes, fields and associations between classes here. :php:class:`User` is not a table / table name . It may be that the name of the database table that the :php:class:`User` class is mapped to is indeed named :php:class:`User` but you should nevertheless adhere to this differentiation of terminology. This may sound nit picky since, due to the ActiveRecord approach, your relational model is often very similar to your domain model but it’s really important. The column names are rarely the same as the field names and as soon as inheritance is involved, the relational model starts to diverge from the domain model. You can have a class :php:class:`User` that is in fact mapped to several tables in the database. At this point it should be clear that talking about “selecting from the :php:class:`User` table” is simply wrong then. And as Doctrine development continues there will be more features available that allow the two models to diverge even more.

Further Reading¶

For people new to object-relational mapping and (object-oriented) domain models we recommend the following literature:

The books by Martin Fowler cover a lot of the basic ORM terminology, the different approaches of modeling business logic and the patterns involved.

Another good read is about Driven Design. Though serious Domain-Driven Design is currently not possible with Doctrine, this is an excellent resource for good domain modeling, especially in complex business domains, and the terminology around domain models that is pretty widespread nowadays is explained in depth (Entities, Value Objects, Repositories, etc).

Conclusion¶

Well, now that we have given a little educational reading about the methodologies and principals behind Doctrine we are pretty much ready to dive in to everything that is Doctrine. Lets dive in to setting up Doctrine in the Getting Started chapter.

Checking Requirements¶

First we need to make sure that you can run Doctrine on your server. We can do this one of two ways:

First create a small PHP script named :php:meth:`phpinfo.php`` and upload it somewhere on your web server that is accessible to the web:

phpinfo();

Now execute it from your browser by going to http://localhost/phpinfo.php. You will see a list of information detailing your PHP configuration. Check that your PHP version is >= 5.2.3 and that you have PDO and the desired drivers installed.

Check that your PHP version is >= 5.2.3 with the following command:

php -v

Now check that you have PDO and the desired drivers installed with the following command:

php -i

You could also execute the phpinfo.php from the command line and get the same result as the above example:

php phpinfo.php

Installing¶

Currently it is possible to install Doctrine four different ways that are listed below:

• SVN (subversion)
• SVN externals
• PEAR Installer
• Download PEAR Package

It is recommended to download Doctrine via SVN (subversion), because in this case updating is easy. If your project is already under version control with SVN, you should choose SVN externals.

svn co http://svn.doctrine-project.org/branches/1.2 .

svn update

cd /var/www/my_project

svn propedit svn:externals lib/vendor

doctrine http://svn.doctrine-project.org/branches/1.2/lib

svn update

svn commit

pear install pear.doctrine-project.org/Doctrine-1.2.x

tar xzf Doctrine-1.2.1.tgz

Implementing¶

Now that you have Doctrine in your hands, we are ready to implement Doctrine in to our application. This is the first step towards getting started with Doctrine.

First create a directory named doctrine_test. This is where we will place all our test code:

mkdir doctrine_test
cd doctrine_test

mkdir lib
mkdir lib/vendor
mkdir lib/vendor/doctrine
mv /path/to/doctrine/lib doctrine

svn co http://svn.doctrine-project.org/branches/1.2/lib lib/vendor/doctrine

svn propedit svn:externals lib/vendor

doctrine http://svn.doctrine-project.org/branches/1.2/lib

svn update lib/vendor

// bootstrap.php
/* Bootstrap Doctrine.php, register autoloader specify
   configuration attributes and load models. */

require_once(dirname(**FILE**) . '/lib/vendor/doctrine/Doctrine.php');

// bootstrap.php
spl_autoload_register(array('Doctrine', 'autoload'));

// bootstrap.php
$manager = Doctrine_Manager::getInstance();

$class = new Doctrine_Some_Class();

class Doctrine
{
    public function autoload($className)
    {
        $classPath = str_replace('_', '/', $className) . '.php';
        $path = '/path/to/doctrine/' . $classPath;
        require_once($path);
        return true;
    }
}

// bootstrap.php
/* Bootstrap Doctrine.php, register autoloader specify
   configuration attributes and load models. */

require_once(dirname(**FILE**) . '/lib/vendor/doctrine/Doctrine.php');
spl_autoload_register(array('Doctrine', 'autoload'));
$manager = Doctrine_Manager::getInstance();

// test.php
require_once('bootstrap.php');
echo Doctrine_Core::getPath();

php test.php /path/to/doctrine/lib

Conclusion¶

Phew! This was our first chapter where we actually got into some code. As you saw, first we were able to check that our server can actually run Doctrine. Then we learned all the different ways we can download and install Doctrine. Lastly we learned how to implement Doctrine by setting up a small test environment that we will use to perform some exercises in the remaining chapters of the book.

Now lets move on and get our first taste of Doctrine connections in the Introduction to Connections chapter.

DSN, the Data Source Name¶

In order to connect to a database through Doctrine, you have to create a valid DSN (Data Source Name).

Doctrine supports both PEAR DB/MDB2 like data source names as well as PDO style data source names. The following section deals with PEAR like data source names. If you need more info about the PDO-style data source names see the documentation on PDO.

phptype(dbsyntax)://username:password@protocol+hostspec/database?option=value

phptype://username:password@protocol+hostspec:110//usr/db_file.db
phptype://username:password@hostspec/database
phptype://username:password@hostspec
phptype://username@hostspec
phptype://hostspec/database phptype://hostspec phptype:///database
phptype:///database?option=value&anotheroption=anothervalue
phptype(dbsyntax) phptype

phptype(syntax)://user:pass@protocol(proto_opts)/database

Opening New Connections¶

Opening a new database connection in Doctrine is very easy. If you wish to use PDO you can just initialize a new :php:class:`PDO` object.

Remember our bootstrap.php file we created in the Getting Started chapter? Under the code where we registered the Doctrine autoloader we are going to instantiate our new connection:

// bootstrap.php
$dsn = 'mysql:dbname=testdb;host=127.0.0.1';
$user = 'dbuser';
$password = 'dbpass';

$dbh = new PDO($dsn, $user, $password);
$conn = Doctrine_Manager::connection($dbh);

// bootstrap.php
$conn->setOption('username', $user);
$conn->setOption('password', $password);

Lazy Database Connecting¶

Lazy-connecting to database can save a lot of resources. There might be many times where you don’t need an actual database connection, hence its always recommended to use lazy-connecting (that means Doctrine will only connect to database when needed).

This feature can be very useful when using for example page caching, hence not actually needing a database connection on every request. Remember connecting to database is an expensive operation.

In the example below we will show you when you create a new Doctrine connection, the connection to the database isn’t created until it is actually needed.

// bootstrap.php
// At this point no actual connection to the database is created
$conn = Doctrine_Manager::connection('mysql://username:password@localhost/test');

// The first time the connection is needed, it is instantiated
// This query triggers the connection to be created
$conn->execute('SHOW TABLES');

Testing your Connection¶

After reading the previous sections of this chapter, you should now know how to create a connection. So, lets modify our bootstrap file to include the initialization of a connection. For this example we will just be using a sqlite memory database but you can use whatever type of database connection you prefer.

Add your database connection to bootstrap.php and it should look something like the following:

/* Bootstrap Doctrine.php, register autoloader and specify
   configuration attributes */

require_once('../doctrine/branches/1.2/lib/Doctrine.php');
spl_autoload_register(array('Doctrine', 'autoload'));
$manager = Doctrine_Manager::getInstance();

$conn = Doctrine_Manager::connection('sqlite::memory:', 'doctrine');

To test the connection lets modify our test.php script and perform a small test. Since we create a variable name $conn, that variable is available to the test script so lets setup a small test to make sure our connection is working:

First lets create a test table and insert a record:

// test.php
$conn->export->createTable('test', array('name' => array('type' => 'string')));
$conn->execute('INSERT INTO test (name) VALUES (?)', array('jwage'));

Now lets execute a simple SELECT query from the test table we just created to make sure the data was inserted and that we can retrieve it:

// test.php
$stmt = $conn->prepare('SELECT \* FROM test');
$stmt->execute();
$results = $stmt->fetchAll();
print_r($results);

Execute test.php from your terminal and you should see:

php test.php
Array(
  [0] => Array(
    [name] => jwage,
    [0] => jwage
  )
)

Conclusion¶

Great! Now we learned some basic operations of Doctrine connections. We have modified our Doctrine test environment to have a new connection. This is required because the examples in the coming chapters will require a connection.

Lets move on to the Configuration chapter and learn how you can control functionality and configurations using the Doctrine attribute system.

Levels of Configuration¶

Doctrine has a three-level configuration structure. You can set configuration attributes at a global, connection and table level. If the same attribute is set on both lower level and upper level, the uppermost attribute will always be used. So for example if a user first sets default fetchmode in global level to :php:const:`Doctrine_Core::FETCH_BATCH` and then sets a table fetchmode to :php:const:`Doctrine_Core::FETCH_LAZY`, the lazy fetching strategy will be used whenever the records of that table are being fetched.

• Global level

  The attributes set in global level will affect every connection and every table in each connection.

• Connection level

  The attributes set in connection level will take effect on each table in that connection.

• Table level

  The attributes set in table level will take effect only on that table.

In the following example we set an attribute at the global level:

// bootstrap.php
$manager->setAttribute(Doctrine_Core::ATTR_VALIDATE, Doctrine_Core::VALIDATE_ALL);

In the next example above we override the global attribute on given connection:

// bootstrap.php
$conn->setAttribute(Doctrine_Core::ATTR_VALIDATE, Doctrine_Core::VALIDATE_NONE);

In the last example we override once again the connection level attribute in the table level:

// bootstrap.php
$table = Doctrine_Core::getTable('User');
$table->setAttribute(Doctrine_Core::ATTR_VALIDATE, Doctrine_Core::VALIDATE_ALL);

Default Attributes¶

Doctrine has a few specific attributes available that allow you to specify the default values of things that in the past were hardcoded values. Such as default column length, default column type, etc.

// bootstrap.php
$manager->setAttribute(
    Doctrine::ATTR_DEFAULT_COLUMN_OPTIONS,
    array('type' => 'string', 'length' => 255, 'notnull' => true)
);

$manager->setAttribute(
    Doctrine::ATTR_DEFAULT_IDENTIFIER_OPTIONS,
    array('name' => '%s_id', 'type' => 'string', 'length' => 16)
);

Portability¶

Each database management system (DBMS) has it’s own behaviors. For example, some databases capitalize field names in their output, some lowercase them, while others leave them alone. These quirks make it difficult to port your applications over to another database type. Doctrine strives to overcome these differences so your applications can switch between DBMS’s without any changes. For example switching from sqlite to mysql.

The portability modes are bitwised, so they can be combined using | and removed using ^. See the examples section below on how to do this.

// bootstrap.php
$conn->setAttribute(
    Doctrine_Core::ATTR_PORTABILITY,
    Doctrine_Core::PORTABILITY_FIX_CASE | Doctrine_Core::PORTABILITY_RTRIM
);

// bootstrap.php
$conn->setAttribute(
    Doctrine_Core::ATTR_PORTABILITY,
    Doctrine_Core::PORTABILITY_ALL ^ Doctrine_Core::PORTABILITY_RTRIM
);

Identifier quoting¶

You can quote the db identifiers (table and field names) with :php:meth:`quoteIdentifier`. The delimiting style depends on which database driver is being used.

Some of the internal Doctrine methods generate queries. Enabling the quote_identifier attribute of Doctrine you can tell Doctrine to quote the identifiers in these generated queries. For all user supplied queries this option is irrelevant.

Portability is broken by using the following characters inside delimited identifiers:

Delimited identifiers are known to generally work correctly under the following drivers: Mssql, Mysql, Oracle, Pgsql, Sqlite and Firebird.

When using the :php:const:`Doctrine_Core::ATTR_QUOTE_IDENTIFIER` option, all of the field identifiers will be automatically quoted in the resulting SQL statements:

// bootstrap.php
$conn->setAttribute(Doctrine_Core::ATTR_QUOTE_IDENTIFIER, true);

Will result in a SQL statement that all the field names are quoted with the backtick ` operator (in MySQL):

SELECT * FROM sometable WHERE `id` = '123'

As opposed to:

SELECT * FROM sometable WHERE id = '123'

Hydration Overwriting¶

By default Doctrine is configured to overwrite any local changes you have on your objects if you were to query for some objects which have already been queried for and modified:

$user = Doctrine_Core::getTable('User')->find(1);
$user->username = 'newusername';

Now I have modified the above object and if I were to query for the same data again, my local changes would be overwritten:

$user = Doctrine_Core::getTable('User')->find(1);
echo $user->username;

You can disable this behavior by using the :php:const:`Doctrine_Core::ATTR_HYDRATE_OVERWRITE` attribute:

// bootstrap.php
$conn->setAttribute(Doctrine_Core::ATTR_HYDRATE_OVERWRITE, false);

Now if were to run the same test we ran above, the modified username would not be overwritten.

Configure Table Class¶

If you want to configure the class to be returned when using the :php:meth:`Doctrine_Core::getTable` method you can set the :php:const:`Doctrine_Core::ATTR_TABLE_CLASS` attribute. The only requirement is that the class extends :php:class:`Doctrine_Table`.

// bootstrap.php
$conn->setAttribute(Doctrine_Core::ATTR_TABLE_CLASS, 'MyTableClass');

Now the MyTableClass would look like the following:

class MyTableClass extends Doctrine_Table
{
    public function myMethod()
    {
        // run some query and return the results
    }
}

Now when you do the following it will return an instance of MyTableClass:

$user = $conn->getTable('MyModel')->myMethod();

If you want to customize the table class even further you can customize it for each model. Just create a class named MyModelTable and make sure it is able to be autoloaded.

class MyModelTable extends MyTableClass
{
    public function anotherMethod()
    {
        // run some query and return the results
    }
}

Now when I execute the following code it will return an instance of MyModelTable:

echo get_class($conn->getTable('MyModel')); // MyModelTable

Configure Query Class¶

If you would like to configure the base query class returned when you create new query instances, you can use the :php:const:`Doctrine_Core::ATTR_QUERY_CLASS` attribute. The only requirement is that it extends the Doctrine_Query class.

// bootstrap.php
$conn->setAttribute(Doctrine_Core::ATTR_QUERY_CLASS, 'MyQueryClass');

The MyQueryClass would look like the following:

class MyQueryClass extends Doctrine_Query
{
}

Now when you create a new query it will return an instance of MyQueryClass:

$q = Doctrine_Core::getTable('User') ->createQuery('u');
echo get_class($q); // MyQueryClass

Configure Collection Class¶

Since you can configure the base query and table class, it would only make sense that you can also customize the collection class Doctrine should use. We just need to set the :php:const:`Doctrine_Core::ATTR_COLLECTION_CLASS` attribute.

// bootstrap.php
$conn->setAttribute(Doctrine_Core::ATTR_COLLECTION_CLASS, 'MyCollectionClass');

The only requirement of the MyCollectionClass is that it must extend Doctrine_Collection:

$phonenumbers = $user->Phonenumber;
echo get_class($phonenumbers); // MyCollectionClass

Disabling Cascading Saves¶

You can optionally disable the cascading save operations which are enabled by default for convenience with the :php:const:`Doctrine_Core::ATTR_CASCADE_SAVES` attribute. If you set this attribute to false it will only cascade and save if the record is dirty. This means that you can’t cascade and save records who are dirty that are more than one level deep in the hierarchy, but you benefit with a significant performance improvement.

$conn->setAttribute(Doctrine_Core::ATTR_CASCADE_SAVES, false);

Exporting¶

The export attribute is used for telling Doctrine what it should export when exporting classes to your database for creating your tables.

If you don’t want to export anything when exporting you can use:

// bootstrap.php
$manager->setAttribute(Doctrine_Core::ATTR_EXPORT, Doctrine_Core::EXPORT_NONE);

For exporting tables only (but not constraints) you can use on of the following:

// bootstrap.php
$manager->setAttribute(Doctrine_Core::ATTR_EXPORT, Doctrine_Core::EXPORT_TABLES);

You can also use the following syntax as it is the same as the above:

// bootstrap.php
$manager->setAttribute(
    Doctrine_Core::ATTR_EXPORT,
    Doctrine_Core::EXPORT_ALL ^ Doctrine_Core::EXPORT_CONSTRAINTS
);

For exporting everything (tables and constraints) you can use:

// bootstrap.php
$manager->setAttribute(Doctrine_Core::ATTR_EXPORT, Doctrine_Core::EXPORT_ALL);

Naming convention attributes¶

Naming convention attributes affect the naming of different database related elements such as tables, indexes and sequences. Basically every naming convention attribute has affect in both ways. When importing schemas from the database to classes and when exporting classes into database tables.

So for example by default Doctrine naming convention for indexes is %s_idx. Not only do the indexes you set get a special suffix, also the imported classes get their indexes mapped to their non-suffixed equivalents. This applies to all naming convention attributes.

// bootstrap.php
$manager->setAttribute(Doctrine_Core::ATTR_IDXNAME_FORMAT, '%s_index');

// bootstrap.php
$manager->setAttribute(Doctrine_Core::ATTR_SEQNAME_FORMAT, '%s_sequence');

// bootstrap.php
$manager->setAttribute(Doctrine_Core::ATTR_TBLNAME_FORMAT, '%s_table');

// bootstrap.php
$manager->setAttribute(Doctrine_Core::ATTR_DBNAME_FORMAT, 'myframework_%s');

// bootstrap.php
$manager->setAttribute(Doctrine_Core::ATTR_VALIDATE, Doctrine_Core::VALIDATE_ALL);

// bootstrap.php
$manager->setAttribute(
    Doctrine_Core::ATTR_VALIDATE,
    Doctrine_Core::VALIDATE_LENGTHS | Doctrine_Core::VALIDATE_TYPES
);

Conclusion¶

Now we have gone over some of the most common attributes used to configure Doctrine. Some of these attributes may not apply to you ever or you may not understand what you could use them for now. As you read the next chapters you will see which attributes you do and don’t need to use and things will begin to make more sense.

If you saw some attributes you wanted to change the value above, then you should have added it to your bootstrap.php file and it should look something like the following now:

/* Bootstrap Doctrine.php, register autoloader and specify
   configuration attributes */

require_once('../doctrine/branches/1.2/lib/Doctrine.php');
spl_autoload_register(array('Doctrine', 'autoload'));
$manager = Doctrine_Manager::getInstance();

$conn = Doctrine_Manager::connection('sqlite::memory:', 'doctrine');

$manager->setAttribute(Doctrine_Core::ATTR_VALIDATE, Doctrine_Core::VALIDATE_ALL);
$manager->setAttribute(Doctrine_Core::ATTR_EXPORT, Doctrine_Core::EXPORT_ALL);
$manager->setAttribute(Doctrine_Core::ATTR_MODEL_LOADING, Doctrine_Core::MODEL_LOADING_CONSERVATIVE);

Now we are ready to move on to the next chapter where we will learn everything there is to know about Doctrine Connections.

Introduction¶

From the start Doctrine has been designed to work with multiple connections. Unless separately specified Doctrine always uses the current connection for executing the queries.

In this chapter we will demonstrate how to create and work with Doctrine connections.

Opening Connections¶

:php:class:`Doctrine_Manager` provides the static method :php:meth:`Doctrine_Manager::connection` which opens new connections.

In this example we will show you to open a new connection:

// test.php
$conn = Doctrine_Manager::connection('mysql://username:password@localhost/test', 'connection 1');

Retrieve Connections¶

If you use the :php:meth:`Doctrine_Manager::connection` method and don’t pass any arguments it will return the current connection:

// test.php
$conn2 = Doctrine_Manager::connection();
if ($conn === $conn2) {
    echo 'Doctrine_Manager::connection() returns the current connection';
}

Current Connection¶

The current connection is the last opened connection. In the next example we will show how you can get the current connection from the :php:class:`Doctrine_Manager` instance:

// test.php
$conn2 = Doctrine_Manager::connection('mysql://username2:password2@localhost/test2', 'connection 2');
if ($conn2 === $manager->getCurrentConnection()) {
    echo 'Current connection is the connection we just created!';
}

Change Current Connection¶

You can change the current connection by calling :php:meth:`Doctrine_Manager::setCurrentConnection`:

// test.php
$manager->setCurrentConnection('connection 1');
echo $manager->getCurrentConnection()->getName(); // connection 1

Iterating Connections¶

You can iterate over the opened connections by simply passing the manager object to a foreach clause. This is possible since :php:class:`Doctrine_Manager` implements special :php:class:`IteratorAggregate` interface.

// test.php
foreach($manager as $conn) {
    echo $conn->getName() . "";
}

Get Connection Name¶

You can easily get the name of a :php:class:`Doctrine_Connection` instance with the following code:

// test.php
$conn = Doctrine_Manager::connection();
$name = $manager->getConnectionName($conn);
echo $name; // connection 1

Close Connection¶

You can easily close a connection and remove it from the Doctrine connection registry with the following code:

// test.php
$conn = Doctrine_Manager::connection();
$manager->closeConnection($conn);

If you wish to close the connection but not remove it from the Doctrine connection registry you can use the following code instead:

// test.php
$conn = Doctrine_Manager::connection();
$conn->close();

Get All Connections¶

You can retrieve an array of all the registered connections by using the :php:meth:`Doctrine_Manager::getConnections` method like below:

// test.php
$conns = $manager->getConnections();
foreach ($conns as $conn) {
    echo $conn->getName() . "";
}

The above is essentially the same as iterating over the :php:class:`Doctrine_Manager` object like we did earlier. Here it is again:

// test.php
foreach ($manager as $conn) {
    echo $conn->getName() . "";
}

Count Connections¶

You can easily get the number of connections from a :php:class:`Doctrine_Manager` object since it implements the Countable interface:

// test.php
$num = count($manager);
echo $num;

The above is the same as doing:

// test.php
$num = $manager->count();

Creating and Dropping Database¶

When you create connections using Doctrine, you gain the ability to easily create and drop the databases related to those connections.

This is as simple as using some functions provided in the :php:class:`Doctrine_Manager` or :php:class:`Doctrine_Connection` classes.

The following code will iterate over all instantiated connections and call the :php:meth:`dropDatabases`/:php:meth:`createDatabases` function on each one:

// test.php
$manager->createDatabases();
$manager->dropDatabases();

// test.php
$conn->createDatabase();
$conn->dropDatabase();

Writing Custom Connections¶

Sometimes you might need the ability to create your own custom connection classes and utilize them. You may need to extend mysql, or write your own connection type completely. This is possible by writing a few classes and then registering the new connection type with Doctrine.

So in order to create a custom connection first we need to write the following classes:

class Doctrine_Connection_Test extends Doctrine_Connection_Common
{
}

class Doctrine_Adapter_Test implements Doctrine_Adapter_Interface
{
    // All the methods defined in the interface
}

Now we register them with Doctrine:

// bootstrap.php
$manager->registerConnectionDriver('test', 'Doctrine_Connection_Test');

With those few changes something like this is now possible:

$conn = $manager->openConnection('test://username:password@localhost/dbname');

If we were to check what classes are used for the connection you will notice that they are the classes we defined above:

echo get_class($conn); // Doctrine_Connection_Test
echo get_class($conn->getDbh()); // Doctrine_Adapter_Test

Conclusion¶

Now that we have learned all about Doctrine connections we should be ready to dive right in to models in the Introduction to Models chapter. We will learn a little bit about Doctrine models first. Then we will start to have some fun and create our first test models and see what kind of magic Doctrine can provide for you.

Introduction¶

At the lowest level, Doctrine represents your database schema with a set of PHP classes. These classes define the schema and behavior of your model.

A basic model that represents a user in a web application might look something like this:

class User extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('username', 'string', 255);
        $this->hasColumn('password', 'string', 255);
    }

    public function setUp()
    {
        $this->actAs('Timestampable');
    }
}

Each :php:class:`Doctrine_Record` child class can have a :php:meth:`setTableDefinition` and :php:meth:`setUp` method. The :php:meth:`setTableDefinition` method is for defining columns, indexes and other information about the schema of tables. The :php:meth:`setUp` method is for attaching behaviors and defining relationships between :php:class:`Doctrine_Record` child classes. In the above example we are enabling the Timestampable behavior which adds some automagic functionality. You will learn more about what all can be used in these functions in the Defining Models chapter.

Generating Models¶

Doctrine offers ways to generate these classes to make it easier to get started using Doctrine.

CREATE TABLE user (
    id BIGINT(20) NOT NULL AUTO_INCREMENT,
    first_name VARCHAR(255) DEFAULT NULL,
    last_name VARCHAR(255) DEFAULT NULL,
    username VARCHAR(255) DEFAULT NULL,
    password VARCHAR(255) DEFAULT NULL,
    type VARCHAR(255) DEFAULT NULL,
    is_active TINYINT(1) DEFAULT '1',
    is_super_admin TINYINT(1) DEFAULT '0',
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    PRIMARY KEY (id)
) ENGINE=InnoDB

// bootstrap.php
$conn = Doctrine_Manager::connection('mysql://root:mys3cr3et@localhost/doctrinetest', 'doctrine');

mkdir doctrine_test/models

// test.php
Doctrine_Core::generateModelsFromDb(
    'models',
    array('doctrine'),
    array('generateTableClasses' => true)
);

// models/generated/BaseUser.php
/**
 * This class has been auto-generated by the Doctrine ORM Framework
 */
abstract class BaseUser extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->setTableName('user');
        $this->hasColumn(
            'id', 'integer', 8,
            array(
                'type' => 'integer',
                'length' => 8,
                'primary' => true,
                'autoincrement' => true
            )
        );
        $this->hasColumn(
            'first_name', 'string', 255,
            array(
                'type' => 'string',
                'length' => 255
            )
        );
        $this->hasColumn(
            'last_name', 'string', 255,
            array(
                'type' => 'string',
                'length' => 255
            )
        );
        $this->hasColumn(
            'username', 'string', 255,
            array(
                'type' => 'string',
                'length' => 255
            )
        );
        $this->hasColumn(
            'password', 'string', 255,
            array(
                'type' => 'string',
                'length' => 255
            )
        );
        $this->hasColumn(
            'type', 'string', 255,
            array(
                'type' => 'string',
                'length' => 255
            )
        );
        $this->hasColumn(
            'is_active', 'integer', 1,
            array(
                'type' => 'integer',
                'length' => 1,
                'default' => '1'
            )
        );
        $this->hasColumn(
            'is_super_admin', 'integer', 1,
            array(
                'type' => 'integer',
                'length' => 1,
                'default' => '0'
            )
        );
        $this->hasColumn(
            'created_at', 'timestamp', null,
            array(
                'type' => 'timestamp',
                'notnull' => true
            )
        );
        $this->hasColumn(
            'updated_at', 'timestamp', null,
            array(
                'type' => 'timestamp',
                'notnull' => true
            )
        );
    }
}

// models/User.php
/**
 * This class has been auto-generated by the Doctrine ORM Framework
 */
class User extends BaseUser
{
}

// models/UserTable.php
/**
 * This class has been auto-generated by the Doctrine ORM Framework
 */
class UserTable extends Doctrine_Table
{
}

// models/User.php
class User extends BaseUser
{
    public function setPassword($password)
    {
        return $this->_set('password', md5($password));
    }
}

// bootstrap.php
$manager->setAttribute(Doctrine_Core::ATTR_AUTO_ACCESSOR_OVERRIDE, true);

// bootstrap.php
Doctrine_Core::loadModels('models');

// test.php
$user = new User();
$user->username = 'jwage';
$user->password = 'changeme';

echo $user->password; // outputs md5 hash and not changeme

php test.php 4cb9c8a8048fd02294477fcb1a41191a

// models/UserTable.php
class UserTable extends Doctrine_Table
{
    public function getCreatedToday()
    {
        $today = date('Y-m-d h:i:s', strtotime(date('Y-m-d')));
        return $this->createQuery('u')
            ->where('u.created_at > ?', $today)
            ->execute();
    }
}

// bootstrap.php
$manager->setAttribute(Doctrine_Core::ATTR_AUTOLOAD_TABLE_CLASSES, true);

// test.php
$usersCreatedToday = Doctrine_Core::getTable('User')->getCreatedToday();

// test.php
Doctrine_Core::generateYamlFromModels('schema.yml', 'models');

php test.php

User:
tableName: user
columns:
  id:
    type: integer(8)
    primary: true
    autoincrement: true
  is_active:
    type: integer(1)
    default: '1'
  is_super_admin:
    type: integer(1)
    default: '0'
  created_at:
    type: timestamp(25)
    notnull: true
  updated_at:
    type: timestamp(25)
    notnull: true
  first_name: string(255)
  last_name: string(255)
  username: string(255)
  password: string(255)
  type: string(255)

// generate.php
require_once('bootstrap.php');

Doctrine_Core::dropDatabases(); Doctrine_Core::createDatabases();
Doctrine_Core::generateModelsFromYaml('schema.yml', 'models');
Doctrine_Core::createTablesFromModels('models');

php generate.php

User:
actAs: [Timestampable]
columns:
  is_active:
    type: integer(1)
    default: '1'
  is_super_admin:
    type: integer(1)
    default: '0'
  first_name: string(255)
  last_name: string(255)
  username: string(255)
  password: string(255)
  type: string(255)

php generate.php

Manually Writing Models¶

You can optionally skip all the convenience methods and write your models manually using nothing but your own PHP code. You can learn all about the models syntax in the Defining Models chapter.

Autoloading Models¶

Doctrine offers two ways of loading models. We have conservative (lazy) loading, and aggressive loading. Conservative loading will not require the PHP file initially, instead it will cache the path to the class name and this path is then used in the :php:meth:`Doctrine_Core::modelsAutoload`.

To use Doctrine model loading you need to register the model autoloader in your bootstrap:

// bootstrap.php
spl_autoload_register(array('Doctrine_Core', 'modelsAutoload'));

Below are some examples using the both types of model loading.

$manager->setAttribute(Doctrine_Core::ATTR_MODEL_LOADING, Doctrine_Core::MODEL_LOADING_CONSERVATIVE);

Doctrine_Core::loadModels('models');

// triggers call to Doctrine_Core::modelsAutoload() and the class is included
$user = new User();

$manager->setAttribute(Doctrine_Core::ATTR_MODEL_LOADING, Doctrine_Core::MODEL_LOADING_AGGRESSIVE);

Doctrine_Core::loadModels('/path/to/models');

Conclusion¶

This chapter is probably the most intense chapter so far but it is a good one. We learned a little about how to use models, how to generate models from existing databases, how to write our own models, and how to maintain our models as YAML schema files. We also modified our Doctrine test environment to implement some functionality for loading models from our models directory.

This topic of Doctrine models is so large that it warranted the chapters being split in to three pieces to make it easier on the developer to absorb all the information. In Defining Models we will really get in to the API we use to define our models.

Columns¶

One problem with database compatibility is that many databases differ in their behavior of how the result set of a query is returned. MySQL leaves the field names unchanged, which means if you issue a query of the form "SELECT myField FROM ..." then the result set will contain the field myField.

Unfortunately, this is just the way MySQL and some other databases do it. Postgres for example returns all field names in lowercase whilst Oracle returns all field names in uppercase. “So what? In what way does this influence me when using Doctrine?”, you may ask. Fortunately, you don’t have to bother about that issue at all.

Doctrine takes care of this problem transparently. That means if you define a derived Record class and define a field called myField you will always access it through $record->myField (or $record['myField'], whatever you prefer) no matter whether you’re using MySQL or Postgres or Oracle etc.

In short: You can name your fields however you want, using under_scores, camelCase or whatever you prefer.

// models/Book.php
class Book extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('bookTitle as title', 'string');
    }
}

# schema.yml
Book:
  columns:
    bookTitle:
      name: bookTitle as title
      type: string

// test.php
$book = new Book();
$book->title = 'Some book';
$book->save();

// models/generated/BaseUser.php
class User extends BaseUser
{
    public function setTableDefinition()
    {
        $this->hasColumn('username', 'string', 255,
            array('default' => 'default username'));
    }
}

# schema.yml
User:
  # ...
  columns:
    username:
      type: string(255)
      default: default username
    #...

// test.php
$user = new User();
echo $user->username; // default username

'sometime' = array(
    'type' => 'time',
    'default' => '12:34:05',
    'notnull' => true,
),

'sometext' = array(
    'type' => 'string',
    'length' => 12,
),

class Test extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('booltest', 'boolean');
    }
}

Test:
  columns:
    booltest: boolean

class Test extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('integertest', 'integer', 4, array(
            'unsigned' => true
        ));
    }
}

Test:
  columns:
    integertest:
      type: integer(4)
      unsigned: true

class Test extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('floattest', 'float');
    }
}

Test:
  columns:
    floattest: float

class Test extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('decimaltest', 'decimal');
    }
}

Test:
  columns:
    decimaltest: decimal

class Test extends Doctrine_Record
{
    public function setTableDefinition() {
        $this->hasColumn('decimaltest', 'decimal', 18,
            array('scale' => 2)
        );
    }
}

Test:
  columns:
    decimaltest:
      type: decimal(18)
      scale: 2

class Test extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('stringtest', 'string', 200, array(
            'fixed' => true
        ));
    }
}

Test:
  columns:
    stringtest:
      type: string(200)
      fixed: true

class Test extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('arraytest', 'array', 10000);
    }
}

Test:
  columns:
    arraytest: array(10000)

class Test extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('objecttest', 'object');
    }
}

Test:
  columns:
    objecttest: object

class Test extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('blobtest', 'blob');
    }
}

Test:
  columns:
    blobtest: blob

class Test extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('clobtest', 'clob');
    }
}

Test:
  columns:
    clobtest: clob

class Test extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('timestamptest', 'timestamp');
    }
}

Test:
  columns:
    timestamptest: timestamp

class Test extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('timetest', 'time');
    }
}

Test:
  columns:
    timetest: time

class Test extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('datetest', 'date');
    }
}

Test:
  columns:
    datetest: date

$conn->setAttribute(Doctrine_Core::ATTR_USE_NATIVE_ENUM, true);

class Test extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('enumtest', 'enum', null,
            array('values' => array('php', 'java', 'python'))
        );
    }
}

Test:
  columns:
    enumtest:
      type: enum
      values: [php, java, python]

class Test extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('gziptest', 'gzip');
    }
}

Test:
  columns:
    gziptest: gzip

class Example extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('id', 'string', 32, array(
            'type' => 'string',
            'fixed' => 1,
            'primary' => true,
            'length' => '32' )
        );

        $this->hasColumn('someint', 'integer', 10, array(
            'type' => 'integer',
            'unsigned' => true,
            'length' => '10'
        ));

        $this->hasColumn('sometime', 'time', 25, array(
            'type' => 'time',
            'default' => '12:34:05',
            'notnull' => true,
            'length' => '25'
        ));

        $this->hasColumn('sometext', 'string', 12, array(
            'type' => 'string',
            'length' => '12'
        ));

        $this->hasColumn('somedate', 'date', 25, array(
            'type' => 'date',
            'length' => '25'
        ));

        $this->hasColumn('sometimestamp', 'timestamp', 25, array(
            'type' => 'timestamp',
            'length' => '25'
        ));

        $this->hasColumn('someboolean', 'boolean', 25, array(
            'type' => 'boolean',
            'length' => '25'
        ));

        $this->hasColumn('somedecimal', 'decimal', 18, array(
            'type' => 'decimal',
            'length' => '18'
        ));

        $this->hasColumn('somefloat', 'float', 2147483647, array(
            'type' => 'float',
            'length' => '2147483647'
        ));

        $this->hasColumn('someclob', 'clob', 2147483647, array(
            'type' => 'clob',
            'length' => '2147483647'
        ));

        $this->hasColumn('someblob', 'blob', 2147483647, array(
            'type' => 'blob',
            'length' => '2147483647'
        ));
    }
}

Example:
  tableName: example
  columns:
    id:
      type:    string(32)
      fixed:   true
      primary: true
    someint:
      type:     integer(10)
      unsigned: true
    sometime:
      type:    time(25)
      default: '12:34:05'
      notnull: true
    sometext:      string(12)
    somedate:      date(25)
    sometimestamp: timestamp(25)
    someboolean:   boolean(25)
    somedecimal:   decimal(18)
    somefloat:     float(2147483647)
    someclob:      clob(2147483647)
    someblob:      blob(2147483647)

Relationships¶

// models/Forum_Board.php
class Forum_Board extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('name', 'string', 100);
        $this->hasColumn('description', 'string', 5000);
    }

    public function setUp()
    {
        $this->hasMany('Forum_Thread as Threads', array(
            'local' => 'id',
            'foreign' => 'board_id'
        ));
    }
}

# schema.yml
Forum_Board:
  columns:
    name:        string(100)
    description: string(5000)

// models/Forum_Thread.php
class Forum_Thread extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('user_id', 'integer');
        $this->hasColumn('board_id', 'integer');
        $this->hasColumn('title', 'string', 200);
        $this->hasColumn('updated', 'integer', 10);
        $this->hasColumn('closed', 'integer', 1);
    }

    public function setUp()
    {
        $this->hasOne('Forum_Board as Board', array(
            'local' => 'board_id',
            'foreign' => 'id'
        ));

        $this->hasOne('User', array(
            'local' => 'user_id',
            'foreign' => 'id'
        ));
    }
}

 # schema.yml
Forum_Thread:
  columns:
    user_id:  integer
    board_id: integer
    title:    string(200)
    updated:  integer(10)
    closed:   integer(1)
  relations:
    User:
      local: user_id
      foreign: id
      foreignAlias: Threads
    Board:
      class: Forum_Board
      local: board_id
      foreign: id
      foreignAlias: Threads

// test.php
$board = new Forum_Board();
$board->name = 'Some board';

// ...
$board->Threads[0]->title = 'new thread 1';
$board->Threads[1]->title = 'new thread 2';

// ...
$user = new User();
$user->username = 'jwage';
$board->Threads[0]->User= $user;
$board->Threads[1]->User = $user;

// ...
$board->save();

print_r($board->toArray(true));

$ php test.php
Array (
    [id] => 2
    [name] => Some board
    [description] =>
    [Threads] => Array
        (
            [0] => Array
                (
                    [id] => 3
                    [user_id] => 1
                    [board_id] => 2
                    [title] => new thread 1
                    [updated] =>
                    [closed] =>
                    [User] => Array
                        (
                            [id] => 1
                            [is_active] => 1
                            [is_super_admin] => 0
                            [first_name] =>
                            [last_name] =>
                            [username] => jwage
                            [password] =>
                            [type] =>
                            [created_at] => 2009-01-20 16:41:57
                            [updated_at] => 2009-01-20 16:41:57
                        )
                )
            [1] => Array
                (
                    [id] => 4
                    [user_id] => 1
                    [board_id] => 2
                    [title] => new thread 2
                    [updated] =>
                    [closed] =>
                    [User] => Array
                        (
                            [id] => 1
                            [is_active] => 1
                            [is_super_admin] => 0
                            [first_name] =>
                            [last_name] =>
                            [username] => jwage
                            [password] =>
                            [type] =>
                            [created_at] => 2009-01-20 16:41:57
                            [updated_at] => 2009-01-20 16:41:57
                        )
                )
        )
)

// models/Email.php
class Email extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('user_id', 'integer');
        $this->hasColumn('address', 'string', 150);
    }

    public function setUp()
    {
        $this->hasOne('User', array(
            'local' => 'user_id',
            'foreign' => 'id'
        ));
    }
}

# schema.yml
Email:
  columns:
      user_id: integer
      address: string(150)
  relations:
      User:
      local: user_id
      foreign: id
      foreignType: one

// models/User.php
class User extends BaseUser
{
    public function setUp()
    {
        parent::setUp();
        $this->hasOne('Email', array(
            'local' => 'id',
            'foreign' => 'user_id'
        ));
    }
}

# schema.yml
User:
    # ...
    relations:
        # ...
        Email:
            local: id
            foreign: user_id

// models/User.php
class User extends BaseUser
{
    public function setUp()
    {
        parent::setUp();

        // ...

        $this->hasMany('Phonenumber as Phonenumbers', array(
            'local' => 'id',
            'foreign' => 'user_id'
        ));
    }
}

// models/Phonenumber.php
class Phonenumber extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('user_id', 'integer');
        $this->hasColumn('phonenumber', 'string', 50);
    }

    public function setUp()
    {
        $this->hasOne('User', array(
            'local' => 'user_id',
            'foreign' => 'id'
        ));
    }
}

# schema.yml
User:
  # ...
  relations:
    # ...
    Phonenumbers:
      type: many
      class: Phonenumber
      local: id
      foreign: user_id

Phonenumber:
  columns:
    user_id: integer
    phonenumber: string(50)
  relations:
    User:
      local: user_id
      foreign: id

// models/Task.php
class Task extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('name', 'string', 100);
        $this->hasColumn('parent_id', 'integer');
    }

    public function setUp()
    {
        $this->hasOne('Task as Parent', array(
            'local' => 'parent_id',
            'foreign' => 'id'
        ));
        $this->hasMany('Task as Subtasks', array(
            'local' => 'id',
            'foreign' => 'parent_id'
        ));
    }
}

# schema.yml
Task:
  columns:
    name: string(100)
    parent_id: integer
  relations:
    Parent:
      class: Task
      local: parent_id
      foreign: id
      foreignAlias: Subtasks

class User extends BaseUser
{
    public function setUp()
    {
        parent::setUp();

        // ...

        $this->hasMany('Group as Groups', array(
            'local' => 'user_id',
            'foreign' => 'group_id',
            'refClass' => 'UserGroup'
        ));
    }
}

User:
    # ...
    relations:
        # ...
        Groups:
            class: Group
            local: user_id
            foreign: group_id
            refClass: UserGroup

// models/Group.php
class Group extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->setTableName('groups');
        $this->hasColumn('name', 'string', 30);
    }

    public function setUp()
    {
        $this->hasMany('User as Users', array(
            'local' => 'group_id',
            'foreign' => 'user_id',
            'refClass' => 'UserGroup'
        ));
    }
}

# schema.yml
Group:
  tableName: groups
  columns:
    name: string(30)
  relations:
    Users:
      class: User
      local: group_id
      foreign: user_id
      refClass: UserGroup

$manager->setAttribute(Doctrine_Core::Doctrine_Core::ATTR_QUOTE_IDENTIFIER,
true);

// models/UserGroup.php
class UserGroup extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('user_id', 'integer', null, array(
            'primary' => true
        ));
        $this->hasColumn('group_id', 'integer', null, array(
            'primary' => true
        ));
    }
}

# schema.yml
UserGroup:
  columns:
    user_id:
      type: integer
      primary: true
    group_id:
      type: integer
      primary: true

// test.php
$user = new User();

// ...
$user->Groups[0]->name = 'First Group';
$user->Groups[1]->name = 'Second Group';

// ...
$user->save();

// ...
$user->UserGroup->delete();

$groups = new Doctrine_Collection(Doctrine_Core::getTable('Group'));

$groups[0]->name = 'Third Group';
$groups[1]->name = 'Fourth Group';

$user->Groups[2] = $groups[0]; // $user will now have 3 groups

$user->Groups = $groups; // $user will now have two groups 'Third Group' and 'Fourth Group'

$user->save();

// ...
print_r($user->toArray(true));

$ php test.php
Array
    (
        [id] => 1
        [is_active] => 1
        [is_super_admin] => 0
        [first_name] =>
        [last_name] =>
        [username] => default username
        [password] =>
        [type] =>
        [created_at] => 2009-01-20 16:48:57
        [updated_at] => 2009-01-20 16:48:57
        [Groups] => Array
            (
                [0] => Array
                    (
                        [id] => 3
                        [name] => Third Group
                    )
            [1] => Array
                (
                    [id] => 4
                    [name] => Fourth Group
                )
            )
        [UserGroup] => Array
            (
            )
    )

// models/User.php
class User extends BaseUser
{
    public function setUp()
    {
        parent::setUp();

        // ...

        $this->hasMany('User as Parents', array(
            'local'    => 'child_id',
            'foreign'  => 'parent_id',
            'refClass' => 'UserReference'
        ));

        $this->hasMany('User as Children', array(
            'local'    => 'parent_id',
            'foreign'  => 'child_id',
            'refClass' => 'UserReference'
        ));
    }
}

// models/UserReference.php
class UserReference extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('parent_id', 'integer', null, array(
            'primary' => true
        ));
        $this->hasColumn('child_id', 'integer', null, array(
            'primary' => true
        ));
    }
}

# schema.yml
User:
  # ...
  relations:
    # ...
    Parents:
      class: User
      local: child_id
      foreign: parent_id
      refClass: UserReference
      foreignAlias: Children

UserReference:
  columns:
    parent_id:
      type: integer
      primary: true
    child_id:
      type: integer
      primary: true

// models/User.php
class User extends BaseUser
{

    public function setUp()
    {
        parent::setUp();

        // ...

        $this->hasMany('User as Friends', array(
            'local'    => 'user1',
            'foreign'  => 'user2',
            'refClass' => 'FriendReference',
            'equal'    => true,
        ));
    }
}

// models/FriendReference.php
class FriendReference extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('user1', 'integer', null, array(
            'primary' => true
        ));
        $this->hasColumn('user2', 'integer', null, array(
            'primary' => true
        ));
    }
}

# schema.yml
User:
  # ...
  relations:
    # ...
    Friends:
      class: User
      local: user1
      foreign: user2
      refClass: FriendReference
      equal: true

FriendReference:
  columns:
    user1:
      type: integer
      primary: true
    user2:
      type: integer
      primary: true

// test.php
$daniels = new User();
$daniels->username = 'Jack Daniels';

$brandy = new User();
$brandy->username = 'John Brandy';

$koskenkorva = new User();
$koskenkorva->username = 'Mikko Koskenkorva';

$beer = new User();
$beer->username = 'Stefan Beer';

$daniels->Friends[0] = $brandy;

$koskenkorva->Friends[0] = $daniels;
$koskenkorva->Friends[1] = $brandy;
$koskenkorva->Friends[2] = $beer;

$conn->flush();

// ...
$beer->free();
unset($beer);
$user = Doctrine_Core::getTable('User')->findOneByUsername('Stefan Beer');

print_r($user->Friends->toArray());

$ php test.php
Array
    (
        [0] => Array
            (
                [id] => 4
                [is_active] => 1
                [is_super_admin] => 0
                [first_name] =>
                [last_name] =>
                [username] => Mikko Koskenkorva
                [password] =>
                [type] =>
                [created_at] => 2009-01-20 16:53:13
                [updated_at] => 2009-01-20 16:53:13
            )
    )

// models/Product.php
class Product extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('name', 'string');
        $this->hasColumn('price', 'decimal', 18);
        $this->hasColumn('discounted_price', 'decimal', 18);
    }

    public function setUp()
    {
        $this->hasMany('Order as Orders', array(
            'local' => 'id',
            'foreign' => 'product_id'
        ));
    }
}

# schema.yml
Product:
  columns:
    name:
      type: string
    price:
      type: decimal(18)
    discounted_price:
      type: decimal(18)
    relations:
      Orders:
        class: Order
        local: id
        foreign: product_id

// models/Order.php
class Order extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->setTableName('orders');
        $this->hasColumn('product_id', 'integer');
        $this->hasColumn('quantity', 'integer');
    }

    public function setUp()
    {
        $this->hasOne('Product', array(
            'local' => 'product_id',
            'foreign' => 'id'
        ));
    }
}

# schema.yml
Order:
  tableName: orders
  columns:
    product_id: integer
    quantity: integer
    relations:
      Product:
        local: product_id
        foreign: id

CREATE TABLE orders (
    id INTEGER PRIMARY KEY AUTO_INCREMENT,
    product_id INTEGER REFERENCES products (id),
    quantity INTEGER,
    INDEX product_id_idx (product_id)
)

// models/Order.php
class Order extends Doctrine_Record
{
    // ...

    public function setUp()
    {
        $this->hasOne('Product', array(
            'local' => 'product_id',
            'foreign' => 'id',
            'foreignKeyName' => 'product_id_fk'
        ));
    }
}

# schema.yml
Order:
    # ...
    relations:
        Product:
            local: product_id
            foreign: id
            foreignKeyName: product_id_fk

class Phonenumber extends Doctrine_Record
{
    // ...

    public function setUp()
    {
        parent::setUp();

        // ...

        $this->hasOne('User', array(
            'local' => 'user_id',
            'foreign' => 'id',
            'onDelete' => 'CASCADE'
        ));
    }
}

# schema.yml
Phonenumber:
    # ...
    relations:
        # ...
        User:
            local: user_id
            foreign: id
            onDelete: CASCADE

Indexes¶

class IndexTest extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('name', 'string');
        $this->index('myindex', array(
            'fields' => array('name')
        ));
    }
}

IndexTest:
  columns:
    name: string
  indexes:
    myindex:
      fields: [name]

class MultiColumnIndexTest extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('name', 'string');
        $this->hasColumn('code', 'string');

        $this->index('myindex', array(
            'fields' => array('name', 'code')
        ));
    }
}

MultiColumnIndexTest:
  columns:
    name: string
    code: string
  indexes:
    myindex:
      fields: [name, code]

class MultipleIndexTest extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('name', 'string');
        $this->hasColumn('code', 'string'); $this->hasColumn('age', 'integer');

        $this->index('myindex', array(
            'fields' => array('name', 'code')
        ));

        $this->index('ageindex', array(
            'fields' => array('age')
        ));
    }
}

MultipleIndexTest:
  columns:
    name: string
    code: string
    age: integer
  indexes:
    myindex:
      fields: [name, code]
    ageindex:
      fields: [age]

class MultipleIndexTest extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('name', 'string');
        $this->hasColumn('code', 'string');
        $this->hasColumn('age', 'integer');

        $this->index('myindex', array(
            'fields' => array(
                'name' => array(
                    'sorting' => 'ASC',
                    'length'  => 10),
                'code'
            ),
            'type' => 'unique',
        ));
    }
}

MultipleIndexTest:
  columns:
    name: string
    code: string
    age: integer
  indexes:
    myindex:
      fields:
        name:
          sorting: ASC
          length: 10
        code:
      type: unique

// models/Article.php
class Article extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('name', 'string', 255);
        $this->hasColumn('content', 'string');

        $this->option('type', 'MyISAM');

        $this->index('content', array(
            'fields' => array('content'),
            'type'   => 'fulltext'
        ));
    }
}

# schema.yml
Article:
  options:
    type: MyISAM
  columns:
    name: string(255)
    content: string
  indexes:
    content:
      fields: [content]
      type: fulltext

Checks¶

You can create any kind of CHECK constraints by using the :php:meth:`check` method of the :php:class:`Doctrine_Record`. In the last example we add constraint to ensure that price is always higher than the discounted price.

// models/Product.php
class Product extends Doctrine_Record
{
    public function setTableDefinition()
    {
        // ...
        $this->check('price > discounted_price');
    }

    // ...
}

Here is the same example in YAML format. You can read more about YAML in the YAML Schema Files chapter:

# schema.yml
Product:
  # ...
  checks:
    price_check: price > discounted_price

Generates (in pgsql):

CREATE TABLE product (
    id INTEGER,
    price NUMERIC,
    discounted_price NUMERIC,
    PRIMARY KEY(id),
    CHECK (price >= 0),
    CHECK (price <= 1000000),
    CHECK (price > discounted_price)
)

If the Doctrine validators are turned on the given definition would also ensure that when a record is being saved its price is always greater than zero.

If some of the prices of the saved products within a transaction is below zero, Doctrine throws Doctrine_Validator_Exception and automatically rolls back the transaction.

Table Options¶

Doctrine offers various table options. All table options can be set via the Doctrine_Record::option function.

For example if you are using MySQL and want to use INNODB tables it can be done as follows:

class MyInnoDbRecord extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('name', 'string');
        $this->option('type', 'INNODB');
    }
}