Structure d'un projet Laravel

Vue d'ensemble de la structure d'un projet Laravel

Laravel est un framework MVC (Modèle-Vue-Contrôleur) qui permet de structurer de manière propre et logique les différents composants d'une application web. Chaque fichier et dossier à la racine d'un projet Laravel a un rôle spécifique, et comprendre cette structure permet de naviguer plus facilement entre les composants et de maintenir un code propre et cohérent.

Fichiers racine du projet Laravel

La structure d'un projet Laravel repose sur plusieurs dossiers et fichiers principaux, chacun ayant une mission bien définie. Voyons d'abord les fichiers qui se trouvent directement à la racine du projet avant de nous attarder sur les dossiers qui structurent l'application.

├── .env              # Configuration de l'environnement : base de données, services externes, etc.
├── .env.example      # Exemple de configuration de l'environnement
├── artisan           # Utilitaire en ligne de commande pour exécuter des tâches Laravel
├── composer.json     # Liste des dépendances PHP du projet
├── package.json      # Liste des dépendances JavaScript du projet
├── phpunit.xml       # Configuration des tests unitaires
├── README.md         # Documentation initiale sur le projet
├── vite.config.js    # Configuration pour Vite, outil de build pour les assets (CSS, JS)

`.env` – Fichier d'environnement

Le fichier .env contient toutes les variables d'environnement nécessaires au bon fonctionnement du projet. C'est ici qu'on spécifie les paramètres comme les informations de connexion à la base de données, la clé d'API de services tiers, ou les paramètres de mail.

Exemple de contenu typique du fichier .env :

APP_NAME=Laravel
APP_ENV=local
APP_KEY=base64:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
DB_CONNECTION=sqlite
DB_DATABASE=database.sqlite

Le fichier .env est essentiel, car il permet de rendre le projet flexible à différents environnements (développement, production) sans modifier le code.

`.env.example` – Exemple de configuration d'environnement

Le fichier .env.example est une version modèle du fichier .env. Il sert de référence pour les développeurs qui veulent configurer le projet sur leur propre machine. Lorsqu'un développeur clone un projet, il peut simplement copier .env.example vers .env et le personnaliser avec les valeurs spécifiques à son environnement.

`artisan` – Console de commande

Le fichier artisan est un script PHP qui permet d'accéder à la console de commande Laravel. Cette console est très utile pour exécuter des tâches variées, comme la création de nouvelles entités (contrôleurs, modèles, etc.), la gestion des migrations de base de données, ou encore l'exécution de tâches planifiées.

Commandes courantes utilisables avec artisan :

php artisan migrate        # Appliquer les migrations de base de données
php artisan serve          # Lancer un serveur local de développement, ne pas l'utiliser si vous avez un logiciel comme Laragon ou Mamp installé qui remplit déjà ce rôle.
php artisan make:controller MyController  # Créer un nouveau contrôleur nommé MyController

L'outil artisan est un des points forts de Laravel, car il permet de faciliter beaucoup de tâches de développement.

`composer.json` – Gestionnaire de dépendances PHP

Ce fichier décrit toutes les dépendances PHP du projet. Composer est l'outil qui permet de gérer ces dépendances. Par exemple, si vous avez besoin d'utiliser une librairie externe, composer.json va la lister, et la commande composer install va installer cette dépendance.

Voici un extrait typique du fichier composer.json :

{
    "require": {
        "php": "^8.0",
        "laravel/framework": "^9.0",
        "fideloper/proxy": "^4.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "app/"
        }
    }
}

Ce fichier est indispensable pour toute mise à jour de dépendances ou pour synchroniser l'environnement de développement avec celui de production.

`package.json` – Gestionnaire de dépendances JavaScript

Le fichier package.json est l'équivalent de composer.json, mais pour les dépendances JavaScript. Laravel utilise souvent des outils JavaScript comme Vue.js ou React pour la partie front-end. Ce fichier permet de lister les bibliothèques JavaScript nécessaires au projet, telles que axios ou lodash.

Exemple d'extrait du fichier package.json :

{
    "devDependencies": {
        "vite": "^4.0.0",
        "laravel-vite-plugin": "^0.7.0"
    },
    "dependencies": {
        "vue": "^3.0.0",
        "axios": "^1.0.0"
    }
}

package.json est essentiel pour gérer les scripts de compilation et les dépendances front-end du projet.

`vite.config.js` – Configuration de Vite

Ce fichier est une configuration pour Vite, qui est utilisé pour le traitement des fichiers CSS et JavaScript. Vite est un outil de build moderne qui remplace Webpack et permet une compilation plus rapide et efficace des assets. Le fichier vite.config.js contient les paramètres de compilation, comme les alias de chemin et les plugins utilisés.

Exemple de contenu de vite.config.js :

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
    ],
});

Ce fichier permet de définir la manière dont les assets sont gérés et compilés lors du développement.

`phpunit.xml` – Configuration des tests

Le fichier phpunit.xml contient la configuration nécessaire pour exécuter les tests unitaires via PHPUnit. Laravel est prééquipé avec PHPUnit pour que les développeurs puissent écrire des tests unitaires sur leurs méthodes et contrôleurs.

Autres fichiers importants

README.md : Un fichier de documentation initiale du projet. Idéalement, il contient des informations sur la façon de configurer et de lancer le projet.

Ces fichiers à la racine sont essentiels pour configurer et exploiter pleinement un projet Laravel. Ils participent à la gestion de l'environnement, de la documentation, des tests, des dépendances et des assets.

Les dossiers principaux du projet Laravel

Laravel organise la structure de son projet en plusieurs dossiers principaux, chacun jouant un rôle spécifique. Cette organisation favorise une séparation claire des responsabilités et permet une évolution maintenable de l'application. Voyons ensemble les dossiers les plus importants et leur utilité.

├── app/                # Contient la logique métier de l'application
├── bootstrap/          # Initialisation du framework
├── config/             # Configuration globale de l'application
├── database/           # Gestion de la base de données (migrations, seeders, etc.)
├── public/             # Point d'entrée de l'application (serveur web)
├── resources/          # Contient les vues, les assets, et les fichiers de localisation
├── routes/             # Définition des routes de l'application
├── storage/            # Stockage des logs, des fichiers, et du cache
├── tests/              # Tests unitaires et fonctionnels
├── vendor/             # Bibliothèques externes installées par Composer

Dossier `app/`

Le dossier app/ est le cœur de l'application. Il contient toute la logique métier et les composants qui structurent l'application en utilisant le modèle MVC. Ce dossier est divisé en plusieurs sous-dossiers :

Http/ : Contient les contrôleurs, les middlewares et les requêtes. Par exemple, le sous-dossier Controllers/ gère la logique de traitement des requêtes des utilisateurs.
Models/ : Contient les modèles, qui représentent les entités de la base de données (par exemple, User.php).
Providers/ : Contient les classes qui servent à lier des services à l'application, comme AppServiceProvider.php.

Exemple de structure :

app/
├── Http/
│   ├── Controllers/    # Logique des contrôleurs
│   ├── Middleware/     # Traitement des requêtes avant les contrôleurs
│   └── Requests/       # Validation des requêtes utilisateur (créé dynamiquement)
├── Models/             # Représentation des entités, ex : User.php
└── Providers/          # Services liés à l'application

Dossier `bootstrap/`

Le dossier bootstrap/ contient le fichier app.php, qui est responsable de charger le framework et de préparer l'application pour l'exécution. Ce dossier ne doit pas être modifié directement, sauf pour des besoins très spécifiques.

Dossier `config/`

Ce dossier regroupe tous les fichiers de configuration de l'application. Chaque aspect de Laravel possède son propre fichier de configuration :

app.php : Contient la configuration générale de l'application (nom, fuseau horaire, langue, etc.).
database.php : Gère la connexion aux bases de données.
mail.php : Configure les paramètres d'envoi de mails.

Exemple d'une partie de app.php :

return [
    'name' => env('APP_NAME', 'Laravel'),
    'env' => env('APP_ENV', 'production'),
    'debug' => (bool) env('APP_DEBUG', false),
    'timezone' => 'UTC',
];

Ces fichiers de configuration permettent d'adapter le comportement de Laravel en fonction des besoins du projet.

Dossier `database/`

Le dossier database/ est destiné à la gestion de la base de données. Il contient :

migrations/ : Définit la structure des tables de la base de données.
seeders/ : Remplit la base avec des données initiales ou de test.
factories/ : Génère des données factices, souvent utilisées pour les tests unitaires.

Structure typique :

database/
├── factories/          # Génération de fausses données
├── migrations/         # Définition des tables de la base de données
└── seeders/            # Remplissage des tables avec des données de test

Dossier `public/`

Le dossier public/ est le point d'entrée du projet. C'est là où se trouve le fichier index.php, qui est la première étape d'exécution de l'application Laravel lorsque les utilisateurs accèdent au site via leur navigateur. Ce dossier contient également les assets publics comme les images et les fichiers JavaScript compilés.

Dossier `resources/`

Le dossier resources/ contient les fichiers de vues, les fichiers CSS et JavaScript non compilés, ainsi que les fichiers de localisation.

views/ : Contient les fichiers Blade (.blade.php), qui sont utilisés pour générer l'interface utilisateur dynamique.
lang/ : Contient les fichiers de localisation pour les traductions de l'application.

Structure :

resources/
├── views/              # Vues Blade pour générer l'interface utilisateur
├── css/                # Fichiers CSS non compilés
├── js/                 # Fichiers JavaScript non compilés
└── lang/               # Localisation et traductions

Dossier `routes/`

Le dossier routes/ est là où les routes de l'application sont définies. Chaque fichier correspond à un groupe de routes :

web.php : Contient les routes qui sont accessibles via le web (interfaces utilisateur).
api.php : Contient les routes destinées à l'API de l'application.

Dossier `storage/`

Ce dossier est utilisé pour stocker tout ce qui est généré par l'application et qui doit être conservé, comme les logs, les sessions, ou encore les fichiers générés par les utilisateurs.

logs/ : Enregistre les logs de l'application.
framework/ : Contient le cache, les sessions, et les fichiers temporaires.

Dossier `tests/`

Le dossier tests/ contient les tests unitaires et fonctionnels de l'application. Laravel est livré avec PHPUnit pour l'écriture des tests. Ce dossier est divisé en plusieurs sous-dossiers :

Feature/ : Contient les tests de fonctionnalités, qui vérifient des aspects larges de l'application, par exemple si une fonctionnalité complète fonctionne comme prévu.
Unit/ : Contient les tests unitaires, qui vérifient des morceaux de code isolés (fonctions, classes).
Browser/ : Peut contenir des tests de navigation (end-to-end) utilisant Laravel Dusk, qui vérifient le comportement de l'application dans un navigateur.
TestCase.php : Ce fichier est la classe de base que tous les tests héritent. Il configure l'environnement de test, les dépendances, et fournit des méthodes utilitaires pour les tests.

Pour une meilleure organisation, il est souvent conseillé de reproduire la structure des dossiers app/ dans tests/ afin de rendre la navigation plus intuitive. Par exemple, un test pour un contrôleur situé dans app/Http/Controllers/ serait placé dans tests/Feature/Http/Controllers/.

Structure typique :

tests/
├── Feature/            # Tests de fonctionnalités
│   ├── Http/           # Tests liés aux contrôleurs HTTP
│   └── ...
├── Unit/               # Tests unitaires
├── Browser/            # Tests de navigation avec Laravel Dusk (optionnel)
└── TestCase.php        # Classe de base pour les tests

Dossiers créés dynamiquement par Laravel

Certains dossiers peuvent être créés automatiquement par Laravel lorsque certaines fonctionnalités sont utilisées :

Requests/ : Ce dossier est créé dans app/Http/ lorsque des form requests sont générés via des commandes Artisan. Les form requests sont utilisés pour la validation des données avant qu'elles n'atteignent les contrôleurs.
Events/ : Ce dossier est créé dans app/ lorsque des événements sont utilisés dans l'application. Les événements permettent de découpler des parties de l'application, par exemple lorsqu'une action (comme la création d'un utilisateur) doit déclencher d'autres processus (comme l'envoi d'un email).
Notifications/ : Ce dossier est créé dans app/ lorsqu'on utilise le système de notifications de Laravel. Les notifications sont souvent utilisées pour informer les utilisateurs par email, SMS, ou d'autres moyens.

Dossiers créés manuellement

Il est courant de créer des dossiers supplémentaires pour organiser des aspects spécifiques de l'application qui ne sont pas prévus par Laravel par défaut. Ces dossiers peuvent être ajoutés manuellement par les développeurs selon les besoins du projet :

Services/ : Ce dossier est généralement créé dans app/ pour y mettre des classes qui font appel à des services externes, tels que des API tierces (par exemple, l'API d'OpenAI, Twilio pour envoyer des SMS, etc.). Créer un dossier Services est une convention courante dans la communauté Laravel pour organiser proprement les appels aux services externes et faciliter la maintenabilité du code.
Autres dossiers : Libre à chaque développeur d'ajouter d'autres dossiers selon les besoins de l'application pour structurer le code de manière logique et efficace.

Dossier `vendor/`

Le dossier vendor/ est généré automatiquement par Composer et contient toutes les bibliothèques externes dont dépend Laravel. Il n'est jamais modifié manuellement.

Synthèse

Ces dossiers sont essentiels pour bien organiser un projet Laravel. Ils permettent de garder une structure cohérente et de maintenir la séparation des responsabilités, ce qui est crucial pour le développement et la maintenabilité d'une application. Les dossiers créés dynamiquement par Laravel et ceux ajoutés manuellement viennent enrichir cette structure en fonction des besoins spécifiques du projet.

Structure d'un projet Laravel

Vue d'ensemble de la structure d'un projet Laravel

Fichiers racine du projet Laravel#

#

.env – Fichier d'environnement#

.env.example – Exemple de configuration d'environnement#

artisan – Console de commande#

composer.json – Gestionnaire de dépendances PHP#

package.json – Gestionnaire de dépendances JavaScript#

vite.config.js – Configuration de Vite#

phpunit.xml – Configuration des tests#

Autres fichiers importants#

Les dossiers principaux du projet Laravel#

Dossier app/#

Dossier bootstrap/#

Dossier config/#

Dossier database/#

Dossier public/#

Dossier resources/#

Dossier routes/#

Dossier storage/#

Dossier tests/#

Dossiers créés dynamiquement par Laravel#

Dossiers créés manuellement#

Dossier vendor/#

Synthèse#