Managing Persistent Data with Doctrine 2 PHP ORM
Under development for more than two years, the first stable release of Doctrine 2 was made available this past December. This release provides users of PHP's leading object-relational mapper with even more expansive capabilities for effectively managing data and relations using a convenient object-oriented interface.
I've been using Doctrine 2 in conjunction with the Zend Framework for several weeks now, and already wonder how I ever got along without it. In this article I'll introduce you to Doctrine 2, helping you to get familiar with some of the key features at your disposal when using this incredibly powerful persistence solution.
By the way, Doctrine 2 takes advantage of several features available only to PHP 5.3, meaning you'll need to upgrade to at least PHP 5.3.0 before continuing with this tutorial.
Installing the Doctrine 2 PHP ORM
Doctrine 2 can be installed in a variety of ways. The easiest in terms of experimenting with the solution is by cloning the project's GitHub repository. Create a directory somewhere within your Web server's document root, enter the directory, and execute the following command:
$ git clone git://github.com/doctrine/doctrine2.git
$ git submodule init
$ git submodule update
Included in the release is a sample project, which we'll use to get acquainted with Doctrine.
Experimenting with the Doctrine 2 Sandbox Project
A simple sample project called
sandbox is stored in the
doctrine2/tools/sandbox directory. This project is intended for you to familiarize yourself with key Doctrine concepts without having to spend a lot of time getting mired in configuration details. Navigate to the
sandbox directory and among other files you'll find an executable named
doctrine. This is the Doctrine command-line console, which you can use to execute a variety of useful tasks. Display the command menu by executing the command from your terminal window:
Doctrine Command Line Interface version 2.1.0-DEV
Defining Persistent Classes in the Doctrine 2 PHP ORM
One of Doctrine's great attributes is the flexibility it provides developers in terms of defining persistent classes. You can choose to manage your class declarations using XML, YAML, or DocBlock annotations. The sandbox project provides you with examples of all three approaches. You'll find sample declarations in the
Entities directories, respectively. I prefer using the DocBlock annotations because of the added convenience of managing your domain class and persistence definitions together.
To see an example of a class that has been annotated, open the
/** @Entity @Table(name="users") */
* @Id @Column(type="integer")
/** @Column(type="string", length=50) */
* @OneToOne(targetEntity="Address", inversedBy="user")
* @JoinColumn(name="address_id", referencedColumnName="id")
public function getId()
public function getName()
These annotations are prefixed with the
@ symbol, and each plays a role in terms of determining how the class is persisted. The most important annotation is
@Entity, which tells Doctrine that this class should be persisted in the first place. The
@Table annotation defines the database table, which should be mapped to this class. Within the class you'll find a series of datatype- and association-specific annotations, which collectively determine how the associated table should be defined and how it relates to other tables in the database. Once defined, these annotations can be used to generate the table schemas.