Apprendre à utiliser Doctrine
Last updated on Thursday, December 5, 2013
  • Moyen

Ce cours est visible gratuitement en ligne.

Got it!

Présentation et installation

Tout d'abord, nous allons voir ce qu'est Doctrine, puis nous l'installerons, pour pouvoir commencer à coder un peu, quand même. :p

Attention, je vous préviens, je ne serai pas aussi direct que dans le tuto de christophetd. Je passerai plus de temps à vous faire découvrir le fonctionnement interne de Doctrine.
Si vous voulez commencer à coder tout de suite, allez voir le sien, il est relativement bien fait pour commencer rapidement.
Si vous souhaitez en savoir un peu plus, et apprendre à bien utiliser Doctrine et pouvoir l'étendre et le personnaliser ensuite (behaviors, et tout ça ! ^^ ), restez ici. ;)

Doctrine, c'est quoi ?

Doctrine est un ORM, pour object-relational mapping, soit mapping objet-relationnel en français.

Attends, euh... c'est quoi un ORM ???

Un ORM, c'est en quelque sorte une interface entre votre base de données et vous. Il s'agit d'un ensemble de classes (ou « bibliothèques ») qui fonctionne de manière indépendante. Le but est de nous permettre d'accéder au contenu de la base de données avec un langage orienté objet (PHP en l'occurrence).

Pour comprendre concrètement comment Doctrine fonctionne, voyons un exemple. Imaginons que l'on possède une table contenant des articles, avec un titre, un contenu et une certaine catégorie. On pourra y accéder avec un objet Article en PHP :

<?php
$article = new Article();
$article->title     = 'Tutoriel Doctrine';
$article->content   = 'blablabla...';
$article->categorie = $monObjetCategorie;
$article->save();

Et voilà !
En quelques lignes, nous avons créé un objet article, l'avons rempli avec des données, et l'avons sauvegardé. Et c'est tout. Doctrine se charge tout seul d'insérer ces données dans les champs de notre table, on ne touche pas au code SQL.

Et c'est l'un des gros avantages d'un ORM : si vous déplacez votre projet sur un autre serveur, avec un autre SGBD, vous n'aurez pas à vous soucier des différences qu'il peut y avoir entre les langages. En effet, Doctrine repose sur PDO et supporte les mêmes drivers. Vous n'aurez pas non plus à écrire les classes (par exemple Categorie ou Article) vous-même, elles sont générées automatiquement. Ce qui ne veut pas dire qu'on ne pourra pas les personnaliser, bien au contraire.

Voici un schéma pour comprendre rapidement comment Doctrine s'articule :

Image utilisateur

Doctrine est constitué de deux couches distinctes :

  • Je vous l'ai dit, l'une repose sur PDO, à laquelle elle ajoute des fonctionnalités, c'est ce qui s'appelle la DBAL : Database Abstraction Layer. Elle pourrait s'utiliser directement, sans la couche ORM. Son but, comme son nom l'indique, est de fournir une couche d'abstraction, c'est-à-dire que grâce à elle, on ne se soucie plus de comment fonctionne notre base de données. À ce niveau-là, on n'utilise pas encore de langage-objet.

  • La deuxième couche (ORM, donc) permet de faire le « lien » entre nos objets PHP et la DBAL, c'est ce qui nous fournit une interface orientée objet pour manipuler la base de données. Elle interagit avec la DBAL et nous retourne des résultats sous forme d'objets.

Ne faites pas de confusion avec PDO : j'ai parlé d'abstraction dans le schéma, mais PDO ne propose pas d'abstraction de la base de données. Elle fournit simplement des fonctions communes, peu importe le SGBD, mais il faut quand même se plier au langage « local ».

Bon assez bavardé, je suppose que vous êtes tous impatients de l'installer ! Comment ça, non ? :p

Installation

Téléchargement

Ici, je vais seulement vous montrer la manière la plus simple et accessible à tout le monde pour installer Doctrine.

Commencez par télécharger le package .tgz ici : http://www.doctrine-project.org/projects/orm/download. La dernière version stable à l'heure où j'écris ces lignes est la 1.2.2. Pour extraire l'archive, utilisez un logiciel comme 7zip ou Winrar.

À la racine de votre projet, créez un répertoire ~/lib/. Nous placerons ici toutes nos classes. Nos classes de modèles seront placées dans ~/lib/models/.

Placez le contenu du dossier <Archive>/Doctrine-1.2.2/lib/ que vous venez de télécharger, dans ~/lib/vendor/doctrine/ (que vous créez pour l'occasion ;) ).

Profitons-en pour créer aussi un répertoire ~/web/ à la racine. Tous les fichiers destinés à être vus par le visiteur seront placés ici.
J'insiste sur le fait que la racine Web est ~/web/. C'est une bonne habitude à prendre de ne pas laisser vos sources librement accessibles. Ne mettez dans ce dossier Web que le strict nécessaire, notamment vos images, feuilles de style, javascript, etc.

Implémentation dans notre projet

Doctrine peut inclure les fichiers contenant nos classes automatiquement, nous n'aurons pas à faire d'include() ou require() manuellement.
Pour cela, il va falloir ajouter quelques lignes de configuration à votre projet. Créez un fichier ~/config/global.php.

Tout d'abord, définissons quelques constantes et incluons la classe de base de Doctrine :

<?php 
// Adaptez bien sûr le DSN à votre cas
define('CFG_DB_DSN', 'mysql://root@localhost/db_doctrine_test');

define('LIB_DIR',  dirname(__FILE__).'/../lib/');
define('CFG_DIR',  dirname(__FILE__).'/');
define('WEB_DIR',  dirname(__FILE__).'/../web/');
define('HTML_DIR', dirname(__FILE__).'/../html/');

require_once(LIB_DIR.'vendor/doctrine/Doctrine.php');
spl_autoload_register(array('Doctrine_Core', 'autoload'));

Concernant la base de données, il est préférable (et je vous l'ordonne ! ^^ ) de dédier complètement une base de données à Doctrine. Cela permettra de laisser Doctrine s'occuper de toute la configuration. Si vous ne lui dédiez pas de base de données, il pourrait y avoir des interactions non désirées avec vos autres projets.

Nous enregistrons aussi l'autoloader de Doctrine avec spl_autoload_register(). C'est celui-ci qui va s'occuper d'inclure les fichiers contenant les classes pour nous.

Waaaa, c'est génial ! Comment ça marche ?

En fait, c'est assez simple. Pour commencer, l'autoloader (Doctrine_Core::autoload()) sera appelé par PHP à chaque fois qu'une classe non définie sera utilisée, avec en paramètre le nom de cette classe. C'est à cette fonction de se débrouiller ensuite pour faire les include() ou require() nécessaires.

Pour trouver où sont rangés ces fichiers, une convention de Doctrine est que le nom des classes indique aussi où elles sont situées : il suffit de remplacer les _ par des / et on obtient le chemin du fichier (relatif par rapport au dossier contenant Doctrine). Par exemple, la classe Doctrine_Record_Abstract est située dans ~/lib/vendor/doctrine/Doctrine/Record/Abstract.php. À noter que Doctrine ne nomme pas les fichiers contenant des classes avec l'extension .class.php.

Cependant, il y a une exception pour les fichiers contenant nos modèles, et Doctrine les inclura toujours (~/lib/models/).

Avant de conclure, je vais faire un petit point sur l'organisation du projet que nous allons utiliser pour suivre ce tutoriel.
Je vous ai brièvement parlé de MVC en introduction. Cependant, pour ce tutoriel, il ne sera pas toujours nécessaire de le respecter, et pour ne pas compliquer la compréhension de ceux qui ne connaissent pas cette architecture, il m'arrivera parfois de ne pas suivre le pattern MVC à la lettre.
Je vous conseille la lecture de l'un des tutoriels présents sur ce site, par exemple celui de Savageman, si voulez en savoir plus sur le sujet.
Vous êtes bien sûr libres d'intégrer directement à votre projet les exemples que je vous donnerai. ;)

Avant d'entrer dans le vif du sujet, créez le fichier ~/web/index.php et placez-y les lignes suivantes pour vérifier que Doctrine est bien installé :

<?php
require_once(dirname(__FILE__).'/../config/global.php');

echo Doctrine_Core::getPath();

Si le chemin vers Doctrine s'affiche, c'est bon. ;) Sinon, reprenez depuis le début, mais il ne devrait pas y avoir de problème à ce stade-là.

Voilà voilà, le projet est maintenant opérationnel. Dans la partie suivante nous allons pouvoir nous connecter à la base de données. :)

Example of certificate of achievement
Example of certificate of achievement