Tour d'horizon de la structure d'un projet Symfony

Les fondations de votre application : les répertoires clés à la racine

Lorsqu'on aborde un nouveau projet Symfony, l'une des premières étapes pour se sentir à l'aise est de comprendre l'organisation de ses fichiers et répertoires. Symfony adopte une structure standardisée, pensée pour la clarté, la maintenabilité et le respect des bonnes pratiques. Une fois que vous aurez saisi le rôle de chaque répertoire principal, naviguer dans votre code deviendra beaucoup plus intuitif.

A la racine de votre projet Symfony fraîchement créé, vous trouverez un ensemble de dossiers et de fichiers. Chacun a une fonction bien définie. Passons en revue les plus importants :

Le répertoire `public/` : le point d'entrée de votre application

Le répertoire public/ est le seul dossier de votre application qui doit être accessible directement depuis un navigateur web. C'est la racine web de votre projet. On y trouve principalement :

• index.php : C'est le contrôleur frontal (front controller). Toutes les requêtes HTTP adressées à votre application Symfony passent par ce fichier unique. Il initialise le noyau de Symfony (Kernel), traite la requête et renvoie la réponse. Vous n'aurez que très rarement besoin de modifier ce fichier.
• Assets : C'est également dans le répertoire public/ (ou ses sous-répertoires) que vous placerez vos ressources statiques (assets) telles que les feuilles de style CSS, les fichiers JavaScript, les images, les polices de caractères, etc. Si vous utilisez Symfony Encore (un wrapper pour Webpack), les assets compilés seront généralement placés dans un sous-répertoire comme public/build/.

La configuration de votre serveur web (Apache, Nginx) doit pointer vers ce répertoire public/ comme racine du site, et non vers la racine du projet lui-même. Cela constitue une mesure de sécurité importante, car cela empêche l'accès direct aux fichiers de configuration ou au code source de votre application depuis le web.

Le répertoire `src/` : le coeur de votre code métier

Le répertoire src/ (source) est l'endroit où vous allez passer le plus clair de votre temps. Il contient tout le code PHP spécifique à votre application. Par convention, et grâce à l'autoloading de Composer (PSR-4), les classes que vous créez ici seront automatiquement disponibles sous le namespace App\. Voici quelques sous-répertoires courants que vous trouverez ou créerez dans src/ :

• Controller/ : Contient vos classes de contrôleurs. Chaque contrôleur regroupe des actions (méthodes publiques) qui répondent à des requêtes spécifiques, interagissent avec le modèle et renvoient des réponses (souvent en rendant un template).
• Entity/ : Si vous utilisez Doctrine ORM (ce qui est le cas par défaut avec l'option --webapp), ce répertoire hébergera vos classes d'entités. Une entité est un objet PHP qui représente une ligne dans une table de votre base de données.
• Repository/ : Egalement lié à Doctrine, ce dossier contient les classes de repositories. Un repository est une classe spécialisée dans la récupération d'entités d'un type particulier depuis la base de données. C'est ici que vous écrirez vos requêtes DQL (Doctrine Query Language) personnalisées.
• Form/ : Pour vos classes de types de formulaires (Form Types). Symfony fournit un composant puissant pour créer, gérer et valider des formulaires HTML.
• Service/ (ou d'autres noms comme Util/, Manager/) : Pour vos classes de services. Un service est une classe PHP qui effectue une tâche spécifique et réutilisable, comme envoyer un email, calculer une valeur complexe, ou interagir avec une API externe. La logique métier importante devrait résider dans des services plutôt que directement dans les contrôleurs.
• Kernel.php : C'est la classe principale du noyau de votre application Symfony. Elle est responsable de la configuration et du traitement des requêtes. Vous n'aurez généralement pas besoin de la modifier souvent, sauf pour des configurations avancées.

L'organisation à l'intérieur de src/ est flexible. Vous pouvez créer d'autres sous-répertoires pour structurer votre code de manière logique en fonction des domaines fonctionnels de votre application.

Le répertoire `config/` : la tour de contrôle de votre application

Comme son nom l'indique, le répertoire config/ centralise toute la configuration de votre application Symfony. Les fichiers de configuration sont principalement au format YAML (.yaml ou .yml), bien que PHP et XML soient également supportés. Vous y trouverez :

• routes/ : Contient les fichiers de configuration des routes. Bien que la définition des routes via des attributs PHP directement dans les contrôleurs soit la méthode la plus courante aujourd'hui, vous pouvez toujours définir des routes en YAML, XML ou PHP dans ce répertoire.
• packages/ : Ce sous-répertoire contient des fichiers de configuration spécifiques à chaque bundle (paquet) installé dans votre application. Par exemple, doctrine.yaml configure Doctrine, twig.yaml configure Twig, security.yaml configure le composant de sécurité. Ces fichiers sont souvent créés et pré-configurés automatiquement lorsque vous installez un nouveau paquet grâce à Symfony Flex.
• services.yaml : Un fichier clé pour définir et configurer vos propres services et pour gérer l'injection de dépendances. Symfony utilise un conteneur de services puissant qui gère l'instanciation et la configuration des objets (services) de votre application. L'autowiring et l'autoconfiguration simplifient grandement ce fichier, mais vous pourriez avoir besoin de le modifier pour des configurations plus spécifiques.
• bundles.php : Un fichier PHP qui retourne un tableau listant tous les bundles qui doivent être chargés par votre application et dans quel environnement (dev, prod, test). Ce fichier est généralement géré automatiquement par Symfony Flex lorsque vous ajoutez ou retirez des bundles via Composer.
• routes.yaml (ou routes.php, routes.xml) : Fichier principal qui peut importer d'autres fichiers de configuration de routes.
• D'autres fichiers comme validator/ pour la configuration de la validation, etc.

Le répertoire `templates/` : l'atelier de vos interfaces utilisateur

Le répertoire templates/ est l'endroit où vous stockerez tous vos fichiers de templates. Symfony utilise par défaut le moteur de templates Twig, qui offre une syntaxe concise et puissante pour générer du HTML (ou d'autres formats) dynamiquement. A l'intérieur de templates/, vous trouverez généralement :

• base.html.twig : Un fichier de layout (gabarit) de base qui définit la structure HTML commune à toutes (ou la plupart) les pages de votre site (comme le , la navigation, le pied de page). Les autres templates hériteront de ce fichier de base et surchargeront des blocs spécifiques ({% block %}).
• Sous-répertoires par contrôleur ou fonctionnalité : Il est courant d'organiser les templates dans des sous-dossiers portant le nom des contrôleurs auxquels ils sont associés (par exemple, templates/article/ pour les templates gérés par ArticleController) ou par domaine fonctionnel.

L'utilisation de Twig permet de séparer clairement la logique de présentation (comment les données sont affichées) de la logique applicative (comment les données sont traitées), conformément au principe MVC.

Autres répertoires et fichiers importants

Plusieurs autres répertoires et fichiers jouent un rôle important :

• bin/ : Contient le script console. C'est l'exécutable que vous utilisez pour lancer les commandes Symfony en ligne de commande (par exemple, php bin/console list, php bin/console make:entity, php bin/console cache:clear).
• var/ : Ce répertoire est utilisé par Symfony pour stocker les fichiers générés dynamiquement qui ne font pas partie de votre code source versionné.
  • cache/ : Contient les fichiers de cache compilés par Symfony (configuration, routes, templates Twig, etc.) pour améliorer les performances. Ce répertoire est spécifique à chaque environnement (dev, prod).
  • log/ : Contient les fichiers de logs de votre application (par exemple, dev.log, prod.log). C'est un endroit crucial pour le débogage.
  Ce répertoire doit être inscriptible par le processus de votre serveur web. Il est généralement listé dans votre fichier .gitignore.
• vendor/ : Ce répertoire est géré par Composer. Il contient tous les paquets tiers (y compris Symfony lui-même et ses composants) que votre projet utilise comme dépendances. Vous ne devez jamais modifier manuellement le contenu de ce répertoire. Il est également typiquement ignoré par Git, car les dépendances peuvent être réinstallées à tout moment avec composer install en se basant sur le fichier composer.lock.
• migrations/ : Si vous utilisez Doctrine Migrations (installé avec --webapp), ce répertoire contiendra les classes PHP générées pour chaque migration de base de données. Ces fichiers décrivent les changements à appliquer au schéma de votre base de données.
• tests/ : Destiné à héberger vos tests unitaires et fonctionnels, écrits avec des outils comme PHPUnit.
• composer.json : Le fichier de configuration de Composer qui liste les dépendances directes de votre projet et d'autres métadonnées.
• composer.lock : Ce fichier est généré par Composer et enregistre les versions exactes de chaque paquet installé. Il garantit que tous les développeurs et tous les environnements (développement, test, production) utilisent exactement les mêmes versions des dépendances, assurant la reproductibilité des builds. Ce fichier doit être versionné.
• symfony.lock : Utilisé par Symfony Flex pour gérer les "recettes" (configurations par défaut pour les paquets). Ce fichier doit également être versionné.
• .env, .env.local, .env.test, etc. : Fichiers utilisés pour définir les variables d'environnement (identifiants de base de données, clés API, modes de débogage, etc.). .env contient des valeurs par défaut et est versionné. .env.local (qui doit être dans .gitignore) surcharge ces valeurs pour votre environnement local spécifique et ne doit pas être versionné car il peut contenir des informations sensibles.

Comprendre cette structure est une étape clé pour maîtriser Symfony. Elle peut sembler intimidante au début, mais vous verrez rapidement qu'elle est logique et qu'elle contribue grandement à l'efficacité du développement.