Guide du développeur Symfony 3 pragmatique

Symfony2 est réputé être un framework plutôt facile à prendre en main. En revanche, garder une cohérence d'ensemble dans l’architecture de son projet n'est pas chose aisée. Voici une petite synthèse des choses à retenir. Quelques semaines avant la sortie de Symfony3, il est toujours bon de faire une petite mise au point pragmatique...

Construire son projet Symfony

La structure d'un projet Symfony

Symfony3 pointe le bout de son nez, et Fabien Potencier avait annoncé dans sa feuille de route que la migration d'un Symfony2 vers un Symfony3 se ferait facilement et délicatement. c'est la parfaite occasion pour ouvrir la discussion sur les pratiques de développement d'un projet Symfony.

Une bonne architecture est essentielle pour faciliter l'évolution et la maintenance de son projet. Il est préconisé de définir un nombre restreint de bundle. Vous devez utiliser des "namespace" standards et non typés pour faciliter la réutilisation, le cherry pick du code et simplifier le découpage de votre projet. La construction proposée dans cet article est toujours en débat au sein de la communauté Symfony qui s'oriente, peu à peu, vers une structure sans Bundle.

• AppBundle : Gére la partie Frontend du projet
• AdminBundle : Contient le backoffice

Il n'est pas obligatoire d'avoir un bundle spécifique pour l'administration. Cela dépend en grande partie de la philosophie de votre projet, de votre rigueur, du nombre d'intervenants sur le projet et des interdépendances entre votre FrontOffice et votre BackOffice. Ainsi plus communément, vous pouvez conserver uniquement le bundle App pour votre projet.

Depuis Symfony 3, le cache, les logs et le bootstrap cache seront disposés dans le dossier var/. La console est présente depuis le dossier bin/.

Récapitulatif d’arborescence de base :

• app - les configurations, vues et les assets globales (jquery, boostrap,...);
• bin - les scripts de gestion symfony 3;
• src - les bundles de votre projet;
• var - les logs et le dossier de cache;
• vendor - les bundles (vendors) externes;
• web - les fichiers "publics" de votre projet.

Vos vendors favoris pour votre projet Symfony

Pour certaines fonctionnalités et besoins, l'utilisation de certains bundles existants est recommandée. En effet, si celui-ci est léger et ne réalise qu'une et une seule chose correctement, il permet de s'affranchir d'un développement qui ne sera pas forcément meilleur et générateur de bugs.

Nos bundles "essentiels" :

• Paginator (pagination) : knplabs/knp-paginator-bundle
• Breadcrumb (file d'Ariane) : whiteoctober/breadcrumbs-bundle
• Doctrine extensions : stof/doctrine-extensions-bundle
• Fixtures (données d'initialisation) : doctrine/doctrine-fixtures-bundle

Les recommandés :

• Seo : sonata-project/seo-bundle
• Thumbnails : liip/imagine-bundle
• API Rest: friendsofbundle/rest-bundle

François, de l'équipe Wanadev, avait il y a quelques temps déjà listé quelques bundles intéressants pour l’amorçage d'un projet Symfony. Depuis sa publication, nous avons un peu revu cette liste, mais elle reste globalement bonne pour démarrer !

My bundle is rich

La structuration de votre bundle est plus importante qu'elle en a l'air. En effet, respecter une bonne logique dans l'organisation de votre bundle facilite le développement collaboratif et facilite la maintenance de votre projet. Pour une vision simple et claire, vous pouvez utiliser une sous-arborescence reprenant les grands blocs fonctionnels de votre projet:

Dans le cas d'un bundle administratif fusionné (backoffice dans AppBundle), il est conseillé de mettre en place cette autre arborescence (notre recommandation) :

Voici les principaux dossiers de votre bundle :

Command : Les commandes ou tâches vous permettent d’effectuer des traitements sur votre projet qui sont exécutés directement en ligne de commande. Souvent utilisé pour mettre en place des routines (maintenance de la base de données, système de notification...), vous ne devez pas oublier que n'avez pas de contexte lors de l’exécution de ces scripts et donc pas d'accès "request" par exemple.

Controller : Le controller contient les routers de votre application qui réalise le pont entre la "request" HTTP et la "response" HTTP renvoyée.

DataFixtures : Stocke les fixtures du projet (jeu de données).

Entity : Les déclarations de vos entités.

Repository : Les Repository gèrent les requêtes DQL ou SQL liées aux entités.

Listener : Les Listeners vous permettent d'exécuter du code lors d'un événement du déroulement des pages.

Form : Les formulaires de votre projet.

Manager : Le code métier ou des traitements spécifiques. Les managers permettent de centraliser du code qui pourrait être appelé par plusieurs controllers par exemple.

Resources :

• config : Ce dossier stocke vos déclarations de service, les paramétrages et la configuration de votre bundle au format yml (notre recommandation) ou xml.
• public :  Contient les assets comme vos images, vos feuilles de style et vos JavaScripts. Avec la gestion des assets Symfony, les éléments contenus dans ce dossier sont accessibles par tous.
• views : pour gérer facilement vos  templates, vous devez respecter  l'arborescence de vos controllers. Pour le nommage des fichiers twig, simplifiez-vous la vie au maximum : index.html.twig, edit.html.twig, show.html.twig... Si votre arborescence est bien conçue, ne rajoutez pas le nom de l'entité associé : show_post.html.twig. Pour améliorer la lisibilité de ce dossier, ajouter des "_" devant vos partials : _items.html.twig

Pour votre gestion des assets, vous pouvez utiliser des outils comme GULP, GRUNT pour gérer des tâches de compilation et de minification des fichiers JS ou CSS. Malgré tout, Assetic proposé par défaut reste une solution. Nous conseillons aussi d'utiliser un gestionnaire de librairies comme BOWER. N'hésitez pas à séparer vos ressources spécifiques de chacune de vos pages pour ne pas surcharger vos fichiers JS et CSS génériques. Pour une écriture CSS scalable et optimisée, nous préconisons d'utiliser SASS ou LESS.

Gestion des utilisateurs

Nous déconseillons l’utilisation d'un bundle spécifique pour gérer vos utilisateurs. Pour une meilleure maitrise des mécanismes et des formulaires, il est préférable d’utiliser le système natif symfony. Les possibilités offertes par défaut dans Symfony permettent de réaliser rapidement (et avec plus de maitrise) les mécanismes "utilisateur" de base.

Bonnes pratiques

Nous publierons prochainement un article qui traitera des bonnes pratiques dans l'écriture du code pour Symfony.

Retrouvez dès à présent des ressources complémentaires pour améliorer vos pratiques :

http://symfony.com/doc/current/quick_tour/the_architecture.html http://elnur.pro/symfony-without-bundles/ https://www.wanadev.fr/category/symfony2-2/

Enfin, nous vous invitons à réagir à cet article, en nous partageant votre conception des bonnes pratiques d'architecture pour la bienséance d'un développement d'un projet Symfony. De notre côté, on se lance sur des projets Symfony3 ;) ! Racontez nous vos anecdotes !