Objectifs

• ✅ Gérer et installer un gestionnaire de dépendances avec Node
• ✅ Configurer Webpack Encore

Introduction

Dans les quêtes précédentes, tu as installé un nouveau projet Symfony. Les dépendances PHP du framework ont été installées avec composer, mais il te manque encore quelques outils côté front.

Tu vas y remédier à l’aide de Webpack.

Webpack est un outil apportant beaucoup de fonctionnalités pour charger et traiter automatiquement les assets. Il permet, entre autres, de :

• compiler tous les fichiers JS (les tiens ou les librairies externes) en un seul fichier, en optimisant les éventuelles duplications de code
• automatiser la compilation du SCSS vers le CSS
• minifier automatiquement les fichiers pour la production (gain de performance)

...et plein d’autres choses !

Webpack est extrêmement utilisé dans la communauté JavaScript, mais la gestion des assets est également une problématique au niveau de PHP, notamment sur de gros projets. S'il existe d’autres outils permettant d’améliorer le workflow de traitement des assets (grunt, gulp, bower…), Webpack est actuellement le plus populaire.

Webpack c’est bien, mais c’est tout de même assez complexe, surtout pour des développeurs n’ayant pas l’habitude de travailler en JS. C’est pour cela que Symfony propose Webpack Encore, une librairie permettant de faciliter la configuration de Webpack et son intégration au sein de Symfony.

Sommaire

Installation du module Symfony Encore

Pour installer Webpack encore, lance simplement via composer :

bash

composer require symfony/webpack-encore-bundle

Un fichier webpack.config.js a été créé, ainsi qu'un répertoire assets/ à la racine du projet (où tu placeras maintenant tous tes assets (CSS, JS, fonts, images statiques…). Mais avant d'aller plus loin, il faut équiper ta machine.

Installation des outils Javascript

À toi de jouer !

Sélectionne l'onglet correspondant à ton OS ci-dessous et suis les instructions indiquées.

Installation des dépendances du projet

💻 Ça y est, tu as tous tes outils, alors c'est parti ! Avec un terminal, déplace-toi à la racine de ton projet Wild Series et lance la commande :

yarn install

Cette commande (équivalente d'un composer install) va télécharger Encore et ses propres dépendances dans le dossier node_modules/ à la racine de ton projet. Ce répertoire est l'équivalent de vendor/ pour Composer. Par conséquent, tu l'auras compris, il ne faudra jamais versionner node_modules ni le modifier. Heureusement pour toi, à l’installation via composer (et donc via flex), le .gitignore de ton projet a déjà été mis à jour en conséquence. Le fichier webpack.config.js généré à la racine du projet contient toute la configuration de Webpack. Par défaut, un certain nombre d’options sont déjà activées. Tu seras ensuite amené à le modifier légèrement pour personnaliser ton projet en fonction de tes besoins. Ouvre le fichier, voici quelques explications rapides des options disponibles par défaut :

• setOutputPath() définit le chemin de sortie de tes fichiers. Ici, ce sera dans un dossier public/build/. Webpack va en effet compiler tes assets et les déplacer ici ; Ils seront donc bien accessibles par le navigateur puisque situés dans le dossier public/. Le dossier build/ ne doit cependant pas être versionné, mais rassure-toi, Symfony l'a déjà ajouté dans son .gitignore.

• addEntry() définit le ou les points d'entrée de ton application. Les frameworks Javascript comme React, Vue ou Angular, favorisent la création de sites à un seul point d'entrée (Single Page Application ou S.P.A.), qui n'auront qu'un unique fichier JS en entrée. Les sites créés via des frameworks, comme Symfony, favorisent quant à eux les M.P.A (Multiple Pages Application), qui pourront avoir un fichier JS par page (car il serait inutile de charger du code JS non utilisé sur la page). Dans tes projets, tu vas sans doute être amené à créer plusieurs entrées (avec .addEntry()), une par fichier JS/CSS, que tu vas vouloir utiliser.

• cleanupOutputBeforeBuild() supprime les précédents fichiers générés par Webpack avant de builder. En d'autres termes, à chaque fois que Encore va être appelé pour générer les assets, il va au préalable vider public/build/ avant de réécrire les nouveaux fichiers à cet endroit. C'est pour cela que tu ne dois jamais modifier les fichiers compilés se trouvant dans le dossier build/, car tes modifications seraient écrasées dès le prochain appel à Encore.

• enableBuildNotifications() active des notifications système quand Webpack a réussi à compiler ou quand 'il y a des erreurs; tu verras donc un petit message apparaître sur ton écran.

• enableVersioning permet d’activer certaines fonctionnalités quand le projet se trouve en production (minification des assets, versionning des fichiers, etc).

Utilisation de Webpack Encore

💻 Rends-toi dans le dossier assets/. Tu verras qu’il contient déjà des dossiers et fichiers, dont un fichier app.js, et un sous dossier styles/ avec un app.css. 💻 Modifie le fichier app.css pour ajouter par exemple un fond rouge au body (tu remettras bien entendu de la couleur de ton choix par la suite). Note que la modification ne sera visible qu'après avoir lancé Webpack, à partir du moment où tu reviendras sur ce que tu as fait lors de la quête précédente ;-)

💻 Ajoute dans ce fichier app.js, un message de test (que tu effaceras pas la suite)

console.log('Hello Webpack Encore !')

Lancer Webpack

Pour lancer Webpack, utilise une de ces lignes de commandes selon tes besoins (à lancer à la racine du projet) :

yarn watch

Compile et observe les changements. En d'autres termes, Webpack surveille en continu le dossier assets/ et recompile à la volée les assets dès qu'il y détecte la moindre modification sur les fichiers css, scss et js.

yarn dev-server

Ici, un serveur virtuel est utilisé pour compiler et servir les fichiers directement depuis la mémoire plutôt que depuis un dossier build. Cela permet l'utilisation du HMR (Hot Module Reload), qui recharge automatiquement ton navigateur quand tu modifies tes assets (fichier CSS ou JS). Pratique lors du développement !

yarn build

Compile les assets pour un environnement de production (les fichiers sont notamment minifiés pour en limiter la taille).

Quelle que soit la commande choisie, cela a pour effet de compiler les fichiers contenus dans assets/ et générer les fichiers finaux, utilisés par ton projet. Le dossier assets/ n’étant pas directement accessible par le navigateur, les fichiers sont générés par Webpack dans le dossier public/build/. Par exemple, tu travailleras sur un fichier app.scss dans assets/ et celui-ci sera compilé en un fichier app.css dans le répertoire /public/build.

Pour intégrer ces fichiers générés par Encore dans Symfony, il faudrait ajouter les chemins dans le HTML du fichier base.html.twig comme ceci par exemple (☝️ mais ne le fais pas) :

<link rel="stylesheet" href="/build/app.css">
<script src="/build/app.js"></script>

Eh oui, si tu choisis de modifier par exemple le setOutputPath de ton fichier webpack.config.js, tu devras ensuite reprendre à la main tous les chemins vers tes assets qui ne seraient plus dans le dossier build/. Pour pallier ce problème (et gérer également d’autres cas plus complexes, automatiquement), un helper Twig est disponible pour charger tes CSS et JS, respectivement {{ encore_entry_link_tags('app') }} et {{ encore_entry_script_tags('app') }} ou le app est le nom donné à ton fichier, sans l’extension .css ou .js

Voilà pourquoi tu trouves les blocs ci-dessous dans le fichier base.html.twig.

{% block stylesheets %}
    {{ encore_entry_link_tags('app') }}
{% endblock %}

{% block javascripts %}
    {{ encore_entry_script_tags('app') }}
{% endblock %}

[OPTIONNEL] Si tu souhaites que le HMR s'exécute également quand tu modifies un fichier Twig, ajoute les quelques lignes ci-dessous à ton fichier webpack.config.js en prenant soin de retirer au préalable la toute dernière ligne ~module.exports = Encore.getWebpackConfig();~

//supprime la dernière ligne
// module.exports = Encore.getWebpackConfig();

// et remplace par ceci
const fullConfig = Encore.getWebpackConfig();
fullConfig.devServer = {
    watchFiles: {
        paths: ['templates/**/*.html.twig'],
    },
};
module.exports = fullConfig;

Tu trouveras encore plus d'explications et d'options sur la documentation de Webpack.

Retour sur la quête précédente

Avant d'aller plus loin, tu vas maintenant pouvoir mettre à jour ce que tu as fait sur la quête précédente avec ces nouveaux équipements et disposer ainsi de tes assets. Ouvre ton fichier templates/program/index.html.twig et modifie-le pour ceci :

{% extends 'base.html.twig' %}

{% block title %}Wild Series{% endblock %}

{% block body %}
<h1>{{ website }} index</h1>
{% endblock %}

Profites-en pour modifier aussi ta page d'accueil sur le même principe. L'idée ici, tu l'auras compris, est de faire hériter tes templates du fichier base.html.twig qui fait appel à ces fameux assets.

Dans ta console navigateur, tu devrais voir apparaître un message 'Hello Webpack Encore!'. Sur ton navigateur, les pages doivent toutes avoir un fond rouge.

Bravo ! Webpack avec Symfony fonctionne correctement !

Gestion des images

Les images font également partie des assets (on parle bien ici des images "décoratives" de ton site et non les fichiers uploadés par l'utilisateur). Ainsi, tu peux créer un sous-dossier images/ dans assets/. Pour que ces images soient buildées par webpack, il faut rajouter quelques lignes de configuration, que tu trouveras dans cette partie de la documentation : https://symfony.com/doc/current/frontend/encore/copy-files.html.

Ensuite, pour faire référence à ces images depuis Twig, utilise le helper :

<img src="{{ asset('build/path_to_image.png') }}" alt=""/>

Installation de librairies tierces avec Webpack Encore

Tu vas avoir besoin de charger un certain nombre de librairies dans tes projets, par exemple Bootstrap (cette fois-ci, on parle bien du framework CSS 🤪) et pourquoi pas un compilateur SCSS. Cela tombe bien, Encore possède des documentations ou des options par défaut pour ces différentes librairies.

Par exemple, pour utiliser SCSS dans ton projet, il te suffit de décommenter l’option .enableSassLoader() dans le fichier webpack.config.js.

Si tu lances Webpack juste après, tu vas avoir un message d’erreur t’invitant à installer les dépendances requises. Il faudra donc taper dans ton terminal :

yarn add sass-loader@latest sass --dev

Pour tester, renomme le fichier assets/styles/app.css en assets/styles/app.scss, puis modifie le fichier assets/app.js pour qu’il charge le fichier app.scss et non plus app.css:

Relance le build de Webpack, par exemple avec la commande

yarn watch

afin de voir si cela fonctionne. Normalement, un fichier app.css a dû se créer dans le dossier build/. Oui, rappelle-toi, la compilation du SCSS donne un fichier CSS qui, lui, va être interprétable par ton navigateur.

Tu peux aussi utiliser la commande

yarn dev-server

mais ne sois pas surpris si tu ne vois pas tes fichiers dans le dossier /build car ils vont être enregistrés ailleurs, dans un dossier temporaire utile au rafraîchissement du navigateur.

Modifie la couleur de fond en bleu dans le fichier SCSS. Puisque tu es en mode dev-server, la modification est détectée et la compilation se fait à la volée (en quelques secondes). Ton navigateur est mis à jour automatiquement, le fond doit maintenant être bleu ! Tu pourras ensuite enlever ce style douteux et mettre le tien à la place ;-)

💪 Challenge

C’est le moment de donner de la couleur et de la vie à ton Wild Series ! Grâce à Webpack et Bootstrap (on parle bien du Framework web ce coup-ci !).

• Installe et configure Webpack Encore pour ton projet Wild Series.
• Charge SASS loader.
• Intègre le framework Bootstrap (en suivant la ressource).

• Crée une navbar dans un fichier _navbar.html.twig et inclus ce fichier dans une balise <header> de ton fichier base.html.twig, afin que celle-ci s’affiche sur toutes les pages. Ajoute un simple lien permettant de revenir sur la page d’accueil (Utilise une navbar Bootstrap)
• Surcharge les variables de couleurs primaires et secondaires en te basant sur ton styleguide.
• Modifie le projet pour que tous tes assets (JS, CSS) soient dans le dossier assets/, et lance le build de Webpack Encore.
• Modifie tes appels aux assets pour que ton site utilise ceux générés dans ton dossier build/.
• Héberge le projet sur Github avec tous les fichiers non suivis dans le .gitignore.
• Bonus : ajoute une favicon de ton choix dans le dossier images et appelle là. Hint : https://alsacreations.com/astuce/lire/59-icon-link-rel-favicon-ico-navigateur.html

Critères de validation

Symfony Encore est bien intégré dans le projet.

• Bootstrap est bien chargé dans tes pages (regarde les sources HTML et vérifie que tu n'as pas de 404 sur tes fichiers dans l'inspecteur > "Réseau").
• La navbar de Bootstrap s'affiche correctement sur tes pages