> Le Site du Zéro - Informatique

> Cours

> Tutoriels

> Site Web

> PHP

> Base de données (PHP)

> Apprendre à utiliser Doctrine

> Débuter avec Doctrine

> Présentation et installation

> Lecture du tutoriel

Présentation et installation

Par

Cybermanu

Mise à jour : 04/09/2010

Difficulté : Facile Facile

487 visites depuis 7 jours, dont 50 sur ce chapitre classé 233/786

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

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.

Retour en haut

Sommaire du chapitre :

Doctrine, c'est quoi ?
Installation

Retour en haut

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 ceux qui ont déjà entendu parler de Symfony, sachez que Doctrine est dorénavant l'ORM intégré par défaut.

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 :

Code : 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 :

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 ?

Retour en haut

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.

Si vous souhaitez l'installer via SVN ou PEAR, je vous renvoie à la documentation en ligne (in english). Mais nous ne nous attarderons pas là-dessus. Notez tout de même qu'il existe un tuto sur SVN sur le Site du Zéro.

À 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 :

Code : PHP - ~/config/global.php

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

Si vous êtes curieux et avez ouvert le fichier Doctrine.php, vous avez dû vous apercevoir que la classe Doctrine est vide ! En fait, elle hérite de Doctrine_Core. Je vous recommande d'utiliser Doctrine_Core par la suite, Doctrine.php étant là uniquement pour la rétro-compatibilité.

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é :

Code : PHP - ~/web/index.php

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

Rappelez-vous bien que le fichier global.php devra être inclus dans tous vos fichiers !

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

Retour en haut

Retour en haut

6 commentaires pour "Présentation et installation"

Note moyenne : 3.54 / 4 (35 votes)

Pseudo	Commentaire
canardman	# Posté le 02/03/2011 à 10:00:41
	Ce serais très bienvenue en effet
Playerz	# Posté le 28/03/2011 à 00:40:30
	+1 pour la maj Au cas où certains zéros auraient un message d'erreur avec le fichier yaml ==> Un début de soluce
stitox	# Posté le 16/01/2012 à 18:21:50
Études : ISTIA	Je viens de télécharger la version stable 2.0.7, la structure est différente à ce que tu es entrain de nous apprendre dans ton tutoriel, je pense que c'est l'heure de mettre ton tuto à jour, n'est ce pas ^^' Sinon Merci pour ce travaille fantastique Découpage PSD - Intégrateur Xhtml/Css.
wperle	# Posté le 13/02/2012 à 20:11:33
Avis : Décevant	J'ai bien suivi les étapes cité dessus mais il me sort l'erreur suivant : Warning: require_once(C:\wamp\www\aaa\config/../lib/vendor/doctrine/Doctrine.php) [function.require-once]: failed to open stream: No such file or directory in C:\wamp\www\aaa\config\global.php on line 10 Call Stack # Time Memory Function Location 1 0.2903 668776 {main}( ) ..\index.php:0 2 0.3865 678088 require_once( 'C:\wamp\www\aaa\config\global.php' ) ..\index.php:2 Fatal error: require_once() [function.require]: Failed opening required 'C:\wamp\www\aaa\config/../lib/vendor/doctrine/Doctrine.php' (include_path='.;c:\wamp\bin\php\php5.3.8\pear') in C:\wamp\www\aaa\config\global.php on line 10 Call Stack # Time Memory Function Location 1 0.2903 668776 {main}( ) ..\index.php:0 2 0.3865 678088 require_once( 'C:\wamp\www\aaa\config\global.php' ) Merci d'intervenir j'ai fouillé partout mais sans succès
ArRaXaS	# Posté le 27/04/2012 à 09:32:45
Avis : Très bon	Hello, Personnellement je ne comprend pas l'utilité de l'instruction suivante : Placez le contenu du dossier <Archive>/Doctrine-1.2.2/lib/ que vous venez de télécharger, dans ~/lib/vendor/doctrine/ Dans mon cas, j'ai plutôt fait ceci : Placez le contenu du dossier <Archive>/Doctrine-1.2.2/lib/ que vous venez de télécharger, dans ~/lib/ (que vous aurez créé pour l'occasion) L'arborescence est plus simple et cela fonctionne tout aussi bien :-) Du coup la ligne 10 du fichier global.php qui était : require_once(LIB_DIR.'vendor/doctrine/Doctrine.php'); est simplifiée aussi en : require_once(LIB_DIR.'Doctrine.php'); PS : j'ai passé la journée d'hier à essayer d'installer la version 2.2 sous windows mais apparemment c'est bonbon --> Je vais d'abord finir le tuto sur la version conseillée et puis j'y reviendrai si j'ai le courage ! Très bon tutoriel en tout cas ! Bonne journée,