The text in this book contains lots of PHP code examples. All starting and ending PHP tags have been removed to reduce the length of the book. Be sure to include the PHP tags when you copy and paste the examples.

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.

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.

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.

Pulled from Wikipedia:

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.

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.

If you use a 3 in 1 package under windows like Uniform Server, MAMP or any other non-official package, you may be required to perform additional configurations.

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.

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 Meta Data Mapping patterns.

Through extending a specific base class named 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 Doctrine_Table class. This class has the typical Data Mapper interface, createQuery(), find(id), findAll(), findBy*(), 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 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).

(1) Note that complexity != size. A domain model can be pretty large without being complex and vice versa. Obviously, larger domain models have a greater probability of being complex.

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".

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 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.).

DQL expresses a query in the terms of your domain model (your classes, the attributes they have, the relations they have to other classes, etc.).

It's very important that we speak about classes, fields and associations between classes here. User is not a table / table name . It may be that the name of the database table that the User class is mapped to is indeed named 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 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 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.

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 Domain 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).

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.

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 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.

You can also check your PHP installation has the necessary requirements by running some commands from the terminal. We will demonstrate in the next example.

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

Checking the requirements are required in order to run the examples used throughout this documentation.

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.

If you wish to just try out Doctrine in under 5 minutes, the sandbox package is recommended. We will discuss the sandbox package in the next section.

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

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.

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.

The DSN consists in the following parts:

List of options

The DSN can either be provided as an associative array or as a string. The string format of the supplied DSN is in its fullest form:

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

Most variations are allowed:

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

The currently supported PDO database drivers are:

A second DSN format supported is

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

If your database, option values, username or password contain characters used to delineate DSN parts, you can escape them via URI hex encodings:

Please note, that some features may be not supported by all database drivers.

Opening a new database connection in Doctrine is very easy. If you wish to use PDO you can just initialize a new 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);

Directly passing a PDO instance to Doctrine_Manager::connection() will not allow Doctrine to be aware of the username and password for the connection, since their is no way to retrieve it from an existing PDO instance. The username and password is required in order for Doctrine to be able to create and drop databases. To get around this you can manually set the username and password option directly on the $conn object.

// bootstrap.php

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

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

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.0/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
        )

)

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.

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 Doctrine::FETCH_BATCH and then sets a table fetchmode to Doctrine::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::ATTR_VALIDATE, Doctrine::VALIDATE_ALL);

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

// bootstrap.php

// ...
$conn->setAttribute(Doctrine::ATTR_VALIDATE, Doctrine::VALIDATE_NONE);

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

// bootstrap.php

// ...
$table = Doctrine::getTable('User');

$table->setAttribute(Doctrine::ATTR_VALIDATE, Doctrine::VALIDATE_ALL);

We haven't introduced the above used Doctrine::getTable() method. You will learn more about the table objects used in Doctrine in the Table section of the next chapter.

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.

You can read more about the bitwise operators on the PHP website.

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

Just because you CAN use delimited identifiers, it doesn't mean you SHOULD use them. In general, they end up causing way more problems than they solve. Anyway, it may be necessary when you have a reserved word as a field name (in this case, we suggest you to change it, if you can).

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 Doctrine::ATTR_QUOTE_IDENTIFIER option, all of the field identifiers will be automatically quoted in the resulting SQL statements:

// bootstrap.php

// ...
$conn->setAttribute(Doctrine::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'

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::ATTR_EXPORT, Doctrine::EXPORT_NONE);

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

// bootstrap.php

// ...
$manager->setAttribute(Doctrine::ATTR_EXPORT, Doctrine::EXPORT_TABLES);

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

// bootstrap.php

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

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

// bootstrap.php

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

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.

You can optionally specify attribute names and values as strings. Below is an example. This is allowed as a convenience to shorten the syntax and make it easier to type.

// bootstrap.php

// ...
$conn->setAttribute('validate', 'none');

Internally when strings are used they are converted to the constants and used.

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.0/lib/Doctrine.php');
spl_autoload_register(array('Doctrine', 'autoload'));
$manager = Doctrine_Manager::getInstance();

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

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

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

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.

Doctrine_Manager provides the static method 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');

If you use the 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';
}

The current connection is the last opened connection. In the next example we will show how you can get the current connection from the 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!';
}

You can change the current connection by calling Doctrine_Manager::setCurrentConnection().

// test.php

// ...
$manager->setCurrentConnection('connection 1');

echo $manager->getCurrentConnection()->getName(); // connection 1

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

The IteratorAggregate is a special PHP interface for implementing iterators in to your objects.

// test.php

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

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

// test.php

// ...
$conn = Doctrine_Manager::connection();

$name = $manager->getConnectionName($conn);

echo $name; // connection 1

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

You can retrieve an array of all the registered connections by using the Doctrine_Manager::getConnections() method like below:

// test.php

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

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

// test.php

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

You can easily get the number of connections from a 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();

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 Doctrine_Manager or Doctrine_Connection classes.

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

// test.php

// ...
$manager->createDatabases();

$manager->dropDatabases();

Drop/create database for specific connection

You can easily drop or create the database for a specific Doctrine_Connection instance by calling the dropDatabase()/createDatabase() function on the connection instance with the following code:

// test.php

// ...
$conn->createDatabase();

$conn->dropDatabase();

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.

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');
    }
}

We aren't actually going to use the above class definition, it is only meant to be an example. We will generate our first class definition from an existing database table later in this chapter.

Each Doctrine_Record child class can have a setTableDefinition() and setUp() method. The setTableDefinition() method is for defining columns, indexes and other information about the schema of tables. The setUp() method is for attaching behaviors and defining relationships between 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.

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

Generating from existing databases is only meant to be a convenience for getting started. After you generate from the database you will have to tweak it and clean things up as needed.