Blog Excilys » symfony

Menez le web à la baguette avec symfony (3) : refonte des glasses

Bastien JANSEN — Wed, 10 Feb 2010 11:00:40 +0000

L’habit fait le moine

Bienvenue dans le troisième épisode de la série “symfony, sex and fun”. Si vous arrivez en cours de route, vous pouvez consulter les articles précédents. Pour l’instant nous disposons d’un module bookmark fonctionnel (ajout, suppression etc.) mais qui n’est pas très joli. Voyons comment symfony permet de gérer les vues.

Note : à partir de maintenant, nous allons faire pas mal de modifications dans les fichiers. Je vous suggère de vous munir d’un bon éditeur PHP si vous souhaitez refaire la démarche chez vous. Pourquoi pas Netbeans et son très bon support de symfony, par exemple ?

L’affichage des vues dans symfony suit le design pattern decorator : chaque application dispose d’un layout global, dans lequel on va injecter le rendu du template de l’action appelée (il va venir le décorer). L’approche généralement utilisée dans d’autres projets suit le chemin inverse : on concatène un en-tête, puis le contenu, et enfin un pied de page, mais ni le header ni le footer ne représentent un document HTML valide.

Jetons un œil au layout (le template global), situé dans apps/frontend/templates/layout.php :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">



  

     include_http_metas() ?>

     include_metas() ?>

     include_title() ?>

    

     include_stylesheets() ?>

     include_javascripts() ?>

  

  

     echo $sf_content ?>

Plusieurs choses sont à noter :

par défaut, symfony fait du rendu HTML (logique, puisque généralement il est utilisé pour construire des applications web),
les balises d’en-tête (métadonnées, titre, feuilles de style, javascripts) sont spécifiées ailleurs, et incluses par des fonctions include_*() : les helper,
le contenu effectif de la page, issu du rendu du template des actions, est stocké dans une variable nommée $sf_content, définie par le framework.

Les helpers sont une notion empruntée à Ruby on Rails. Ce sont de simples fonctions, prenant éventuellement des paramètres, qui vont générer un morceau de vue HTML. Par exemple, le helper link_to va prendre une URL, un couple module/action ou encore une “adresse de routage” (comme @homepage) en paramètre et générer la balise correspondante. Pour des questions d’organisation logique, les helpers sont groupés dans des sortes de paquets, en fonction de ce sur quoi ils agissent. On retrouve ainsi les “paquets” UrlHelper, DateHelper, I18NHelper, etc. (par curiosité, vous pouvez les explorer dans la documentation de l’API symfony).

Note : avant de continuer, il faut que je vous parle de la manière dont les configurations sont gérées. Symfony dispose de plusieurs niveaux de configuration :

framework (configuration par défaut),
projet, dans le répertoire config/,
application, dans le répertoire apps//config,
module, dans le répertoire apps//modules//config.

Ces niveaux sont fusionnés du haut vers le bas, c’est-à-dire que la configuration du projet peut surcharger celle du framework, ainsi de suite.

En regardant l’arborescence du projet, on s’aperçoit que seul l’application frontend dispose d’un répertoire config (pas le module bookmark). Si on ouvre le fichier apps/frontend/config/view.yml, on retrouve la pièce manquante du puzzle qui constitue la vue rendue :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# You can find more information about this file on the symfony website:

# http://www.symfony-project.org/reference/1_4/en/13-View



default:

  http_metas:

    content-type: text/html



  metas:

    #title:        symfony project

    #description:  symfony project

    #keywords:     symfony, project

    #language:     en

    #robots:       index, follow



  stylesheets:    [main.css]

  javascripts:    []

  has_layout:     true

  layout:         layout

C’est donc ici que sont définis les scripts et les feuilles de style CSS à utiliser. Notez les deux dernières lignes : elles précisent que la vue utilise un layout, nommé… layout. Il est donc possible pour un module ou une action d’utiliser un autre layout, voire aucun layout si, par exemple, il/elle génère des PDF à la volée. Adaptons tout cela à nos besoins :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# apps/frontend/config/view.yml

default:

  http_metas:

    content-type: text/html



  metas:

    title:        Plum Bookmark Manager

    description:  Plum Bookmark Manager is a web application intended to store and manage your bookmarks

    keywords:     plum, bookmark, manager, php, symfony



  stylesheets:    [main.css]

  javascripts:    []

  has_layout:     true

  layout:         layout

De plus, en modifiant le layout et la CSS main.css, on peut facilement obtenir un résultat visuel plus agréable : Mais en général, ce n’est pas de cette façon que les bookmarks sont présentés. Il faudrait que le lien soit cliquable, que la date d’ajout soit mieux formatée, et que l’ID disparaisse (il ne nous intéresse pas, de toute manière). Allons faire un tour dans apps/frontend/modules/bookmark/templates/indexSuccess.php, et modifions-le comme ceci :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 use_helper('Date'); ?>

Bookmarks List






  

   foreach ($bookmarks as $bookmark): ?>

    

      

      

    

   endforeach; ?>

  
 echo format_date($bookmark->getCreatedAt(), 'p') ?>  echo link_to($bookmark->getDescription(), $bookmark->getUrl(), array('popup' => 'true')) ?>






 echo url_for('bookmark/new') ?>">New

La table a été épurée, et des helpers sont maintenant utilisés : format_date et link_to. Ils permettent respectivement d’obtenir une date plus lisible et un lien HTML avec une description. Comme format_date n’est pas accessible par défaut dans les templates, il a fallu inclure DateHelper grâce à la directive use_helper('Date') (le suffixe “Helper” est ajouté automatiquement).

Taguez-les tous !

La deuxième partie à revoir après le design, c’est la gestion des tags. En effet, il nous reste deux classes qui ne sont pas encore utilisées : Tag et BookmarkTag. La seconde étant une table de liaison, on ne va pas la manipuler directement (i.e. nous n’allons pas en créer un module). Par contre, il peut être intéressant d’avoir un module tag :

1
$ ./symfony doctrine:generate-module frontend tag Tag

Plutôt que d’utiliser les formulaires générés pour insérer des données de tests, nous allons utiliser des fixtures, un jeu de données spécifié dans un fichier, qui pourra être utilisé à n’importe quel moment pour réinitialiser la base de données :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# data/fixtures/fixtures.yml

Bookmark:

  excilys: # cette clé sert de "clé primaire" pour BookmarkTag

    url: http://www.excilys.com

    description: Site du groupe Excilys

  google:

    url: http://www.google.fr

    description: Un moteur de recherche peu connu



Tag:

  informatique:

    name: Informatique

  dev:

    name: Dev



BookmarkTag:

  bt1:

    Bookmark: excilys

    Tag: informatique

  bt2:

    Bookmark: excilys

    Tag: dev

  bt3:

    Bookmark: google

    Tag: informatique

Ces données peuvent être insérées en base avec la commande suivante (qui efface les éventuelles données déjà présentes) :

1
$ symfony doctrine:data-load

Avec un nuage de tags, SVP…

Nous pouvons maintenant ajouter une action au module tag, par exemple pour générer un nuage de tags. Pour cela, nous allons créer une méthode qui va chercher les tags utilisés en base, ainsi que le nombre de fois qu’ils sont utilisés. Cela se passe dans la classe BookmarkTagTable (un DAO étendant Doctrine_Table) :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// lib/model/doctrine/BookmarkTagTable.class.php

class BookmarkTagTable extends Doctrine_Table

{

  /**

  * Retrieves all the tags with the number of times they are attached to

  * a bookmark (weight).

  */

  public function retrieveTagsWithWeight()

  {

    $q = $this->createQuery('bt')

        ->leftJoin('bt.Tag t')

        ->select('bt.tag_id, t.name, count(bt.tag_id)')

        ->groupBy('bt.tag_id')

        ->orderBy('t.name ASC');



    return $q->fetchArray();

  }

}

Les méthodes appelées sont suffisamment explicites pour que je ne les détaille pas. L’étape suivante consiste à ajouter l’action qui va appeler ce DAO, puis la vue qui affichera le nuage :

1
2
3
4
5
6
7
// apps/frontend/modules/tag/actions/actions.class.php

public function executeTagCloud(sfWebRequest $request)

{

  $this->tags = Doctrine::getTable('BookmarkTag')->retrieveTagsWithWeight();

  $this->baseFontSize = doubleval(sfConfig::get('app_fontSizes_base'));

  $this->maxFontSize = doubleval(sfConfig::get('app_fontSizes_max'));

}

On définit deux tailles de police : minimale et maximale. Plutôt que de coder en dur ces valeurs, on les externalise dans le fichier de configuration de l’application, que l’on peut lire grâce à sfConfig::get('app_key_name') :

1
2
3
4
5
# apps/frontend/config/app.yml

all:

  fontSizes:

    base: 0.8

    max: 2.0

Notez que l’imbrication yaml se traduit en une concaténation avec des underscores au niveau du nom de la propriété (ex. app_fontSizes_base).

Voici la vue :

1
2
3
4
5
6
7
8
9


foreach($tags as $tag) {

  $count = intval($tag['count']);

  $fontSize = min($baseFontSize + ($count / 10) - 0.1, $maxFontSize);



  echo link_to($tag['Tag']['name'], 'bookmark/byTag?name='.$tag['Tag']['name'],

      array('style' => "font-size: ${fontSize}em;"));

  echo ' ';

}

Le code fait un calcul savant maladroit de taille de police en fonction du poids (nombre d’associations entre ce tag et un bookmark), avec des bornes mini et maxi. Un autre algorithme possible calculerait la taille d’un tag relativement à sa fréquence d’utilisation par rapport aux autres (par exemple, si tous les tags sont utilisés 100 fois, ils auront la même petite taille, puisqu’aucun ne se démarque vraiment).

Il serait bien de pouvoir intégrer ce nuage de tags sur toutes les pages, idéalement il faudrait l’intégrer dans le layout global.

Les components

Notre nuage de tags

Comment rendre un template dans un autre ? Pour faire ce genre de tâches, symfony propose la notion de component : dans le layout global, on va ajouter une directive d’inclusion de composant, qui fait référence à un couple module/composant. Les composants sont différents des actions. Ils résident dans un fichier actions/components.class.php, et leur templates sont sous la forme _.php.

Pour migrer notre action en composant, il faut donc créer le fichier apps/frontend/modules/tag/actions/components.class.php, y déplacer la méthode executeTagCloud(), et renommer le template tagCloudSuccess.php en _tagCloud.php.

Le résultat du rendu de notre composant sera intégré à l’endroit de son inclusion :

1
2
3
4
5
6
7
<body>

...

  <div id="right-column">

    ('tag', 'tagCloud'); ?>

  </div>

...

</body>

En adaptant la CSS, on peut obtenir ce design :

A fond les forms !

Un framework dédié aux formulaires est présent dans symfony, il est assez complexe à appréhender lorsqu’on débute, je vais donc essayer d’être le plus clair possible et de ne pas m’égarer. Au niveau du vocabulaire, un formulaire est représenté par une classe *Form, contenant entre autre des widgets et des validators. Les premiers sont utilisés pour le rendu HTML (par exemple on a un widget input text et un widget combobox). Les validateurs, quant à eux, permettent de vérifier que les données entrées pour un widget donné sont “valides” ; il y a donc un validateur par widget.

Ouvrons la classe BookmarkForm, générée par doctrine:build. Elle est vide, ce qui est normal puisque le comportement par défaut est défini dans sa classe parente gérée par le framework, BaseBookmarkForm. La première chose que je vous propose de faire, c’est de désactiver le champ created_at, puisqu’il est censé devoir être valorisé automatiquement :

1
2
3
4
5
6
7
class BookmarkForm extends BaseBookmarkForm

{

  public function configure()

  {

    unset($this['created_at']);

  }

}

Il faudra également supprimer les références à created_at dans les templates de vues.

Toujours dans la méthode configure(), il serait intéressant d’utiliser un validateur d’URL pour notre champ url :

1
2
3
4
$this->validatorSchema['url'] = new sfValidatorAnd(array(

  $this->validatorSchema['url'],

  new sfValidatorUrl()

));

L’astuce ici consiste à utiliser un “super-validateur” qui va faire un “et logique” entre le validateur par défaut (pour la taille maximale de 255 caractères) et un sfValidatorUrl.

Si l’on essaie d’ajouter un nouveau bookmark, la vue est maintenant minimaliste. Si l’on tente de rentrer une URL invalide, des messages d’erreur nous préviennent :

Message en cas d'URL invalide

Regardons de plus près le fonctionnement du processus de soumission. Une fois les données entrées, l’action create va exécuter les étapes suivantes (dans la méthode processForm) :

binder les données POST sur l’objet *Form adéquat,
valider les données en appelant la méthode validate(),
réafficher la vue en cas d’erreur,
sinon persister les objets en cas de succès, puis rediriger vers la liste de bookmarks.

Passez le bonjour agile

Après réflexion, le modèle de données n’est pas forcément le meilleur. Pour associer les tags à un bookmark, on utilise généralement un seul champ de saisie dans lequel on séparera les tags par des virgules. Après validation du formulaire, il faudra donc rechercher tous les éventuels enregistrements correspondant à ces tags en base, pour pouvoir ajouter les relations tag-bookmark.

Il serait peut-être plus judicieux et plus pratique de ne pas avoir une relation n-m (notre classe BookmarkTag), mais 1-n. Certes, il y aura des doublons dans la base, mais on gagnera surement en simplicité.

Fort heureusement pour nous, nous avons vu que symfony permet facilement de modifier le modèle de données. Il suffit d’éditer le fichier config/doctrine/schema.yml et de reconstruire les classes du domaine, de formulaires, etc.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# schema.yml

Bookmark:

  actAs:

    Timestampable:

      updated:

        disabled: true

  columns:

    url:  { type: string(255), notnull: true }

    description: { type: string(255) }



Tag:

  columns:

    bookmark_id:  { type: integer }

    name: { type: string(255), notnull: true }

  relations:

    Bookmark:  { onDelete: CASCADE, local: bookmark_id, foreign: id }

Avant de reconstruire les classes, il faut au préalable supprimer les fichiers *BookmarkTag* dans lib/, sinon Doctrine continuera de créer la table BookmarkTag en BDD (pour une raison qui m’échappe). Il ne faut évidemment pas oublier de déplacer le code gérant le nuage de tags dans les classes/vues de gestion de Tag (au lieu de BookmarkTag précédemment).

1
$ ./symfony doctrine:build --all

Pour obtenir le nouveau comportement décrit plus haut, il faut à présent modifier :

la classe BookmarkForm pour y ajouter un widget correspondant à notre liste de tags,
la vue permettant l’insertion d’un bookmark pour y ajouter un champ de saisie de type texte.

1
2
3
4
5
6
7
8
// lib/form/doctrine/BookmarkForm.class.php



public function configure()

{

  // ...

  $this->widgetSchema['tags'] = new sfWidgetFormInputText();

  $this->validatorSchema['tags'] = new sfValidatorString();

}
1
2
3
4
5
6
7


<tr>

  <th>Tags :</th>

  <td>

    ['tags'] ?>

  </td>

</tr>

L’astuce est ensuite de convertir la valeur récupérée dans le widget ‘tags’ en autant de tags. Pour cela, il faut intervenir juste la sauvegarde du formulaire, dans actions.class.php :

1
2
3
4
5
6
7
8
9
protected function processForm(sfWebRequest $request, sfForm $form)

{

  // ...

  if ($form->isValid())

  {

    $bookmark = $form->save();



    Doctrine::getTable('Bookmark')->createTags($bookmark->getId(), $form->getValue('tags'));

    // ...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
class BookmarkTable extends Doctrine_Table

{

    public static function createTags($bookmarkId, $tagList)

    {

        $tags = explode(',', $tagList);



        foreach ($tags as $tag) {

            $t = new Tag();

            $t->setBookmarkId($bookmarkId);

            $t->setName(trim($tag));

            $t->save();

        }

    }

}

Vérifions si tout fonctionne bien :

Création d'un bookmark avec des tags associés

Ceci n’est qu’une ébauche assez maladroite. Dans le monde merveilleux des Bisounours, il faudrait vérifier que l’on n’insère pas plusieurs fois le même tag sur le même bookmark, en particulier lorsqu’on utilise le formulaire d’édition (qui contient lui aussi le champ ‘tags’). Ceci peut faire un parfait exercice pour le lecteur assidu, d’autant plus que nous approchons dangereusement de la limite de taille (raisonnable) pour un article . Si vous cherchez un autre exercice pour cogiter le soir dans le métro, vous pouvez également essayer d’afficher la liste des tags associés à un bookmark.

Conclusion

Nous voici déjà à la fin de cet article (ohhhhh… ). Ce que nous pouvons en retenir, c’est qu’à chaque problème, symfony propose une solution. Les problèmes que l’on peut rencontrer sont souvent les mêmes d’un projet à l’autre, c’est pourquoi les concepteurs du framework le développent de manière à ce que l’on perde le moins de temps possible.

symfony est suffisamment flexible et agile pour permettre à tout moment de modifier le modèle de données et pouvoir profiter de ces modifications assez rapidement, notamment grâce à la génération automatique de code. J’ajouterais néanmoins qu’il est préférable, à mon sens, de bien réfléchir au modèle dès le départ pour éviter de perdre trop de temps par la suite.

Il est également intéressant de noter que l’on peut faire des thèmes assez jolis à base de rose, et que ça ne fait pas forcément girly (le lecteur visé se reconnaitra ).

Accès au code source :

http://code.google.com/p/excilys/source/browse/projects#projects/plum/tags/plum_article_3

[cci]

Menez le web à la baguette avec symfony (2) : un squelette pour pas chair

Bastien JANSEN — Fri, 15 Jan 2010 19:38:17 +0000

Résumé de l’épisode 1

Dans l’article précédent, nous avons rapidement vu que des solutions intéressantes apparaissent au sein du monde PHP. Parmi l’un des nombreux frameworks émergeants, nous avons choisi d’étudier symfony à travers la création d’une application web de gestion de bookmarks, Plum. Nous avons pour l’instant créé une application par défaut. Il reste maintenant à lui faire faire son “vrai” travail…

Nous manipulons pour l’instant peu de types de données : les bookmarks et les tags. Voici un diagramme UML les représentant :

Diagramme de classes de notre modèle

(Ce magnifique diagramme a été réalisé en ligne sur le site de yuml.me. Publicité gratuite ).

Pour facilement manipuler les données en base, symfony gère de base deux Object-Relational Mappers (ORM) : Doctrine et Propel. Cependant, comme Doctrine est devenu l’ORM par défaut depuis la version 1.3 du framework, c’est lui que nous utiliserons. Doctrine propose une solution élégante d’accès aux données via le langage DQL, inspiré du HQL d’Hibernate, ainsi qu’une API d’accès aux données. Propel se base de son côté sur une API semblable aux Criteria. Que l’on utilise Doctrine ou Propel, symfony fonctionne de manière semblable. Dans la suite de cet article, je vais détailler pas à pas les étapes suivantes :

configuration de l’accès à la BDD (hôte, port etc.),
définition du modèle de données dans un fichier au format YAML : config/doctrine/schema.yml,
appel de la commande responsable de la génération des classes du modèle, du code SQL, de la création de la BDD et chargement des données de test en BDD,
éventuelle génération de modules dans une application pour faire du CRUD basique,
adaptation du code et utilisation de l’API Doctrine…

Définition du modèle de données

La configuration de la base de données se fait au moyen d’une commande :

1
./symfony configure:database --name=doctrine --class=sfDoctrineDatabase "mysql:host=localhost;dbname=plum" root password

Ce qui crée un fichier config/databases.yml utilisant le “driver” sfDoctrineDatabase sur une base MySQL locale nommé plum. Par la suite, il suffira de modifier directement ce fichier au lieu de rappeler cette commande :

1
2
3
4
5
6
7
8
# config/databases.yml

all:

  doctrine:

    class: sfDoctrineDatabase

    param:

      dsn: 'mysql:host=localhost;dbname=plum'

      username: root

      password: password

Note : si vous commencez à vous perdre au milieu de toutes ces commandes, sachez qu’elles disposent d’une aide contextuelle. Vous pouvez y accéder en utilisant “symfony help” suivi de la commande qui vous cause du souci, par exemple :

1
2
3
4
$ ./symfony help doctrine:build

Usage:

 symfony doctrine:build [--application[="..."]] [--env="..."] [--no-confirmation] [--all] [--all-classes] [--model] [--forms] [--filters] [--sql] [--db] [--and-migrate] [--and-load[="..."]] [--and-append[="..."]]

...

La seconde étape est la définition du modèle, elle se fait de la manière suivante :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# config/doctrine/schema.yml

Bookmark:

  actAs:

    Timestampable:

      updated:

        disabled: true

  columns:

    url:  { type: string(255), notnull: true }

    description: { type: string(255) }



Tag:

  columns:

    name: { type: string(255), notnull: true, unique: true }



BookmarkTag:

  columns:

    bookmark_id:  { type: integer, primary: true }

    tag_id: { type: integer, primary: true }

  relations:

    Bookmark:  { onDelete: CASCADE, local: bookmark_id, foreign: id }

    Tag: { onDelete: CASCADE, local: tag_id, foreign: id }

On définit ici trois tables, ayant chacune une série de colonnes (champs). La clé actAs permet d’ajouter des comportements (behaviours) spécifiques à Doctrine. Par exemple, ici on décide que la table Bookmark est Timestampable, ce qui aura pour but d’ajouter automatiquement deux champs created_at et updated_at, qui seront mis à jour par magie. Mais nous ne sommes pas intéressés par le champ updated_at, donc nous le supprimons.

La table BookmarkTag est la table de liaison de la relation n-n entre bookmarks et tags. On y retrouve donc les deux champs correspondant aux clés étrangères. La relation proprement dite est définie sous la clé relations, avec le nom des tables référencées, ainsi que les champs locaux et distants. Nous allons maintenant pouvoir passer à la génération de la base de donn… comment ? “D’où viennent les champs id référencés dans la relation de la table BookmarkTag ?” Eh bien, ils sont générés automagiquement par Doctrine ! Ainsi, un champ “id” en clé primaire autoincrémentée sera ajouté aux tables Bookmark et Tag (mais pas à BookmarkTag qui possède déjà une clé primaire composée des deux clés étrangères).

Génération enchantée

Base et modèle de données

C’est à partir d’ici que nous allons pouvoir mesurer toute la puissance du framework (et de ses composants). Même si jusqu’ici on en a déjà pris plein les yeux, ça ne fait que commencer . Tout va se produire dans cette ligne de commande aux allures mystiques :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
$ symfony doctrine:build --all



 This command will remove all data in the following "dev" connection(s):  



 - doctrine                                                              



 Are you sure you want to proceed? (y/N)                                  



y

>> doctrine  Dropping "doctrine" database

>> doctrine  SQLSTATE[HY000]: General error:...ing Query: "DROP DATABASE plum"

>> doctrine  Creating "dev" environment "doctrine" database

>> doctrine  generating model classes

>> file+     C:\Users\Bastien\AppData\Local\Temp/doctrine_schema_38869.yml

>> tokens    C:/wamp/www/plum/trunk/lib/mode...ine/base/BaseBookmark.class.php

..

>> autoload  Resetting application autoloaders

>> file-     C:/wamp/www/plum/trunk/cache/fr.../config/config_autoload.yml.php

>> doctrine  generating form classes

>> tokens    C:/wamp/www/plum/trunk/lib/form/BaseForm.class.php

>> tokens    C:/wamp/www/plum/trunk/lib/form...base/BaseBookmarkForm.class.php

...

>> tokens    C:/wamp/www/plum/trunk/lib/form/doctrine/BookmarkForm.class.php

...

>> autoload  Resetting application autoloaders

>> file-     C:/wamp/www/plum/trunk/cache/fr.../config/config_autoload.yml.php

>> doctrine  generating filter form classes

>> tokens    C:/wamp/www/plum/trunk/lib/filt...aseBookmarkFormFilter.class.php

...

>> autoload  Resetting application autoloaders

>> file-     C:/wamp/www/plum/trunk/cache/fr.../config/config_autoload.yml.php

>> doctrine  generating sql for models

>> doctrine  Generated SQL successfully for models

>> doctrine  created tables successfully

Vu le nombre de lignes affichées en sortie, cette commande a dû faire pas mal de choses… En fait, c’est un énorme raccourci (d’où le –all) qui a fait les actions suivantes :

DROP de la base de données définie précédemment (avec une confirmation, qui peut être évitée en passant le paramètre supplémentaire –no-confirmation),
création de la base de données,
création des model classes, qui sont une “traduction” sous formes d’entités PHP de notre modèle de données (typiquement ce qu’il y a dans le package domain dans les applis Java),
création des form classes, qui serviront dans les formulaires des vues (équivalent des Command Spring ou des ActionForm Struts). Ils seront entre autres chargés de valider les données entrées, et éventuellement de les transformer,
création de filter form classes, qui seront utilisées dans les formulaires pour chercher des enregistrements selon certains critères (des utilisateurs par sexe, couleur de cheveux, … enfin pas avec le modèle de données de Plum, bien sûr ),
génération du code SQL nécessaire à la création des tables (correspondant à ce que nous avons décrit dans config/doctrine/schema.yml)
création des tables en BDD à partir du code SQL précédemment généré

Note : pour une fois, nous avons été feignants. Il est possible de faire toutes ces opérations étape par étape, en passant des paramètres à doctrine:build (comme –model, –filters etc. se référer à l’aide contextuelle !).

Ne vous inquiétez pas, nous nous attarderons plus tard sur chacun des points de la liste précédente (lorsque nous en aurons besoin, en fait). Notez tout de même que dans les noms de classes générées, on retrouve des héritages, comme par exemple BaseBookmarkForm et BookmarkForm. La première est gérée par symfony, et est susceptible d’être modifiée automatiquement suite à l’exécution d’une commande. La seconde hérite de la première, c’est celle-ci que nous pourrons modifier librement pour adapter le comportement à nos besoins (et bénéficier immédiatement des répercussions de modèle, par exemple, qui seront intégrées dans la classe de base regénérée).

Scaffolding

Scaffolding en action...

Bien, maintenant que nous avons une version PHP et SQL de notre modèle, il faut l’utiliser. Pour cela, symfony, comme d’autres frameworks, propose de générer un squelette de code permettant de faire du CRUD (Create-Retrieve-Update-Delete). Cette génération est généralement appelée scaffolding dans le jargon RoR/Grails/. Allons-y :

1
2
3
4
5
6
7
8
9
10
$ symfony doctrine:generate-module frontend bookmark Bookmark

>> dir+      ..nd\modules/bookmark\actions

>> file+     ...kmark\actions/actions.class.php

>> dir+      ...nd\modules/bookmark\templates

>> file+     ...kmark\templates/editSuccess.php

>> file+     ...mark\templates/indexSuccess.php

>> file+     ...okmark\templates/newSuccess.php

>> file+     ...kmark\templates/showSuccess.php

>> file+     ...es/bookmark\templates/_form.php

...

Nous venons de générer un module. Dans le vocabulaire symfoniesque, un module est un sous-ensemble d’une application, qui va regrouper un certains nombre de fonctionnalités liées à une “entité”. Dans notre cas, les opérations de manipulation d’un marque-page seront groupées dans le module nommé bookmark. Ce module a été créé dans l’application frontend, et il est basé sur l’objet Bookmark défini dans notre modèle de données. Cette commande est donc liée à Doctrine (il suffit de regarder son préfixe “doctrine:”). Dans le cas où nous souhaiterions créer un module qui n’a rien à voir avec le modèle (par exemple un module contenant des pages statiques), il faudra utiliser la commande generate:module.

Aperçu

Il est temps de voir ce que cette génération rend visuellement. Pour cela, butinez l’adresse http://www.plum.local/frontend_dev.php/bookmark :

Etape 1 : la liste des bookmarks est vide

Etape 2 : on clique sur "Create", et on remplit les champs

Etape 3 : on valide. Tadaaa !!

Remarquez la barre de debug en haut à droite des pages rendues. En cliquant sur les différents textes affichés, il est possible d’avoir le détail de la configuration, des requêtes SQL exécutées, les logs générés, etc. Très utile donc, et en exclusivité chez symfony à ma connaissance (edit : ou alors ils étaient les premiers, les implémentations dans Django ou Grails ne semblent pas aussi complètes). Elle n’est disponible qu’en environnement “dev”, accessible via le contrôleur frontend_dev.php. Si vous souhaitez accéder à l’environnement prod, il faut utiliser le contrôleur index.php. Il existe également les environnement de test et de staging, pour plus d’info consultez la documentation symfony.

Remarquez également le motif des URL dans les captures précédentes. Après le nom du contrôleur frontend_dev.php identifiant l’application utilisée (qui peut être omis en production grâce à de l’URL rewriting Apache par exemple), nous retrouvons le nom du module (bookmark) et éventuellement une action (new, ou index par défaut). Plus d’infos sur les actions dans le chapitre qui suit.

Analyse du code généré

Arborescence des modules

Cette magnifique image montre les deux endroits où le scaffolding a opéré.

Tout d’abord, un répertoire bookmark a été créé dans apps/frontend/modules. Il contient les actions et les vues. Les actions contiennent de la logique (mais pas métier), elles peuvent être apparentées à une couche service. C’est ici que nous ferons des appels aux classes du modèle générées par Doctrine.

Le fichier actions.class.php contient la classe bookmarkActions, dont voici un extrait :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
class bookmarkActions extends sfActions

{

  public function executeIndex(sfWebRequest $request)

  {

    $this->bookmarks = Doctrine::getTable('Bookmark')

      ->createQuery('a')

      ->execute();

  }



  public function executeNew(sfWebRequest $request)

  {

    $this->form = new BookmarkForm();

  }

  //...

Chaque action correspond à une méthode dont le nom est de la forme execute. Dans l’extrait de code précédent, nous pouvons voir deux actions, “index” et “new”, responsable du listage et de la création d’un bookmark. Nous pouvons voir l’utilisation de la classe BookmarkForm générée par Doctrine, qui sera utilisée dans la vue.

Les vues sont définies dans le répertoire templates, en général on en retrouve une par action. Leur nom suit le motif nomAction.php. Par défaut, l’état vaut “success”, mais il est possible d’en spécifier un autre en retournant une chaine de caractères à la fin de la méthode d’action, par exemple “error”, ou mieux : sfView::ERROR. Dans ce cas, le template <nomAction>Error.php sera utilisé.

Symfony permet de renvoyer n’importe quel type de données dans la vue. Par défaut c’est du HTML, mais rien n’empêche de générer un PDF ou une image en réponse de la requête. Il faut alors veiller à ce que le serveur envoie le bon type MIME dans la réponse, pour que le navigateur gère correctement le résultat.

Le second endroit où le scaffolding a ajouté des fichier est le répertoire de tests. On remarque qu’un test fonctionnel a été ajouté pour la classe bookmarkActions :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
include(dirname(__FILE__).'/../../bootstrap/functional.php');



$browser = new sfTestFunctional(new sfBrowser());



$browser->

  get('/bookmark/index')->



  with('request')->begin()->

    isParameter('module', 'bookmark')->

    isParameter('action', 'index')->

  end()->



  with('response')->begin()->

    isStatusCode(200)->

    checkElement('body', '!/This is a temporary page/')->

  end()

;

Nous n’allons trop nous attarder sur ce test. Sachez juste que le framework propose un “émulateur de navigateur”, sur lequel nous allons pouvoir appeler des pages, puis faire des vérifications dans la requête ainsi que dans la réponse. Ici, le test vérifie que si l’on appelle l’action index du module bookmark, la réponse a un statut HTTP 200 (aucun souci) et la page renvoyée ne contient pas la chaine “This is a temporary page” que l’on trouve dans la page par défaut d’un projet symfony.

Juste pour être surs, nous pouvons lancer les tests :

1
2
3
4
$ ./symfony test:functional frontend

bookmarkActionsTest..................................................ok

  All tests successful.

  Files=1, Tests=4

Routage

Récapitulons ce qui s’est passé. Nous venons de générer un module permettant de faire du CRUD sur la table des bookmarks. Les formulaires HTML générés sont accessibles à l’URL http://www.plum.local/frontend_dev.php/bookmark, mais pour l’instant l’URL “/” pointe toujours vers la page par défaut de symfony si on ne spécifie aucun module. Corrigeons cela en éditant le fichier de routage du frontend :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# apps/frontend/config/routing.yml

# You can find more information about this file on the symfony website:

# http://www.symfony-project.org/reference/1_4/en/10-Routing



# default rules

homepage:

  url:   /

  param: { module: default, action: index }



# generic rules

# please, remove them by adding more specific rules

default_index:

  url:   /:module

  param: { action: index }



default:

  url:   /:module/:action/*

Le routage est un composant important du framework (même si en fait, tous les composants sont importants ). Il va permettre d’appeler la bonne action sur le bon module en fonction de l’URL demandée. Le fichier de configuration précédent est une série de règles, qui vont être parcourues l’une après l’autre. La première matchant l’URL appelée gagne. Pour notre page par défaut, c’est la première règle qui est utilisée (rien après le slash). La clé param indique le module et l’action à utiliser : ici, c’est l’action index dans le module default situé au fin fond du framework.

Si la première règle ne convient pas, alors on essaye de voir si on peut trouver un nom de module, auquel cas on exécute par défaut l’action index. En dernier choix, le routage tente de trouver un module et une action (éventuellement suivie de paramètres dénotés par l’astérisque).

Nous souhaiterions afficher par défaut la liste des bookmarks enregistrés, il va donc falloir pointer vers bookmark/index :

1
2
3
4
# apps/frontend/config/routing.yml

homepage:

  url:   /

  param: { module: bookmark, action: index }

Et voilà le résultat :

Nouvelle homepage

Note : si vous utilisez le contrôleur de prod, index.php, il se peut que les changements ne soient pas pris en compte, à cause du cache de l’application. Il faut alors exécuter la commande symfony cache:clear, ou pour les plus feignants symfony cc.

Grails propose un système de routes du même acabit, où le nom du contrôleur et de l’action sont également concaténés avec des slashs. Après recherches, Grails ne semble pas proposer de routes nommées comme le font symfony et Ruby on Rails (du moins, pas directement). Les routes nommées permettent de rediriger vers ou de créer une URL à partir d’un nom plus explicite. Dans le listing précédent, on voit un exemple avec la route nommée homepage qui pointe vers /bookmark/index. Elle peut ensuite être référencée ainsi :

1
link_to("Rentrer à la maison", '@homepage?param1=value1');

Bonux : comparaison des commandes grails et symfony + vocabulaire utilisé

1
2
3
4
5
6
7
# Création des classes du domaine

$ grails create-domain-class com.excilys.grails.Song # On fait générer des classes du modèle une par une. La base de donnée est modifiée au runtime.

$ symfony doctrine:build --all # On définit le modèle dans un fichier de config, et symfony génère les classes associées et met à jour la base de donnée.



# Génération des controleurs et des vues pour le CRUD

$ grails generate-all com.excilys.grails.Song

$ symfony doctrine:generate-module frontend bookmark Bookmark

Note: attention tout de même, ces commandes ne sont pas strictement équivalentes (notamment au niveau de la spécification d’une classe particulère à générer)

Certains relecteurs m’ont fait remarquer que les différences de vocabulaire entre symfony/grails/une application Java peuvent porter à confusion. Voici donc des équivalences de termes (à mon sens) :

contrôleur symfony <=> DispatcherServlet Spring
actions symfony/grails <=> Controller Spring
*Table extends Doctrine_Table <=> DAO

Notez également que symfony recommande de placer la logique métier dans les classes *Table, les actions vont uniquement faire des tâches “simples” comme vérifier les paramètres obligatoires dans une URL, appeler les DAO, définir les variables utilisées dans les vues, faire des redirect/forward et laisser la main à la vue.

Stay tuned for scenes from our next episode…

Nous venons de générer un module avec du code par défaut. Il va maintenant falloir l’adapter : supprimer les actions non utilisées, en ajouter si besoin, rendre l’apparence un peu plus attrayante… Bref, c’est maintenant que nous allons arrêter de faire du “par défaut” pour faire du “adapté à ce qu’on veut”. Et c’est aussi maintenant que l’on va pouvoir voir si le framework est suffisamment souple pour répondre à nos besoins (un indice : la réponse est “oui”).

A bientôt !

Accès au code source

Le code source de cet article est disponible sur le projet googlecode d’Excilys à l’adresse : http://excilys.googlecode.com/svn/projects/plum/tags/plum_article_2/

Menez le web à la baguette avec symfony

Bastien JANSEN — Thu, 07 Jan 2010 09:55:53 +0000

Introduction

Chez Excilys, nous ne sommes pas sectaires. Bien que le groupe concentre son activité autour des technologies Java, bon nombre de collaborateurs s’intéressent à d’autres langages ou technologies. Après Android et Grails, je vais vous présenter le framework PHP symfony au travers d’une série d’articles dans lesquels nous construirons petit à petit une application web.

Commençons par un rapide aperçu de PHP.

PHP: Hypertext Preprocessor est un langage de script créé par Rasmus Lerdorf en 1994. Bien que le langage soit majoritairement utilisé pour créer des sites/applications web (du fait qu’il propose beaucoup d’outils allant dans ce sens), il est tout à fait possible d’utiliser PHP pour créer des applications type script d’administration système, voire des applications graphiques (avec les bindings GTK par exemple).

Depuis ses débuts où il était écrit en Perl, PHP a évolué petit à petit pour devenir un langage objet (grosso modo depuis sa version 5), avec de nombreuses facilités telles que :

un accès très simple aux SGBD (MySQL, PostGreSQL…),
une manipulation de XML via DOM ou SimpleXML,
la possibilité de générer des images via GD,
de nombreuses autres API.

Durant de nombreuses années, PHP a été considéré comme un langage d’amateur, tout juste bon à bidouiller son site perso (PHP signifiait initialement Personal Home Page ). Il est vrai que cette techno n’a pas tous les atouts de son côté :

apparition tardive et pas forcément bien implémentée d’une syntaxe orientée objet,
incohérence (ou absence ?) de conventions de nommage et de paramétrage des fonctions des API,
nombreux problèmes de sécurité (aussi bien dans le langage que dans les principales applications).

Cependant, il est à noter que PHP a tout de même certains avantages :

langage assez simple à apprendre et à utiliser (un hello world consiste à écrire “Hello world!” dans un fichier .php),
performances convenables (et de nombreux tunings peuvent être effectués pour la scalability : cache, opcodes etc.),
documentation et aide très faciles à trouver.

Comme nous l’avons vu, PHP a longtemps été délaissé par les professionnels. Cependant la tendance s’inverse, le monde de l’entreprise semble de plus en plus s’intéresser (et contribuer) à cette technologie. La preuve en est avec la pléthore de frameworks PHP apparus depuis quelques années :

symfony,
Zend Framework,
CakePHP,
Code Igniter.

Les outils, bonnes pratiques et design patterns qui font le succès de langages tels que Java commencent à faire leur apparition au sein de la communauté PHP :

Présentation de symfony

Le but de cet article, puis de ses petits frères, sera de nous familiariser avec l’un des frameworks PHP les plus répandus actuellement, à savoir symfony. symfony est développé par Sensio Labs, une entreprise française spécialisée dans le développement web et les technologies Open Source.

Ce framework est intéressant sous plusieurs aspects. Outre le fait qu’il soit open source, il est développé par une entreprise, pour des entreprises. Sensio Labs assure donc le support adéquat, avec notamment des formations permettant de maitriser la bête en quelques jours. Côté documentation, nous sommes gâtés : tutoriels officiels (sous forme de calendrier de l’Avent), livres sous format électronique (gratuits) ou papier, forums, ainsi qu’une foultitude de sites de la communauté.

symfony, tout comme Maven ou Ruby on Rails, prône le paradigme “convention over configuration”. Toutefois, rien n’empêche le développeur téméraire de bousculer totalement le “normal” et adapter la structure à son goût (ou à de l’existant), de remplacer certains composants etc. Les différentes briques du frameworks se veulent les moins couplées possibles, de manière à pouvoir les remplacer ou les supprimer si elle ne sont pas nécessaires dans un projet.

Dans sa prochaine version majeure (actuellement en heavy development), Symfony 2 (notez la majuscule cette fois !) utilisera différents composants récemment développés, qui peuvent tout à fait être intégrés dans des projets utilisant (ou non) un autre framework : gestion du format YAML, event dispatcher, injection de dépendances, templating etc.

“Assez de blabla, plus de concret !”, entends-je dans le fond de la salle (près du radiateur…). Passons donc à l’action !

Présentation du projet : Plum

Afin de plonger dans le framework, je vous propose de développer directement une application web, que nous nommerons Plum (pour Plum Link & Url Manager par exemple, ou tout ce que votre imagination trouvera). Cette application aura pour principal fonction d’agréger des marques-pages, à la manière de del.icio.us. Un peu de fonctionnel, alors.

On désire pouvoir stocker des bookmarks, qui ne sont rien de plus que des URLs associées éventuellement à une description, ajoutées à une certaine date. À ces URLs, on va associer zéro ou plusieurs tags, qui sont en fait des mots-clés permettant de retrouver facilement des bookmarks liés à un sujet particulier.

Exemple :

URL : http://www.excilys.com
Description : Site du groupe Excilys
Date de création : 25/12/2009
Tags : excilys, développement, java, javaee, trop bien

Mise en place de l’environnement

À partir de maintenant, je suppose que vous disposez déjà d’un environnement Apache/PHP/MySQL fonctionnel. Si ce n’est pas le cas, de nombreux outils et tutoriels vous aideront si vous souhaitez installer Plum chez vous.

La récupération de symfony peut se faire de trois façons : par SVN, PEAR ou en téléchargeant une archive .zip ou .tgz. Nous choisirons la troisième solution (car elle nécessite moins d’utilitaires prérequis). Nous allons travailler sur la version 1.4.1 de symfony, sortie récemment et disposant d’un Long Term Support (LTS). Elle est à télécharger ici.

Dans la suite du projet, j’utiliserai le répertoire ~/prog/php/ comme répertoire de travail, mais vous êtes libres de l’adapter à votre OS/goût. Après avoir extrait l’archive symfony-1.4.1.tgz dans ~/prog/php, un dossier symfony-1.4.1 a dû être créé. Il contient l’ensemble du framework (dans lib/) ainsi que des assets et scripts de lancement (dans data/) et les tests unitaires/fonctionnels du framework (dans test/).

La première étape est de créer la structure du projet :

1
2
3
4
5
6
7
8
9
10
11
12
bastien:php $ mkdir plum

bastien:php $ cd plum/

bastien:plum $ ../symfony-1.4.1/data/bin/symfony generate:project plum

>> dir+      /home/bastien/prog/php/plum/log

>> file+     /home/bastien/prog/php/plum/symfony

>> dir+      /home/bastien/prog/php/plum/test

>> dir+      /home/bastien/prog/php/plum/test/functional

>> dir+      /home/bastien/prog/php/plum/test/bootstrap

...

>> tokens    /home/bastien/prog/php/plum/config/doctrine/schema.yml

>> tokens    /home/bastien/prog/php/plum/lib/form/BaseForm.class.php

bastien:plum $

Explications : rien de bien sorcier, on créé un répertoire qui va contenir notre projet, on se met dedans et on appelle le script principal de symfony (que nous venons d’extraire), avec les paramètres suivants :

generate:project : c’est la commande symfony que nous invoquons, qui va… générer un projet
plum : c’est le seul et unique paramètre de la commande, ici le nom de notre projet

Maintenant que nous avons un projet, il faut y ajouter une application (un projet peut contenir plusieurs applications). Nous allons dans un premier temps générer le frontend, c’est-à-dire l’application principale que verront les utilisateurs lambda :

1
2
3
4
5
6
bastien:plum $ ./symfony generate:app frontend

>> dir+      /home/bastien/prog/php/plum/apps/frontend/templates

>> file+     /home/bastien/prog/php/plum/apps/frontend/templates/layout.php

...

>> dir+      /home/bastien/prog/php/plum/test/functional/frontend

bastien:plum $

Notez que maintenant nous utilisons directement le script ./symfony (qui appelle derrière le script que nous appelions précédemment). La commande generate:app est invoquée pour générer une application nommée frontend, qui sera accessible dans un sous-dossier de apps/.

Analyse du projet généré

En retour, le script va nous générer un tas de dossiers et de fichiers, qui constituent l’arborescence de base d’un projet symfony :

apps : contient les applications du projet (typiquement le frontend que nous venons de générer)
cache : ici sera stocké le cache de l’application (afin de servir le client plus rapidement en évitant par exemple des parsings de configuration ou des remplissages de templates)
config : stocke tous les fichiers de configuration du projet (base de données, projet, rsync etc.)
data : c’est dans ce répertoire que seront mis entre autres les fixtures (des jeux de tests fixes à insérer dans une BDD)
lib : contiendra des classes PHP, de préférence globales au projet (en opposition aux classes ayant un scope application ou module, comme nous le verrons par la suite)
log : dossier dans lequel les logs applicatifs seront enregistrés
plugins : le répertoire des plugins externes (par exemple un plugin de gestion des comptes utilisateurs)
test : c’est là que nous placerons nos tests unitaires / fonctionnels
web : c’est le seul répertoire qui sera accessible depuis l’extérieur (c’est-à-dire par des requêtes sur le site), c’est donc ici que nous mettrons les images, les CSS etc.
symfony : ce n’est ni plus ni moins qu’un « raccourci » vers le script principal de symfony que nous avons utilisé tout à l’heure, il nous évitera d’avoir à retrouver son chemin à chaque fois

Afin de facilement accéder à l’application, j’ai choisi de créer un VirtualHost apache :

/etc/apache2/sites-available/plum.local

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15


 ServerName www.plum.local

 DocumentRoot "/home/bastien/prog/php/plum/web"

 DirectoryIndex index.php

 

 AllowOverride All

 Allow from All

 



 Alias /sf /home/bastien/prog/php/symfony-1.4.1/data/web/sf

 

 AllowOverride All

 Allow from All

En gros, on redirige www.plum.local (à ajouter dans /etc/hosts) vers le répertoire web/ de l’application, et on définit l’alias /sf qui pointe vers le répertoire data/sf/ du framework. Ce répertoire contient les CSS et images utilisées dans le code généré lors de la création du projet.

Voici à quoi ressemble l’application générée :

Nous n’avons pour l’instant généré qu’un projet vide pointant vers une page par défaut du framework. Nous corrigerons tout cela dans le second article, dans lequel nous définirons le modèle de données de notre application avant de tester la génération de code.

Bonux : comparaison des commandes grails et symfony

Génération du projet :

1
2
grails create-app ourapp

symfony generate:project ourapp

(Il faut par la suite générer une ou des application(s) avec symfony pour obtenir un résultat exploitable par le serveur web)

Accès au code source :

Le code source de cet article est disponible sur le projet googlecode d’Excilys à l’adresse : http://excilys.googlecode.com/svn/projects/plum/tags/plum_article_1/

La suite de la série est disponible ! Lire l’épisode 2.