Utiliser Chaplin.js et Backbone.js avec Symfony 2 : installation et configuration

Introduction

Le développement d’applications web modernes de qualité est une tache complexe : elles doivent être performantes, réactives, maintenables, modulaires, évolutives et,  à minima, être compatibles avec la diversité de navigateurs et de plateformes avec lesquelles elles seront utilisées (ordinateurs, tablettes, smartphones…). Elles doivent s’intégrer avec un nombre croissant de services tiers (Facebook, Twitter…). Elles doivent pouvoir être déployées sur des hébergements classiques comme sur des plateformes de Cloud Computing.

Pour réussir, la partie client de l’application doit désormais être tout aussi soignée et bien conçue que la partie serveur. Heureusement de nombreux composants logiciels permettent d’accélérer et de fiabiliser ces développements. Encore faut-il savoir choisir dans cette jungle des bibliothèques et de frameworks puis les faire fonctionner ensembles.

Question choix, pas d’inquiétudes, je les impose !

Côté serveur j’utiliserais Symfony 2. La deuxième version majeure de ce framework web à la Ruby On Rails écrit en PHP repose sur le meta-pattern MVC et l’injection de dépendances. Le framework Symfony inclut en standard presque tout ce qu’il faut : ORM, templates, système d’envoi d’emails, framework de génération de formulaires, outils de tests unitaires et fonctionnels. Il promeut des conventions de structuration et de codage ; est fort d’une vaste communauté et dispose de nombreux bundles tiers (extensions) parmi lesquels un générateur d’administration, l’intégration de l’API Facebook et près de 1800 autres.

Côté client je me baserais sur la bibliothèque Backbone.js, une étoile montante du monde Javascript, via Chaplin.js. Backbone permet de synchroniser très aisément les données d’une application cliente via des appels à une API REST côté serveur. Le framework Chaplin.js qui repose sur Backbone propose un structure de projet et quelques fonctionnalités bien utiles comme le support des modules AMD et une implémentation des design-patterns usuels.

J’écrierais le code client en CoffeeScript, une syntaxe alternative à JS inspirée de Ruby mais vous n’êtes pas obligés de faire de même.

Je vais m’employer à décire au long de deux articles l’utilisation conjointe de ces deux technologies. Dans le premier nous installerons et configurerons ces composants pour qu’ils fonctionnent ensembles. Dans le second je réaliserais un microblog une implémentation de TodoMVC. Sa partie serveur sera réalisée avec Symfony sous la forme d’une API REST / JSON directement compatible avec sa partie cliente réalisée à l’aide de Chaplin.js et Backbone.js.

Pré-requis

Connaissances

• maîtrise de PHP et de la programmation orienté objet
• bonnes notions du développement avec Symfony 2
• maîtrise de JavaScript
• notions de CoffeeScript si vous souhaitez utilisez cette syntaxe

Logiciels

• un serveur LAMP (Apache, PHP, MySQL) fonctionnel
• le gestionnaire de bibliothèques PHP Composer
• si vous souhaitez utiliser la version Coffee de Chaplin.js il faudra bien entendu CoffeeScript, qui lui même dépend de Node.js et de NPM

Si vous utilisez Mac OS X je ne saurais que trop vous conseiller Homebrew pour installer MySQL, Node.js (si vous utilisez la version CoffeeScript de Chaplin.js) et une version récente de PHP.

Création du projet Symfony

Installez Symfony via Composer grâce à cette commande :

$ composer create-project symfony/framework-standard-edition <mon-dossier/votre-application> 2.16

Puis suivez le guide pour configurer correctement votre environnement.

Génération du bundle qui contiendra l’application client Backbone.js / Chaplin.js

Créez ensuite un bundle qui contiendra votre application en tapant la commande suivante à la racine de votre projet Symfony:

$ php app/console generate:bundle

Et répondez aux question posées par le générateur. Pour ma part j’ai indiqué Dunglas/ChaplinDemoBundle comme namespace et j’ai laissé les choix par défaut pour toutes les autres options.

Installation de Chaplin.js, de Backbone.js et de leurs dépendances

Téléchargez maintenant le boilerplate Chaplin.js, version CoffeeScript ou version JavaScript (cliquez sur le bouton ZIP sur ces pages pour récupérer une archive de la dernière version), décompressez le.

Si vous utilisez la version en pure JavaScript copiez le contenu du répertoire js/ dans le dossier Ressources/public/ de votre bundle et passez directement à l’étape d’installation des assets.

Pour ceux qui préfèrent CoffeeScript copiez le répertoire coffee/ de l’archive dans le répertoire Ressources/ du bundle généré à l’étape précédente et le répertoire js/ de l’archive dans le répertoire Ressources/public/ (créez le si il n’existe pas encore).

Pas besoin de s’embêter à récupérer toutes les dépendances de Chaplin.js (Backbone.js, Undescore.js, jQuery…) elles sont déjà incluses dans le boilerplate.

Voici la structure que doit avoir le répertoire Ressources/ de votre bundle après la copie des dossiers issus du boilerplate Chaplin :

• coffee/ : code CoffeeScript de votre application, ne sera pas accessible depuis le serveur web
• public/
  • js/ :  code JavaScript compilé de votre application
    • vendor/ : bibliothèques JavaScript tiers utilisées par votre application (dépendances)
    • templates/ : les templates Handlebars.js
• views/ : les templates Twig

Ouvrez un terminal dans le répertoire Ressources/ de votre bundle et lancer la commande suivante :

$ coffee --watch --bare --output public/js/ coffee/

L’argument –watch permet la recompilation automatique en JavaScript des fichiers CoffeeScript dès qu’ils sont modifiés et  –bare supprime l’encapsulation automatique dans une fonction (nécessaire à Chaplin.js).

Installez maintenant les fichiers statiques de notre bundle contenant Chaplin.js dans le répertoire web du projet en utilisant un lien symbolique afin ne pas avoir à répéter la manipulation lors de chaque changement apporté au code du client :

$ php app/console assets:install --symlink

Un peu de ménage

Si ce n’est pas encore fait supprimez les routes de démonstration créez lors de l’installation de Symfony. Il s’agit de _welcome, _demo_secured et _demo dans le fichier app/config/routing_dev.yml.

Supprimez la ligne qui charge le DemoBundle du fichier config/AppKernel.php :

$bundles[] = new Acme\DemoBundle\AcmeDemoBundle();

Supprimez maintenant le DemoBundle lui même (répertoire src/Acme/).

Création de la page chargeant le code JavaScript

Pour initialiser notre SPA, il va nous falloir créer une page qui charge notre application JavaScript.

Commençons par adapter le controlleur par défaut de notre bundle. Remplacez le contenu de  src/Dunglas/ChaplinDemoBundle/Controller/DefaultController.php par :

L’action index assignée à la route / se contente de charger la template index.html.twig. Remplaçons le contenu de Ressources/views/Default/index.html.twig par une version adaptée à Twig et à Symfony de la page index.html fournie avec le boilerplate Chaplin.js :

J’ai apporté quelques petites modifications relatives à Symfony.

Ligne 18 j’utilise Assetic pour charger Require.js au bon endroit dans la structure de répertoires Symfony.

De la même manière ligne 25 j’indique à Chaplin.js ou trouver les fichiers JavaScript compilés.

Ligne 51 si l’application est en mod développement je contourne le cache navigateur en passant l’heure actuelle en paramètre GET de tous les fichiers JavaScript chargés afin de ne pas avoir à appuyer frénétiquement sut “Cmd + r” à chaque modification.

Puis ligne 56 je passe en paramètre de notre application je chemin vers la racine de notre projet pour que le Router de Chaplin.js fonctionne toujours même si le projet est en mode développement (fichier app_dev.php) ou que l’on utilise pas l’application par défaut.

Cette modification en entraine d’autres dans le fichier Ressources/coffee/hello_world_application.coffee :

Ligne 12 j’ajoute un constructeur qui prend en paramètre une propriété contenant le chemin relatif vers la racine du projet.

Ligne 31 j’utilise cette propriété pour initialiser le routeur de Chaplin.js

Chargez la page d’accueil de votre application dans en navigateur ou /app_dev.php en mode développement. Si tout est OK vous devez voir apparaitre “Hello World!” en bas de la page.

Symfony, Backbone.js et Chaplin.js sont maintenant installés et configurés pour fonctionner ensembles. Nous avons une bonne base pour construire une application web moderne.

Il faudra tout de même adapté cette template pour charger les fichiers JavaScript optimisés avec r.js en production car comme vous l’aurez remarqué, je n’utilise Assetic, l’excellent gestionnaire d’assets fourni en standard avec Symfony, que pour charger require.js.

La compilation des fichiers Coffee et l’import des modules AMD n’est pas faite par ce biais. Un bundle existe pourtant pour cela, HearsayRequireJSBundle, mais il ne semble plus maintenu et supporte assez mal CoffeeScript. Il m’a semblé plus simple pour ce tutoriel d’utiliser directement require.js et le compilateur CoffeScript.

A la prochaine

Dans le prochain article j’irais un peu plus loin en réutilisant cette installation pour développer un petit moteur de microblogging. Nous réaliserons une API REST compatible avec Backbone.js à l’aide des bundles Symfony FOSRest et JMSSerializer puis je présenterais la partie client s’y connectant bâtie avec Chaplin.js.

Edit : J’ai finalement décidé de réaliser une implémentation de TodoMVC à l’aide Symfony, Backbone et Chaplin.