Structure des dossiers d'un projet Laravel : Les répertoires clés

Comprendre l'organisation : une visite guidée des fondations de votre projet

Après avoir créé votre premier projet Laravel, la première chose que vous remarquerez est la structure de dossiers et de fichiers générée. Au premier abord, cela peut sembler un peu intimidant en raison du nombre de répertoires. Cependant, cette organisation est logique et conçue pour favoriser la clarté et la maintenabilité de votre code. Chaque dossier a un rôle bien défini. Comprendre cette structure est essentiel pour naviguer efficacement dans votre projet et savoir où placer vos différents fichiers et logiques métier.

Dans cette section, nous allons explorer les répertoires les plus importants d'un projet Laravel typique. Bien que nous n'allions pas détailler chaque sous-dossier et fichier, vous aurez une bonne compréhension de l'architecture globale. N'oubliez pas que la documentation officielle de Laravel reste votre meilleure alliée pour des informations plus approfondies.

Ouvrez le dossier de votre projet nouvellement créé dans votre éditeur de code préféré et commençons cette visite guidée.

Le coeur de l'application : le répertoire `app`

Le répertoire app est, comme son nom l'indique, le coeur de votre application. C'est ici que réside la majorité de votre code spécifique au projet. Vous y trouverez plusieurs sous-dossiers importants :

• Console : Contient vos commandes Artisan personnalisées. Le fichier Kernel.php dans ce dossier vous permet d'enregistrer vos commandes et de définir vos tâches planifiées (cron jobs).
• Exceptions : Contient le gestionnaire d'exceptions de votre application (Handler.php). C'est ici que vous pouvez personnaliser la manière dont les exceptions sont loguées ou rendues à l'utilisateur.
• Http : C'est l'un des dossiers les plus utilisés. Il contient :
  • Controllers : Vos classes de contrôleurs, qui gèrent la logique des requêtes HTTP.
  • Middleware : Les middlewares permettent de filtrer les requêtes HTTP entrant dans votre application (par exemple, pour l'authentification, la vérification CSRF, etc.).
  • Kernel.php : Enregistre les middlewares globaux et les groupes de middlewares.
• Models : C'est ici que vous placerez vos modèles Eloquent, qui représentent les données de votre application et interagissent avec la base de données. Par défaut, les nouveaux modèles créés avec php artisan make:model peuvent apparaître directement dans app/ ou dans app/Models/ selon la version de Laravel ou si le dossier existe déjà. Il est courant de les organiser dans app/Models.
• Providers : Les fournisseurs de services (Service Providers) sont au coeur du démarrage (bootstrapping) d'une application Laravel. Ils enregistrent les liaisons dans le conteneur de services, enregistrent les écouteurs d'événements, les middlewares, les routes, etc. Vous y trouverez des fournisseurs par défaut comme AppServiceProvider.php, AuthServiceProvider.php, EventServiceProvider.php, et RouteServiceProvider.php.

Essentiellement, tout ce qui concerne la logique métier, les règles de validation, la manipulation des données, et la gestion des requêtes de votre application se trouve dans le répertoire app.

Démarrage et configuration : `bootstrap` et `config`

Le répertoire bootstrap contient quelques fichiers qui démarrent le framework et configurent l'autochargement. Vous ne modifierez généralement pas souvent les fichiers de ce répertoire.

• app.php : C'est le script qui charge (bootstrap) le framework.
• cache/ : Ce dossier contient les fichiers générés par le framework pour l'optimisation des performances, comme les fichiers de cache de configuration et de routes. Il est généralement préférable de ne pas versionner (via Git) le contenu de ce dossier.

Le répertoire config, comme son nom l'indique, contient tous les fichiers de configuration de votre application. Chaque fichier correspond à un aspect spécifique de la configuration (base de données, mail, cache, session, files d'attente, services tiers, etc.). Par exemple, config/database.php gère les connexions à la base de données, config/mail.php configure l'envoi d'e-mails. Vous passerez du temps ici pour adapter le comportement de Laravel à vos besoins. Ces fichiers sont bien commentés et utilisent largement les variables d'environnement définies dans votre fichier .env pour permettre des configurations différentes selon les environnements (développement, production, etc.).

Données et accès public : `database` et `public`

Le répertoire database abrite tout ce qui concerne le schéma de votre base de données et ses données initiales :

• factories : Les factories (usines à modèles) vous permettent de générer facilement de fausses données pour vos modèles Eloquent, très utiles pour les tests ou pour peupler votre base de données en développement.
• migrations : Les migrations sont comme un système de contrôle de version pour votre base de données. Elles vous permettent de définir et de modifier le schéma de votre base de données de manière programmatique et reproductible.
• seeders : Les seeders (semeurs) sont des classes utilisées pour peupler votre base de données avec des données initiales ou des données de test.

Le répertoire public est le seul répertoire qui devrait être accessible directement depuis un navigateur web. Il contient le fichier index.php, qui est le point d'entrée de toutes les requêtes vers votre application. C'est votre "document root" ou "web root". Ce répertoire est également l'endroit où vous placerez vos assets compilés (fichiers CSS, JavaScript, images) qui doivent être accessibles publiquement. Par défaut, vous y trouverez un fichier .htaccess (pour les serveurs Apache) qui aide à router toutes les requêtes vers index.php.

Ressources, routes et stockage : `resources`, `routes` et `storage`

Le répertoire resources contient vos vues, vos assets bruts (non compilés) et vos fichiers de localisation :

• css, js (ou parfois sass, less) : Contiennent vos fichiers CSS, SASS, LESS, JavaScript avant qu'ils ne soient compilés et publiés dans le répertoire public (souvent via Laravel Mix ou Vite).
• lang (ou locales) : Contient les fichiers de langue pour la localisation (internationalisation) de votre application.
• views : C'est ici que résident vos fichiers de templates Blade, qui constituent l'interface utilisateur de votre application.

Le répertoire routes contient toutes les définitions de routes pour votre application. Il est subdivisé en plusieurs fichiers :

• web.php : Pour les routes web, qui sont généralement avec état (utilisent les sessions, la protection CSRF, etc.).
• api.php : Pour les routes d'API, qui sont généralement sans état (stateless) et utilisent des tokens pour l'authentification.
• console.php : Pour définir vos commandes Artisan basées sur des closures.
• channels.php : Pour enregistrer les canaux de diffusion d'événements (broadcasting channels) de votre application.

Le répertoire storage contient les fichiers générés par le framework et votre application, les fichiers de session, les caches, les logs, et les fichiers uploadés par les utilisateurs (s'ils ne sont pas stockés sur un service externe). Il est divisé en plusieurs sous-dossiers :

• app : Peut être utilisé pour stocker des fichiers générés par votre application. Le sous-dossier app/public est souvent utilisé pour les fichiers qui doivent être accessibles publiquement après avoir créé un lien symbolique de public/storage vers storage/app/public (via php artisan storage:link).
• framework : Contient les fichiers générés par le framework (sessions, vues compilées, caches).
• logs : Contient les fichiers de log de votre application (par exemple, laravel.log).

Le contenu de storage (sauf storage/app/public après le lien symbolique) n'est généralement pas destiné à être accessible directement via le web.

Tests et dépendances : `tests` et `vendor`

Le répertoire tests contient vos tests automatisés. Laravel est livré avec un support pour PHPUnit et encourage fortement les tests. Ce dossier est structuré en :

• Feature : Pour les tests d'intégration, qui testent une plus grande partie de votre application, y compris la manière dont plusieurs objets interagissent, ou même une requête HTTP complète.
• Unit : Pour les tests unitaires, qui testent une très petite et isolée partie de votre code (une méthode d'une classe, par exemple).
• Le fichier TestCase.php de base s'y trouve également.

Le répertoire vendor est l'endroit où Composer installe toutes les dépendances de votre projet, y compris Laravel lui-même et toutes les bibliothèques tierces que vous ajoutez. Vous ne devriez jamais modifier directement les fichiers dans le répertoire vendor, car ils seraient écrasés lors de la prochaine mise à jour via Composer. Ce dossier est généralement ignoré par les systèmes de contrôle de version (via .gitignore) car les dépendances peuvent être réinstallées à tout moment en utilisant la commande composer install à partir des informations contenues dans les fichiers composer.json et composer.lock.

Fichiers clés à la racine du projet

Enfin, à la racine de votre projet, vous trouverez plusieurs fichiers importants :

• .env : (Environnement) Ce fichier contient la configuration spécifique à votre environnement (développement local, staging, production). Il n'est généralement pas versionné par Git pour des raisons de sécurité et de spécificité environnementale. Il est copié à partir de .env.example.
• .env.example : Un fichier d'exemple pour .env. Il liste toutes les variables d'environnement que votre application attend.
• .gitattributes et .gitignore : Fichiers de configuration pour Git. .gitignore spécifie les fichiers et dossiers à ignorer par Git (comme /vendor, /node_modules, .env, /storage/*.log, etc.).
• artisan : Le script PHP qui lance l'outil en ligne de commande Artisan.
• composer.json : Le fichier qui déclare les dépendances de votre projet pour Composer, ainsi que d'autres métadonnées.
• composer.lock : Enregistre les versions exactes des paquets qui ont été installés. Cela garantit que tout le monde travaillant sur le projet utilise les mêmes versions de dépendances.
• package.json : Utilisé par npm (Node Package Manager) ou Yarn pour gérer les dépendances JavaScript et CSS si vous utilisez Laravel Mix ou Vite pour la compilation des assets.
• phpunit.xml : Le fichier de configuration pour PHPUnit.
• vite.config.js ou webpack.mix.js : Le fichier de configuration pour Vite ou Laravel Mix, les outils de compilation d'assets front-end de Laravel.

Cette exploration, bien que non exhaustive, devrait vous donner une solide compréhension de la manière dont un projet Laravel est structuré. Avec cette connaissance, vous serez mieux équipé pour développer votre application de manière organisée et efficace.