Doctrine est une couche ORM rapide et performante, basée sur le pattern ActiveRecord bien connu des adeptes de Ruby on Rails, pouvant être utilisée en lieu et place de Propel, l'ORM natif embarqué avec Symfony par défaut.

Installation

La mise en place de Doctrine se présente sous la forme d'un plugin, sfDoctrine, qui s'installe via un checkout Subversion dans le répertoire plugins de votre projet Symfony, comme suit :

$ cd /path/to/project/plugins
$ sudo apt-get install subversion
$ svn co http://svn.symfony-project.com/plugins/sfDoctrinePlugin sfDoctrinePlugin

Note: Si votre projet est déjà versionné dans un dépôt Subversion, vous pouvez faire un svn:externals vers le plugin :

$ propset svn:externals "symfony http://svn.symfony-project.com/plugins/sfDoctrinePlugin" /path/to/project/plugins

L'avantage est que desormais vos svn up mettront à jour les fichiers du plugin d'un même coup.

Ceci fait, il faut installer PDO et son driver MySQL via PECL sur votre système si ce n'est pas déjà le cas :

$ sudo apt-get install build-essential php5-dev php-pear libmysqlclient12-dev
$ sudo pecl install PDO PDO_MySQL

C'est un peu long, puisque compilé à la volée. Il ne faut pas oublier d'activer notre nouvelle extension et son driver dans nos fichiers différents php.ini :

$ sudo vi /etc/php5/apache2/php.ini /etc/php5/cli/php.ini

Et ajoutez en toute fin de fichiers les deux lignes suivantes :

extension=pdo.so
extension=pdo_mysql.so

Configuration

Maintenant, définissons nos paramètres de connexion pour le projet monprojet dans le fichier ./config/databases.yml du projet :

all:
  monprojet:
    class: sfDoctrineDatabase
    param:
      dsn: mysql://user:pass@localhost/mydb

Ensuite, on va tester une structure de données assez simpliste (au pif et pour faire original, un blog), pour vérifier que ça marche. On édite le fichier ./config/doctrine/monprojet.yml :

User:
  tableName:     users
  columns:
    name:        string(20)
    created_at:  timestamp
Article:
  tableName:     articles
  columns:
    title:       string(255)
    exerpt:      text
    description: text
    created_at:  timestamp
    user_id:
      foreignClass: User
      foreignName:  author
      localName:    article_author
      onDelete:     cascade
Comment:
  tableName:     comments
  columns:
    content:     text
    created_at:  timestamp
    user_id:
      foreignClass: User
      foreignName:  commenter
      localName:    comment_user
      onDelete:     cascade
    article_id :
      foreignClass: Article
      localName:    comment_article
      onDelete:     cascade

On peut maintenant générer les classes du modèle objet précedemment défini :

$ symfony doctrine-build-model

Ce qui nous donne :

>> loading   Class descriptions from "/home/...m/config/doctrine/monprojet.yml"
>> writing   BaseUser.class.php
>> writing   BaseArticle.class.php
>> writing   BaseComment.class.php

Ces fichiers ont été créés sous ./lib/model/doctrine automatiquement. Vous pourrez modifier les classes objets pour les adapter à vos besoin, mais attention, les classes de base situées dans le sous-répertoire generated seront systématiquement écrasées à chaque regénération.

Utilisation

Les commandes de scaffolding propres à Symfony et Propel ont été adaptées partiellement à Doctrine ; vous trouverez ainsi quelques tâches utiles :

doctrine-export            > exports doctrine schemas to propel schema.xml
doctrine-generate-crud     > Creates Doctrine CRUD Module
doctrine-import            > converts propel schema.*ml into doctrine schema
doctrine-init-admin        > initialize a new doctrine admin module

Pour aller plus loin

La syntaxe de requêtage et les autres aspects de Doctrine sont détaillés dans les ressources suivantes :