Commencer à développer avec le framework symfony

Il y a de nombreuses façons d'installer symfony, selon vos connaissances, votre plateforme… La plus simple reste l'utilisation de PEAR. Voici un ensemble de liens qui vous permettront d'installer symfony quelle que soit votre plateforme :

• Installer symfony sur Ubuntu Dapper Drake
• Installer symfony via PEAR
• Installer symfony sous MacOsX
• Installer symfony sur WAMP

Je vous propose également deux versions prêtes à l'emploi :

• Zazou Mini Web Server avec la symfony Sandbox (Windows) (ftp) (http de secours) ;
• une machine virtuelle (vmware) avec PHP, Perl, Python, MySQL et symfony (accessible via un partage réseau) (ftp) (http de secours).

La première version vous permettra de vous familiariser avec le framework, tandis que la seconde version vous permettra de tester et créer vos applications dans un environnement identique à la production.

Les détracteurs du langage PHP ont de nombreuses raisons de se plaindre : lenteur, permissivité, pas de séparation entre le code et le design, etc. symfony apporte de nombreuses réponses (que vous découvrirez tout au long de ce tutoriel ;-). Cependant, tout a un prix ! Certains développeurs PHP « traditionnels » peuvent être confrontés à des principes ou à l'utilisation d'outils auxquels ils ne sont pas habitués.

II-B-1. Vive la console !▲

II-B-2. Le design pattern MVC et l'objet▲

symfony est entièrement basé sur le design pattern MVC (Modèle-Vue - Contrôleur). Utilisé dans d'autres technologies (notamment Java), il n'a été largement diffusé dans le monde PHP qu'avec des frameworks tels que symfony. Le MVC est un pattern architectural qui sépare les données (c.-à-d. le modèle), l'interface homme-machine (la vue) et la logique de contrôle (le contrôleur).

Ce modèle de conception impose donc une séparation en trois couches : - Le modèle : il représente les données de l'application. Il définit aussi l'interaction avec la base de données et le traitement de ces données ; - La vue : elle représente l'interface utilisateur, ce avec quoi il interagit. Elle n'effectue aucun traitement, elle se contente simplement d'afficher les données que lui fournit le modèle. Il peut tout à fait y avoir plusieurs vues qui présentent les données d'un même modèle ; - Le contrôleur : il gère l'interface entre le modèle et le client. Il va interpréter la requête de ce dernier pour lui envoyer la vue correspondante. Il effectue la synchronisation entre le modèle et les vues. symfony implémente donc trois couches répondant à ce pattern. Le schéma ci-dessous illustre le mécanisme du MVC dans un projet symfony lorsque l'utilisateur navigue sur le site.

Pour une courte introduction à MVC, je vous conseille la lecture de la première partie du tutoriel de Baptiste Wicht (pour une introduction rapide), et la lecture du cours de Serge Tahé pour aller plus loin.

La programmation avec le framework symfony est clairement orientée objet. Cependant de nombreux développeurs PHP n'ont pas encore sauté le pas. Si vous êtes dans ce cas, il vous faudra donc passer par l'étape apprentissage de l'objet ! (Par exemple en consultant les tutoriels disponibles à ce sujet.) On peut maintenant entrer dans le vif du sujet : la création de votre premier projet !

symfony permet à partir d'un seul projet de gérer plusieurs applications, par exemple une pour le frontend et une autre pour le backend. Voici quelques précisions sur les différents niveaux d'un projet :

• Le projet : c'est la structure qui englobe tout. C'est à son niveau que l'on spécifie les informations sur la base de données ;
• L'application : elle correspond généralement à un site. C'est à ce niveau qu'il y a le plus de configurations à effectuer. Un projet peut comporter plusieurs applications, cependant, dans la plupart du cas, il n'y en aura qu'une ;
• Les modules : ce sont des « unités fonctionnelles » de votre application. (Par exemple : clients, produits, commandes.) C'est à ce niveau que vous allez travailler le plus !
• Les actions et les templates : les modules comportent des couples d'actions-templates. C'est l'application du pattern MVC, et également la séparation entre la partie « traitement » et la partie « affichage ». Toutes les opérations sur la base de données et les autres traitements (web services, ftp, mail, etc.) sont réalisés dans le fichier d'actions (monModule/actions/action.class.php), c'est ensuite le fichier de template (monModule/templates/monActionSuccess.php) qui se charge du rendu graphique.

Le schéma ci-dessous représente les différents niveaux d'un projet symfony (extrait de la conférence symfony-AFUP).

La création d'un nouveau projet passe par l'utilisation de la ligne de commande. Il vous faut créer un répertoire dans lequel placer votre projet. Vous pouvez le faire via l'interface graphique (selon votre serveur) ou via la ligne de commande :

mkdir monProjet
cd monProjet

Une fois que vous êtes bien dans le répertoire de votre projet, exécuter la commande de création d'un nouveau projet, en remplaçant monProjet par le nom de votre projet :

symfony init-project monProjet

Vous devez ensuite créer une application dans votre projet (vous pourrez par la suite refaire cette étape si vous souhaitez créer plusieurs applications au sein de votre projet). Là aussi, une simple ligne de commande suffit :

symfony init-app monProjet monAppli

Une nouvelle arborescence va être créé dans monProjet/apps/monAppli. Elle contient un ensemble de répertoires :

• Config : ce répertoire contient tous les fichiers de configuration propres à l'application (cache, routing, sécurité …) ;
• I18n : c'est ici que sont stockés les fichiers pour l'internationalisation (régionalisation) de votre projet, notamment les fichiers de traduction (généralement messages.fr.xml) ;
• Lib : ce dossier contient les bibliothèques personnelles que vous pouvez ajouter. Il contient également un fichier appelé myUser.class.php. Ce fichier ne doit pas être supprimé ni renommé (il dérive d'une classe User nécessaire au fonctionnement du site, y compris si votre site ne comporte pas de gestion d'utilisateurs !). Vous pouvez surcharger les méthodes afin de personnaliser la gestion des utilisateurs ;
• Modules : vide lors de la création de votre application, c'est lui qui contiendra tous les modules de votre application (notamment les fichiers d'actions et les templates) ;
• Template : contient le template dynamique par défaut (layout.php). C'est lui qui inclut tous les metas et le titre de la page. C'est également lui qui réalise l'inclusion du template de l'action en cours.

Il vous reste une dernière petite chose à effectuer avant de profiter de symfony. Vous devez créer un lien symbolique entre un répertoire de l'installation de symfony et votre projet, afin d'avoir les styles par défaut de symfony et l'accès à la barre web de débogage. Pour ce faire, vous devez effectuer la commande suivante (c'est un exemple pour la machine virtuelle, il vous faudra l'adapter à votre version de *nix et votre installation de symfony) :

ln -s /usr/share/php/data/symfony/web/sf ./web/sf

Vous pouvez maintenant passer à la configuration de votre projet !

La configuration s'effectue à plusieurs niveaux : le projet, l'application et les modules. On peut tout à fait définir une configuration globale à une application, mais surcharger la configuration d'un module particulier en changeant les informations de son fichier de configuration (les noms et le contenu sont identiques entre les fichiers de configuration d'une application et d'un module). Les fichiers de configuration pour une application sont situés dans monProjet/apps/monAppli/config. Les fichiers de configuration pour un module sont situés dans monProjet/apps/monAppli/modules/monModule/config. Il n'y a pas de documentation exhaustive sur ces fichiers de configuration. Cependant la plupart des informations utiles sont situées directement dans les fichiers de configuration, sous forme de commentaires.

Les fichiers de configuration de symfony sont quasiment tous au format YAML (extension .yml). Basé sur un fichier texte, ils présentent une syntaxe simple. Les différents niveaux hiérarchiques sont représentés par des espaces avant le texte.

prod:                     <- Niveau 1: la ligne se termine par un deux-points (:)
 .settings:             <- Niveau 2: la ligne commence par des espaces et se termine par un deux-points
  no_script_name: off     <- Paramètre: la valeur commence au premier caractère (espace non compté) après les deux points (:)
 
dev:                     <- Niveau 1
 error_reporting: 4095     <- Paramètre
  web_debug: on         <- Paramètre
  cache: off             <- Paramètre

Il y a de nombreux fichiers de configuration dans symfony. Voici la liste des principaux fichiers, ainsi que les points importants pour chacun des fichiers.

IV-C-1. config.php▲

IV-C-2. i18n.yml▲

IV-C-3. logging.yml▲

IV-C-4. routing.yml▲

# default rules
homepage:
url: /
param: { module: monModule, action: index }

IV-C-5. security.yml▲

read: # Début de la section pour la lecture (toutes actions)
is_secure: off # Positionné à off, tout le monde peut accéder à l'action en lecture
update: # Début de la section pour la modification
is_secure: on # Positionné à on, il faut être "connecté" pour activer la mise a jour
credentials: admin # Ici, il faut avoir le privilège 'admin' pour réaliser une maj
editArticle: # Début de la section pour l'action editArticle
credentials: admin # Il faut avoir le privilège 'admin' pour pouvoir exécuter l'action
editArticle
publishArticle: # Début de la section pour l'action publishArticle
credentials: publisher # Il faut avoir le privilège 'publisher' pour pouvoir exécuter l'action
publishArticle

IV-C-6. settings.yml▲

prod:
  .settings:
    web_debug:              off
    cache:                  on
 
dev:
  .settings:
    web_debug:              on
    cache:                  off
 
test:
  .settings:
    cache:                  on
    web_debug:              on

IV-C-7. view.yml▲

default:
  http_metas:
    content-type: text/html; charset=utf-8
 
  metas:
    title:        Bienvenue sur developpez.com
    robots:       index, follow
    description:  developpez.com le site no 1 des developpeurs
    keywords:     informatique, developpement, cours, tutoriel, programmation
    language:     fr
 
  stylesheets:    [main,develz]
 
  javascripts:    [jquery/src/jquery/jquery.js, libperso/popup.js]
 
  has_layout:     on
  layout:         layout

articleSuccess:
  metas:
    title: Article - Developpez.com
 
faqSuccess:
  metas:
    title: Foire aux questions - Developpez.com
  javascripts:     [qr.js]

Pour relier votre projet à une base de données, vous devez modifier certains fichiers de configuration.

V-A-1. properties.ini▲

[symfony]
name=monProjet

V-A-2. databases.yml▲

all:
monProjet:
class: sfPropelDatabase
param:
datasource: monProjet
phptype: mysql
hostspec: localhost
database: maBase
username: root
password: toor

V-A-3. Propel.ini▲

Propel.project = monProjet
Propel.database = mysql
Propel.database.createUrl = mysql://localhost/
Propel.database.url = mysql://locahost/monProjet_dev

Le fichier schema.yml contient une représentation du modèle relationnel de la base de données. Il est nécessaire pour pouvoir réaliser le mapping objet, ainsi que pour la génération de pages (CRUD et admin).

Créer le fichier▲

Avec un éditeur de texte▲

Le fichier schema.yml étant un fichier YAML, vous en connaissez déjà la syntaxe. Le niveau 1 correspond à une table et le niveau 2 à un champ. Le contenu du niveau 2 est entre accolades et il regroupe toutes les caractéristiques du champ (type, taille…). L'exemple ci-dessous vous explique comment structurer votre fichier pour une table.

Le fichier schema.yml peut être remplacé par un fichier au format XML (appelé schema.xml). Il est beaucoup plus compliqué d'éditer un tel fichier, cependant, vous pouvez utiliser le logiciel DbDesigner et convertir le fichier XML de ce logiciel en schema.xml sur ce site.

À partir d'une base de données existante▲

symfony offre également la possibilité de créer ce fichier (au format YAML ou XML) à partir d'une base de données existante. Il faut tout d'abord paramétrer la connexion à la base de données (fichier properties.ini, databases.yml et Propel.ini), puis exécuter la commande suivante :

Création du fichier schema au format YAML

Sélectionnez

symfony propel-build-model

Création du fichier schema au format XML

Sélectionnez

symfony propel-build-model xml

symfony sait maintenant comment est structurée votre base de données. Il faut maintenant faire la passerelle entre la base (relationnelle) et le php (en objet). C'est la génération du modèle. Cette étape va créer les classes correspondantes aux tables indiquées dans le fichier schema.yml. Les fichiers sont générés dans le répertoire monProjet/lib/model/om/. Cette génération est réalisée avec la ligne de commande suivante : symfony propel-build-model. Vous avez la possibilité de surcharger toutes les méthodes créées par symfony dans le fichier maTable.php situé dans monProjet/lib/model/om/. Il ne vous reste plus qu'à créer les tables dans votre base de données. Vous avez deux solutions pour cela, en ligne de commande : Créer un fichier SQL et l'exécuter vous-même :

symfony propel-build-sql

Laisser symfony se connecter à la base de données et créer les tables :

symfony propel-build-db

La création d'un module s'effectue en ligne de commande. Vous pouvez créer un module vierge (ce sera alors à vous de créer toutes les actions), ou bien de créer un module permettant d'effectuer les opérations de base sur une table.

VI-A-1. Création d'un module vierge▲

symfony init-module monProjet monModule

VI-A-2. Création d'un module CRUD▲

symfony propel-generate-crud monAppli monModule Maclasse

Lors de la création d'un module, un nouveau répertoire est créé dans /monProjet/apps/monAppli/modules. Il contient cinq dossiers :

• Actions : ce dossier contient le fichier actions.class.php. C'est lui qui contient toutes les méthodes-actions du module ;
• Config : il permet de surcharger la configuration de l'application (il est vide par défaut). La configuration est principalement surchargée pour la sécurité (security.yml) et pour l'affichage (view.yml) ;
• Lib : ce dossier permet d'insérer des classes personnalisées accessibles uniquement dans ce module ;
• Templates : contient tous les templates associés aux actions du module ;
• Validate : ce dossier contient les fichiers de configuration permettant la validation automatique des formulaires.

VI-B-1. Création d'une nouvelle action▲

public function executeNouveauclient()
{
…
}

Comme vous avez pu le remarquer, il existe un dossier templates dans votre module. Par défaut, lorsque l'action monAction est exécutée, c'est le fichier monActionSuccess.php dans ce dossier qui est appelé. Vous devez donc créer ce fichier dans le dossier templates. Vous avez également la possibilité de modifier le fichier template qui sera appelé dans le code de votre action. Cela vous permet de modifier dynamiquement le template qui sera appelé par une action donnée.

$this->setTemplate('monTemplate');

symfony offre également la possibilité de se passer de fichier template et de préparer la sortie directement dans le fichier actions. Cette méthode n'est pas conseillée et vous devez la réserver pour des cas bien spécifiques (comme le renvoi de JSON lors d'un appel ajax).

public function executeIndex()
{
    echo "<html><body>Bonjour à tous<body></html>";
    return sfView::NONE;
}
Ou
public function executeIndex()
{
    return $this->renderText("<html><body>Hello, World!</body></html>");
}

symfony utilise la réécriture d'URL. C'est pourquoi il ne faut pas faire les liens directement en HTML (en utilisant la balise <a link>). Les liens pointent vers une action (login) d'un module (utilisateur) :

<?php echo link_to("utilisateur/login") ?>

Pour passer des paramètres à la page appelée, vous pouvez utiliser la syntaxe habituelle :

<?php echo link_to("utilisateur/login?email=chris@bulles.org") ?>

Tous les résultats des traitements que vous réalisez dans votre fichier d'actions doivent être passés au fichier template pour être affichés. Il faut tout d'abord déclarer cette variable dans l'action. Cette variable doit être de la forme : $this->maVar Pour récupérer cette variable dans le template, il suffit de faire : $maVar. Ce « changement » de variables entre les actions et les templates peut être déroutant au début. Il est également valable pour « les objets de la base de données » :

$this->utilisateur = UtilisateurPeer ::doSelectOne($cr) ;

<p>Bienvenue <?php echo $utilisateur->getNom() ?>, c'est votre <?php echo $utilisateur->getNbConnexion() ?>eme connexion.</p>

symfony intègre un système complet de gestion des sessions et des utilisateurs. Voici les bases de cette gestion, de très nombreuses fonctionnalités ne sont pas abordées ici. La documentation vous permettra d'approfondir ces concepts.

VII-C-1. Gestion des attributs de la session▲

$this->getUser()->setAttribute('nbArticles', 15) ;
$this->getUser()->getAttribute('nbArticles') ;

$sf_user->setAttribute('nbArticles', 15) ;
$sf_user->getAttribute('nbArticles') ;

VII-C-2. Connexion de l'utilisateur▲

$this->getUser()->setAuthenticated(true) ; // Connecte
$this->getUser()->setAuthenticated(false) ; // Deconnecte
$this->getUser()->isAuthenticated() ; // Vrai si connecté

$sf_user->setAuthenticated(true) ; // Connecte
$sf_user->setAuthenticated(false) ; // Deconnecte
$sf_user->isAuthenticated() ; // Vrai si connecté

VII-C-3. Gestion des permissions▲

$this->getUser()->addCredential('auteur') ;

$this->getUser()->hasCredential('moderateur') ;

$this->getUser()->removeCredential('auteur') ;

$this->getUser()->clearCredentials() ;

Vous allez faire votre entrée dans le monde des helpers ! Les helpers sont des méthodes php qui génèrent du code Javascript. Elles permettent de générer du code propre, respectueux des standards et tout ceci simplement. Les helpers sont présents dans de nombreux domaines : Javascript, AJAX, Flash, formatage de données, régionalisation… et les formulaires ! La première étape pour créer un formulaire est de débuter par la balise <form>. Le code suivant va créer l'entête du formulaire

<?php echo form_tag('user/create')?>

Il faut ensuite créer tous les champs de votre formulaire. Il existe deux grands types d'helpers : les standards (commençant par input) et ceux reliés à la base de données (object helper - commençant par object). Il faut ensuite fermer vous-même le formulaire (en fermant la balise </form>).

VII-D-1. Les champs standards▲

// Champ de saisie (input)
<?php echo input_tag('nom', 'valeur par défaut') ?>
// Tous les helpers supportent des paramètres additionnels.
// Ils vous permettent de spécifier des attributs au code généré
<?php echo input_tag('nom', 'valeur par défaut', 'maxlength=20') ?>
// Champ texte multiligne (text area)
<?php echo textarea_tag('nom', ' valeur par défaut', 'size=10x20') ?>
// Case à cocher (Check box)
<?php echo checkbox_tag('coche moi', 1, true) ?>
// Sélecteur (Radio button)
<?php echo radiobutton_tag('status[]', 'value1', true) ?>
<?php echo radiobutton_tag('status[]', 'value2', false) ?>
// Liste déroulante (Combo)
<?php echo select_tag('paiement',
options_for_select(array('Visa', 'Eurocard', 'Mastercard')
)
?>
// Envoi de fichier
<?php echo input_file_tag('name') ?>
// Champ mot de passe
<?php echo input_password_tag('name', 'value') ?>
// Champ caché
<?php echo input_hidden_tag('name', 'value') ?>
// Bouton validation (texte)
<?php echo submit_tag('Save') ?>
// Bouton validation (image)
<?php echo submit_image_tag('submit_img') ?>

VII-D-2. Les champs en liaison avec la base de données▲

<?php echo object_input_tag($client, 'getTelephone') ?>

<?php echo object_input_tag($object, $method, $options) ?>
<?php echo object_input_date_tag($object, $method, $options) ?>
<?php echo object_input_hidden_tag($object, $method, $options) ?>
<?php echo object_textarea_tag($object, $method, $options) ?>
<?php echo object_checkbox_tag($object, $method, $options) ?>
<?php echo object_select_tag($object, $method, $options) ?>
<?php echo object_select_country_tag($object, $method, $options) ?>
<?php echo object_select_language_tag($object, $method, $options) ?>

VII-D-3. Les validations▲

methods:
 post: [nom, email, tel, adresse, cp, ville]
names:
 nom:
  required: true
  required_msg: Veuillez renseigner votre nom.
  validators: stringValidator
 email:
  required: true
  required_msg: L'adresse e-mail est requise.
  validators: emailValidator
 tel:
  required: true
  required_msg: Vous devez entrer un numéro detéléphone.
  validators: [phoneValidator, phoneLengthValidator]
 cp:
  required: true
  required_msg: Le code postal est requis.
  validators: [codeValidator, codeIntValidator]
 
stringValidator:
 class: sfStringValidator
  param:
   min: 3
   min_error: Le champ doit comporter au moins 3 caractères.
codeValidator:
 class: sfStringValidator
  param:
   min: 5
   min_error: Le code postal doit comporter au minimum 5 chiffres.

Tout d'abord, la documentation sur symfony est riche, voici les principaux points de repère :

• « The definitive guide to symfony », c'est le livre officiel sur ce framework. Vous pouvez l'acheter, ou le consulter gratuitement en ligne en anglais ou en français.
• La documentation de l'API, elle n'est pas facile à comprendre, mais elle permet de se plonger au cœur du framework.
• Le projet Askeet : l'idée est de créer un projet avec symfony en 24 jours (à une heure par jour). C'est un bon moyen de continuer l'apprentissage après ce tutoriel.

Si vous avez des questions, la communauté symfony vous aidera sûrement. Et n'oubliez pas le forum de developpez sur le sujet !