Development

Documentation/fr_FR/book/1.0/03-Running-Symfony

You must first sign up to be able to contribute.

Cette partie de la documentation est en cours de traduction. Cela signifie qu'elle est traduite de manière soit incomplète, soit inexacte. En attendant que cette traduction soit terminée, vous pouvez consulter la version en anglais pour des informations plus fiables.

Chapitre 3 – Installer Symfony

Comme vous l’avez appris au chapitre précédent, ce framework est un ensemble de fichiers écrits en PHP. Installer Symfony consiste donc à installer ces fichiers et à les rendre accessibles à tout projet s’appuyant sur cette technologie.

En tant que framework PHP 5, Symfony nécessite PHP 5. Assurez-vous qu’il est installé en tapant une commande sur la ligne de commande :

> php -v

PHP 5.2.0 (cli) (built: Nov 2 2006 11:57:36)
Copyright (c) 1997-2006 The PHP Group
Zend Engine v2.2.0, Copyright (c) 1998-2006 Zend Technologies

Si la version est 5.0 ou supérieure, vous pouvez procéder à l’installation comme décrit dans ce chapitre.

Installer le bac à sable

Si vous voulez simplement savoir de quoi Symfony est capable, vous préférerez sûrement une installation rapide. Dans ce cas, vous aurez besoin du bac à sable.(sandbox)

Le bac à sable est un simple répertoire de fichiers. Il contient un projet Symfony vide incluant toutes les bibliothèques nécessaires ( symfony, pake, lime, Creole, Propel, Phing), une application par défaut et une configuration standard. Il est pleinement opérationnel comme cela, sans configuration particulière ni paquets supplémentaires.

Pour l’installer, téléchargez l’archive à partir de http://www.symfony-project.com/get/sf_sandbox.tgz. L’extraire dans le répertoire racine de votre serveur (communément web/ou www/) Dans un souci de compréhension, nous conviendrons que vous l’avez extrait dans le répertoire sf_sandbox

CAUTION Que tous les fichiers soient à la racine de votre serveur de développement est confortable pour vos tests en local, mais dangereux s’il s’agit d’un serveur de production. Cela rend le cœur de votre application accessible aux utilisateurs.

Testez votre installation en utilisant le CLI (interface en ligne de commande) de Symfony. `Sur un système *nix et à partir du répertoire sf_sandbox, entrez la commande suivante :

> ./symfony -V

Sur Windows, utilisez cette commande :

> symfony -V

Vous devriez alors voir la version du bac à sable : symfony version 1.0.0

Maintenant assurez-vous que votre navigateur peut afficher le bac à sable en accédant à l’URL suivante :

http://localhost/sf_sandbox/web/frontend_dev.php/

Vous devriez maintenant voir une page de félicitations ressemblant à l’illustration 3-1. Cela signifie que votre installation s’est terminée avec succès. Si tel n’est pas le cas, un message vous indiquera la marche à suivre afin de régler votre problème. Vous pouvez aussi vous référer à la section "Troubleshooting" plus loin dans ce chapitre.

Illustration 3-1 – La page de félicitations du bac à sable.

Sandbox congratulations page

Le bac à sable est prévu pour que vous vous entraîniez à Symfony en local et non pour développer des applications destinées à être publiées sur le web. Cependant, la version de Symfony intégrée au bac à sable est entièrement fonctionnelle et est équivalente à une version installée via PEAR.

Pour désinstaller le bac à sable il vous suffit de supprimer le répertoire sf_sandbox.

Installer les librairies de Symfony

Lorsque vous développerez une application, vous souhaiterez probablement installer Symfony deux fois : une fois sur votre serveur de développement et une seconde fois sur votre serveur de production (à moins que ce dernier possède déjà Symfony). Pour chaque serveur vous souhaiterez sûrement éviter la duplication en maintenant tous les fichiers dans un emplacement unique, et cela que vous développiez une seule ou plusieurs applications.

Etant donné que Symfony évolue vite, vous pourriez être concerné par la publication d’une nouvelle version stable. Vous devez considérer la mise à jour du framework comme une priorité. Voilà donc une autre raison pour ne partager qu’un seul exemplaire de vos répertoires Symfony entre tous vos projets.

Lorsque vous devez installer Symfony pour un véritable développement, deux possibilités s’offrent à vous :

  • L’installation via PEAR est recommandée pour la plupart des utilisateurs. Elle peut être facilement partagée et mise à jour. De plus, ce processus d’installation est rodé.
  • L’installation via Subversion (SVN) n’est censée être utilisée que par des développeurs PHP confirmés qui souhaiteraient tirer avantage des derniers patchs, ajouter leur propre code spécifique et/ou contribuer au projet Symfony.

Symfony intègre quelques autres paquets :

  • pake est un utilitaire CLI
  • lime est un utilitaire de tests unitaires
  • Creole est une couche d’abstraction de données. A l’instar de PHP Data Objects (PDO), il fournit une interface entre votre code et le code SQL. Il permet de changer d’outil d’interrogation de base de données.
  • Propel sert au mapping objet relationnel (ORM). Il fournit la persistance de données et un service d’interrogation.
  • Phing est une CLI pour Propel.

Pake et lime ont été développés par l’équipe de Symfony. Creole, Propel et Phing ont été développés par d’autres équipes et sont livrés sous la licence GNU/LGPL (Lesser Public General License). Tous ces paquets sont inclus dans Symfony.

Installer Symfony via PEAR

Le paquet Symfony de PEAR contient les librairies de Symfony et leurs dépendances. Il contient aussi un script qui modifie le CLI pour y intégrer la commande symfony

La première étape de l’installation est l’ajout du canal PEAR, comme suit :

> pear channel-discover pear.symfony-project.com

Pour voir toutes les librairies disponibles sur ce canal, entrez ce qui suit :

> pear remote-list -c symfony

Vous êtes maintenant prêt à installer la dernière version stable de Symfony. Tapez la commande suivante :

> pear install symfony/symfony

downloading symfony-1.0.0.tgz ...
Starting to download symfony-1.0.0.tgz (1,283,270 bytes)
.................................................................
.................................................................
.............done: 1,283,270 bytes
install ok: channel://pear.symfony-project.com/symfony-1.0.0

Voilà, CLI et les fichiers Symfony sont installés. Vérifiez le succès de l’installation en récupérant la version du produit via la nouvelle commande symfony :

> symfony -V

symfony version 1.0.0

TIP Si vous préférez installer la dernière version beta, comportant les dernières évolutions et les derniers fixes, saisissez pear install symfony/symfony-beta. Les verions beta plus instables et non recommandées pour des environnements de production.

Les librairies Symfony sont maintenant installées dans les répertoires suivants :

  • $php_dir/symfony/ contient les librairies principales
  • $data_dir/symfony/ contient le squelette des applications Symfony : modules de bases, configuration, base d’internationalisation (i18n) etc … * $doc_dir/symfony/ contient la documentation
  • $test_dir/symfony/ contient les tests unitaires.

Les variables _dir sont visibles dans la configuration PEAR. Pour connaitre leurs valeurs , tapez la commande suivante.

> pear config-show

Récupérer Symfony par le dépôt SVN

Dans le cas de serveur de production, ou si PEAR n’est pas une option, vous pouvez télécharger la dernière version des librairies Symfony directement à partir du dépôt Subversion de Symfony en effectuant un checkout:

> mkdir /path/to/symfony
> cd /path/to/symfony
> svn checkout http://svn.symfony-project.com/tags/RELEASE_1_0_0/ .

La commande symfony, uniquement disponible pour des installations via PEAR, est appelée à partir du script /chemin/vers/symfony/data/bin/symfony. Par conséquent la commande suivante est équivalente à symfony –V pour une installation via SVN :

> php /chemin/vers/symfony/data/bin/symfony -V

symfony version 1.0.0

Si vous optez pour une installation SVN, vous possédez peut-être déjà un projet Symfony. Pour que ce projet se serve des dossiers Symfony, vous devez modifier les deux variables définies dans le dossier de des config dude votre projet/config.php, comme suit :

[php]
<?php

$sf_symfony_lib_dir  = '/chemin/vers/symfony/lib/';
$sf_symfony_data_dir = '/chemin/vers/symfony/data/';

Le chapitre 19 propse d’autres façon de rattacher un projet à une installation Symfony (incluant les liens symboliques et les chemins relatifs).

TIP Vous pouvez aussi télécharger le paquet PEAR (http://pear.symfony-project.com/get/symfony-1.0.0.tgz) et l’extraire ailleurs. Le résultat sera alors le même qu’avec un checkout.

Installer une application

Comme vous l’avez appris au chapitre 2, un projet Symfony est composé de n applications. Toutes les applications d’un projet partagent la même base de données. Dans l’optique de créer une application, vous devez d’abord créer un projet

Créer un projet

Chaque projet Symfony respecte une structure prédéfinie. La ligne de commande Symfony automatise la création de nouveaux projets en créant le squelette du projet, sa propre arborescence et ses propres droits d’accès.

Pour une installation PEAR, tapez la commande suivant :

> mkdir ~/myproject
> cd ~/myproject
> symfony init-project myproject

Pour une installation SVN, créer le projet avec cette commande :

> mkdir ~/myproject
> cd ~/myproject
> php /path/to/symfony/data/bin/symfony init-project myproject

La commande symfony doit toujours être lancée à partir de la racine du projet (myproject/dans le cas précédant) car toutes les opérations réalisées par cette commande sont relatives aux projets.

Symfony va créer l’arborescence suivante :

apps/
batch/
cache/
config/
data/
doc/
lib/
log/
plugins/
test/
web/

TIP L’ordre ìnit-project`ajoute un script symfonyà la racine du projet ayant le même effet que la commande symfonyinstallée par PEAR. Par conséquent, vous pouvez utiliser la syntaxe php symfonyà la place de symfonysi vous n’avez if you don't have native command-line support {pas accès à une ligne de commande native}

Créer une application

Le projet est presque accessible, il ne lui manque plus qu’au moins une application. Pour la créer, employez la commande ìnit-app avec le nom de l’application comme argument.

> symfony init-app myapp

Cela va créer un répertoire myapp/ dans le dossier apps/ du projet avec une configuration par défaut et un ensemble de répertoires prêts à recevoir votre site web.

apps/
  myapp/
    config/
    i18n/
    lib/
    modules/
    templates/

Certains fichiers PHP correspondant au contrôleur principal de chaque environnement sont aussi créés dans le répertoire web\ du projet.

web/
  index.php
  myapp_dev.php

index.php est le contrôleur principal d’une nouvelle application en production. Lorsque vous créer la première application de votre projet, Symfony crée un fichier appelé index.php au lieu de myapp.php (Si vous ajoutez une nouvelle application appelée mynewapp.php, le nouveau contrôleur principal en production s’intitulera mynewapp.php). Pour utiliser votre application via l’environnement de développement, appelé le contrôleur principal myapp_dev.php. Vous en apprendrez plus à propos de ces environnements au chapitre 5.

Configurer un serveur web

Les fichiers du répertoire web/ sont les points d’entrée de votre application. Vous devez correctement configurer le serveur web pour les rendre accessibles via internet. Sur votre serveur de développement, comme sur votre serveur de production vous avez sûrement accès à la configuration d’Apache. Vous pouvez donc configurer une hôte virtuel. Sur des serveurs mutualisés, vous devrez utiliser le fichier .htaccess.

Configurer un hôte virtuel

Le lsiting 3-1 est un exemple de configuration d’un hôte virtuel sous Apache dans le fichier httpd.conf

Listing 3-1 – Exemple de configuration Apache dans apache/conf/httpd.conf

<VirtualHost *:80>
  ServerName myapp.example.com
  DocumentRoot "/home/steve/myproject/web"
  DirectoryIndex index.php
  Alias /sf /$sf_symfony_data_dir/web/sf
  <Directory "/$sf_symfony_data_dir/web/sf">
    AllowOverride All
    Allow from All
  </Directory>
  <Directory "/home/steve/myproject/web">
    AllowOverride All
    Allow from All
  </Directory>
</VirtualHost>

L’emplacement du sf_symfony_data_dir du listing 3-1 doit être remplacé par le chemin réel. A titre d’exemple, pour une installation PEAR sous *nix, vous devriez avoir quelque chose comme :

    Alias /sf /usr/local/lib/php/data/symfony/web/sf

[{An alternative to this alias would be to create a symbolic link (symlink) or copy the /path/to/symfony/data/web/sf/ directory to myproject/web/sf/.}]

NOTE L’alias du répertoire web/sf/ n’est pas obligatoire. En effet, il ne fait que permettre à Apache de trouver les images, les feuilles de styles et les fichiers JavaScript nécessaires pour la barre de debug, le générateur d’administration, la page Symfony par défaut et le support Ajax. [{Une solution alternative à cet alias serait de créer un lien symbolique (symlink) ou copier la cible de chemin/vers/symfony/date/web/sf/ dans myproject/web/sf}]

Il ne vous reste plus qu’a redémarrer Apache. L’application nouvellement créée peut maintenant être consultée grâce à un navigateur standard à partir de l’URL :

http://localhost/myapp_dev.php/

Vous devriez alors voir la page de félicitations déjà aperçue à l’illustration 3-1.

SIDEBAR La réécriture d’URL (URL rewriting)

Symfony utilise la technique de réécriture d’URL afin d’afficher des URL parlantes, utilisables par les moteurs de recherche et cachant les informations techniques à l’utilisateur. Vous en apprendrez plus sur ce point, appelé le [{routing}], au chapitre 9.

Si votre version d’Apache n’est pas compilée avec le module mod_rewrite, vérifiez que le mod_rewriteDynamic Share Object (DSO) est installé et que les lignes suivantes existent dans votre fichier http.conf :

AddModule mod_rewrite.c LoadModule rewrite_module modules/mod_rewrite.so

Pour Internet Information Services (IIS), ìsapi/rewrite`doit être installé et activé/ Vérifiez la documentation Symfony pour plus de détails sur l’installation d’IIS.

Configurer un hébergement mutualisé

L’installation d’une application sur un hôte mutualisé est un peu plus rusée, étant donné qu’il possède souvent une structure de dossiers que vous ne pouvez pas modifier.

CAUTION

Développer et tester directement sur un serveur mutualisé n’est pas une bonne pratique, puisqu’elle rend l’application visible alors même qu’elle n’est pas terminée, révèle son fonctionnement interne et ouvre de grandes failles de sécurité. Une autre raison, est que les performances d’un serveur mutualisé ne sont pas suffisantes pour parcourir efficacement votre application en mode débug. Par conséquent, vous ne devriez pas débuter vos développements sur un serveur mutualisé mais plutôt créer votre application en local et ensuite la déployer sur votre serveur mutualisé. La chapitre 16 vous en dit plus à ce sujet.

Imaginons que vous utilisiez une hébergement mutualisé dont le dossier web est www/et non web/. Vous n’avez pas non plus accès au httpd.conf, mais uniquement au .htaccessdisponible dans le dossier web.

Dans un projet Symfony, tous les chemins d’accès aux répertoires sont paramétrables. La chapitre 19 vous en dira plus à ce propos mais dans l’intervalle, vous pouvez toujours renommer le répertoire web/ en www/ et permettre à l’application de prendre en compte ce changement en modifiant la configuration, comme indiqué dans le listing 3-2. Ces lignes doivent être ajoutées à la fin du fichier config.phpde l’application.

` Listing 3-2 – Modifier les paramètres par défaut de la structure des dossiers, dans apps/myapp/config/config.php

[php]
$sf_root_dir = sfConfig::get('sf_root_dir');
sfConfig::add(array(
  'sf_web_dir_name' => $sf_web_dir_name = 'www',
  'sf_web_dir'      => $sf_root_dir.DIRECTORY_SEPARATOR.$sf_web_dir_name,
  'sf_upload_dir'   => $sf_root_dir.DIRECTORY_SEPARATOR.$sf_web_dir_name.DIRECTORY_SEPARATOR.sfConfig::get('sf_upload_dir_name'),
));

La racine du projet contient un fichier .htaccess par défaut, comme indiqué au listing 3-3. Modifiez-le pour qu'il corresponde à votre configuration. Listing 3-3 - .htaccess par défaut, dans myproject/www/.htaccess

Options +FollowSymLinks +ExecCGI

<IfModule mod_rewrite.c>
  RewriteEngine On


  # On remplace tous les fichiers par .quelque chose
  RewriteCond %{REQUEST_URI} \..+$
  RewriteCond %{REQUEST_URI} !\.html$
  RewriteRule .* - [L]


  # on vérifie que la version.html est présente
  RewriteRule ^$ index.html [QSA]
  RewriteRule ^([^.]+)$ $1.html [QSA]
  RewriteCond %{REQUEST_FILENAME} !-f


  # non, donc on redirige le contrôleur principal      
  RewriteRule ^(.*)$ index.php [QSA,L]
</IfModule>


# erreur en provenance du contrôleur principal
ErrorDocument 500 "<h2>Application error</h2>symfony application failed to start properly"

Vous devriez maintenant être capable d'accéder à votre application. Vérifiez si vous obtenez la page de félicitations en accédant à cette URL :

http://www.example.com/myapp_dev.php/

SIDEBAR

D'autres configurations serveur

Symfony est accessible via d'autres configurations serveurs. Vous pouvez, par exemple, utiliser un alias à la place d'un hôte viruel. Vous pouvez très bien faire tourner Symfony sur un serveur IIS. Il y a de nombreuses possibilités mais elles ne sont pas le sujet de ce livre.

Si vous souhaitez plus d'inforamtions sur ces diverses configurations, rendez-vous sur le wiki (http://www.symfony-project.com/trac/wiki). Il contient beauoup de tutoriels à ce sujet.

Problèmes

[{If you encounter problems during the installation, try to make the best out of the errors or exceptions thrown to the shell or to the browser. They are often self-explanatory and may even contain links to specific resources on the Web about your issue.}]

Problèmes courants

Si les problèmes persistent, vérifiez la liste des erreurs fréquentes suivantes :

  • Certaines installations de PHP acceptent à la fois les commandes du PHP4 et du PHP 5. Dans ce cas, il est préférable de préfixer tous les appels de commandes par php5 à la place de php. Par exemple préférez php5 symfony à symfony. Vous aurez peut-être aussi besoin d'ajouter la ligne SetEnv PHP_VER 5 au fichier .htaccess ou renommer tous les fichiers .php en php5. Une erreur renvoyée par une ligne de commande PHP 4 essayant d'accéder à Symfony ressemble à cela :

    Parse error, unexpected ',', expecting '(' in .../symfony.php on line 19.
    
  • Le limite mémoire, définie dans le php.ini doit être portée à au moins 16 Mo. Ce problème se manifeste le plus souvent par un message d’erreur au moment de ‘installation de Symfony via PEAR ou par la ligne de commande

    Allowed memory size of 8388608 bytes exhausted
    
  • Le paramètre zend.ze1_compatibility_mode doit être positionné à off dans le fichier php.ini. Si cela ne l’est pas, vous obtiendrez une erreur « implicit cloning » lorsque vous essaierez d’accéder à un script par un navigateur.

    Strict Standards: Implicit cloning object of class 'sfTimer' because of 'zend.ze1_compatibility_mode'
    
  • Les dossiers log et cache de votre projet doivent être définis avec des droits d’écriture. Si ce n’est pas le cas, une tentative d’accès à ces dossiers pourrait donner l’erreur suivante :

    sfCacheException [message] Unable to write cache file"/usr/myproject/cache/frontend/prod/config/config_config_handlers.yml.php"
    
  • La variable d’environnement PATH doit contenir le chemin d’accès vers le dossier des commandes PHP, php. De même et si vous utilisez PEAR, le fichier php.ini doit pointer vers le dossier PEAR/

  • Il peut arriver qu’il y ait plus d’un fichier `php.inidisponible sur un serveur (le cas du serveur WAMP). Faites un appel à la fonction |^hînfo()pour savoir l’exacte localisation du fichier php.ini utilisé par votre application.

NOTE Pour des raisons de performance , il est fortement recommandé de positionner les paramètres magic_quotes_gpc et register_globals à off dans votre fichier php.ini

Les ressources Symfony

Votre problème a déjà peut-être été identifié et la solution est déjà peut-être répertoriée par l’une des ressources suivantes :

Si vous ne trouvez pas votre réponse, essayez d’interroger les membres les plus actifs de la communauté Symfony via le forum, la liste de diffusion ou même le canal IRC #symfony.

Contrôle de version

Une fois l’installation terminée le lancement d’un contrôle de version est recommandé. Cela vous permet de garder les traces de toutes les modifications de code, vous donne accès aux précédentes mises à jour, facilite la mise en place de patchs, améliore le travail d’équipe. Bien que Symfony supporte CVS nous recommandons l’usage de Subversion (http://subversion.tigris.org/) En considérant que vous avez déjà installé un serveur Subversion et que vous souhaitez créer un nouveau dépôt pour votre projet, les exemples suivants vous montreront les commandes Subversion utiles .

D’autres clients Subversion existent, et les utilisateurs de Windows pourront utiliser TortoiseSVN (http://tortoisesvn.tigris.org/). Pour plus d’informations consulter la documentation Subversion

Pour les exemples suivants nous considérerons que $SVNREP_DIR est défini dans les variables d’environnement. Si ce n’est pas le cas, vous substituerez $SVNREP_DIR par le chemin réel vers le dossier dépôt.

Commençons par créer un nouveau dépôt pour le projet ‘ myproject` :

> svnadmin create $SVNREP_DIR/myproject

Ensuite, la structure de base du dépôt comprenant les dossiers trunk, tags, and branches sera créée grâce à cette commande plutôt longue :

> svn mkdir -m "layout creation" file:///$SVNREP_DIR/myproject/trunk file:///$SVNREP_DIR/myproject/tags file:///$SVNREP_DIR/myproject/branches

Ce sera votre première révision. Vous devez maintenant importer les fichiers de votre projet à l’exception de cache et log

> cd ~/myproject
> rm -rf cache/*
> rm -rf log/*
> svn import -m "initial import" . file:///$SVNREP_DIR/myproject/trunk

Vérifiez les fichiers précédemment traités grâce à la commande suivante :

> svn ls file:///$SVNREP_DIR/myproject/trunk/

Tout semble s’être correctement déroulé. Maintenant votre dépôt contient la version de référence (et l’historique) de tous les fichiers de votre projet. Ceci veut donc dire que tous les fichiers du dossier ~/myproject/doivent être liés au dépôt. Pour cela commencez par renommer le dossier myproject/ (nous l’effacerons plus tard si tout se passe bien) et effectuez un checkout du dépôt dans un nouveau dossier

> cd ~
> mv myproject myproject.origin
> svn co file:///$SVNREP_DIR/myproject/trunk myproject
> ls myproject

Voilà. Maintenant vous pouvez travailler sur les fichiers situés dans ~/myprojet/ et répercuter les modifications dans le dépôt. N’oubliez pas de supprimer le dossier myproject.origin/, maintenant inutile.

Il reste une chose à faire. Si vous reportez vos modifications vers le dépôt vous risquez de copier des éléments indésirables comme les dossierscacheetlog de votre projet. SVN vous permet de spécifier des éléments à ignorer au cours des opérations du contrôle de version. Vous avez aussi besoin d’ajuster les droits sur ces dossier :

> cd ~/myproject
> chmod 777 cache
> chmod 777 log
> svn propedit svn:ignore log
> svn propedit svn:ignore cache

L’éditeur de texte par défaut devrait alors démarrer. Si ce n’est pas le cas, vérifiez les associations des fichiers Subversion et de votre éditeur de texte en tapant la commande suivante : > export SVN_EDITOR= > svn propedit svn:ignore log > svn propedit svn:ignore cache

Maintenant vous n’avez plus qu’à ajouter les dossiers du projet que SVN doit ignorer.

*

Sauvegardez et quittez. Vous avez fini

Résumé

Pour tester et vous amuser avec Symfony en local, la meilleure des solutions est sans nul doute le bac à sable, qui contient une environement préconfiguré.

Pour de réels développements ou pour un serveur de production, préférez l’installation PEAR ou le contrôle de version. Cela installera les librairies Symfony et vous aurez toujours besoin d’initialiser un projet et une application. La dernière chose à faire est alors de configurer le serveur. Cela peut-être fait de plusieurs façon, mais nous vous recommandons d’utiliser la technique des hôtes virtuels.

Si vous rencontrez des problèmes au cours de l’installation, vous pourrez trouver la plupart des réponses grâce aux tutoriels disponibles sur le site de Symfony. Si nécessaire vous pourrez soumettre vos questions à la communauté via le forum, le channel irc ou les liste de diffusion. Vous aurez une réponse pertinente très rapidement.

Un fois votre projet initialisé, prenez la bonne habitude d’effectuer une contrôle de version

Maintenant que vous êtes prêt à utiliser Symfony, il est temps de voir comment construire une application web de base.