From Doctrine 1 to Doctrine 2

What you need to know

Doctrine 2 is an implementation of the Data Mapper pattern, and does not force your model classes to extend an Active Record, nor to contain details about the relational model like foreign keys.

Doctrine 2 is divided into three packages, each building on the previous one:

• Doctrine\Common contains reusable code like the annotation parser and the event system.
• Doctrine\DBAL asbtracts not only the particular database driver, like PDO already does natively, but also the SQL dialects of different DBMS.
• Doctrine\ORM maps your object graphs into database and vice versa. It is where the fun happens.

Note that you will have to run your application of PHP 5.3 for Doctrine 2 to work, mainly because of the use of namespaces in it.

Porting mapping information

In Doctrine 2, you'll need to maintain your PHP classes, instead of a mapping schema. These classes need to be annotated with @Entity and various other annotations to define which columns and relationships should be reflected in the database. This means private properties containing other objects or field values need to be eplicitly defined. You can take a look to the Doctrine\Tests namespace on github to see some examples of model definition along with metadata.

Thus, your Domain Model classes are managed by you, and you should maintain your object graph consistent. Then mapping information can be read by Doctrine 2 to port your objects into the database tables and reconstitute them when you execute query. Doctrine 2 is much more focused into mapping, instead of on shipping validation and behaviors as Doctrine 1 did.

Of course, the porting of Doctrine 1 metadata to Doctrine 2 ones can be automated with a script, contained in the Doctrine command line tools.

doctrine orm:convert-d1-schema

will transform your YAML schema into YAML mapping information for Doctrine 2. you'll still need to generate your PHP classes however, just for this first time.

I think the best approach to store mapping information is directly into class source code, with annotations that can be easily kept synchronized with the fields they refer to. While in other languages annotations require their classes to be present in order to compile, PHP applications define annotations as comments, which are ignored by anything else than Doctrine 2. There may be issues with APC and other optimizators that strip away comments, however.
You have now to configure your doctrine command line tool to load the metadata generated by the previous step, and then run:

doctrine orm:convert-mapping annotations /path/to/folder/where/generate/classes 

From now on, you'll maintain metadata only in the classes in that folder (after reconfiguration of Doctrine to read them instead of the YAML metadata). The generated classes will be empty, apart from annotated private properties, and you'll still have to insert the original public methods if you have any.

This mechanism port relationships as well as columns, but only the one explicitly defined (in the relations key). Autodiscovered relations like the ones inferred from field_id-like fields are not ported, but you'll still have the foreign key as a column. Doctrine 2 objects do not save foreign keys internally, so they will act as a placefolder that should be substituted with a relation annotation.

Your application code

Doctrine 2 has a cleaner architecture than its previous iteration, and it promotes Dependency Injection instead of accessing Doctrine_* classes statically or via a singleton like Doctrine_Manager.

Here's what to inject in substitution of your old Doctrine_*::*() calls:

• if you used Doctrine_Connection or Doctrine_Manager directly, now you should inject a Doctrine\ORM\EntityManager, which is the Facade of Doctrine 2. When you have a reference to the Entity Manager, you can access any functionality of Doctrine 2.
• If you referred to Doctrine_Record instances, you'll have to inject or instantiate your models, which do not extend any Doctrine base class.
• If you referred to a Doctrine_Table object (a single one), you can instead inject a Doctrine\ORM\EntityRepository, obtained with $em->getRepository($className).
• If you need to access the mapping metadata, to discover for example the type of a field, you have an entry point where each class metadata are available: $em->getMetadataFactory() will give you a Doctrine\ORM\Mapping\ClassMetadataFactory, which you can query for metadata of each class you know.
• If you need instead metadata only for a single class, you can obtain with $metadataFactory->getMetadataFor($className) a single Doctrine\ORM\Mapping\ClassMetadata, to inject into your own object.
• To perform queries, you can instance a Builder for queries with $this->em->createQueryBuilder($className). Until you have a QueryBuilder, it provides you with a fluent interface to add DQL parts; when you call getQuery() on it, it will return an immutable Query object which you can execute with several utility methods, like getSingleResult().

Is it worth the hassle?

Doctrine 2 is a new major version and it is indeed going to require some changes to your codebase that take more than an hour. However, its mapping power, well-though architecture and speed are worth the effort. If you want to do serious object-oriented programming in PHP, you will have to consider Doctrine 2 someday.