Déploiement - Knowledge of Laravel

Introduction

Lorsque vous déployez une application Laravel en production, il faut la préparer pour qu’elle fonctionne le plus efficacement possible. Ce guide couvre les points essentiels d’un déploiement en production fiable.

Flux de déploiement

Prérequis serveur

Le framework Laravel a les prérequis système suivants. PHP 8.3 ou supérieur et les extensions PHP ci-dessous sont requises.

Extension	Description
Ctype	Contrôle des types de caractères
cURL	Communication HTTP
DOM	Manipulation DOM de XML/HTML
Fileinfo	Détection des types MIME
Filter	Filtrage des données
Hash	Fonctions de hachage
Mbstring	Traitement des chaînes multi-octets
OpenSSL	Chiffrement
PCRE	Expressions régulières
PDO	Connexion à la base de données
Session	Gestion des sessions
Tokenizer	Analyse des tokens PHP
XML	Traitement XML

Configuration serveur

Nginx

Si vous utilisez Nginx, basez-vous sur la configuration suivante. Il est essentiel de rediriger toutes les requêtes vers public/index.php. Ne déplacez pas index.php à la racine du projet, ce qui exposerait des fichiers de configuration sensibles.

server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    root /srv/example.com/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

FrankenPHP

FrankenPHP est un serveur d’applications PHP moderne écrit en Go. Vous pouvez démarrer votre application Laravel avec cette seule commande.

frankenphp php-server -r public/

Pour des fonctionnalités avancées telles que HTTP/3, la compression moderne, l’intégration avec Laravel Octane ou la mise en binaire autonome, consultez la documentation Laravel de FrankenPHP.

Permissions des répertoires

Laravel a besoin d’écrire dans bootstrap/cache et storage. Configurez les permissions pour que l’utilisateur du serveur web puisse y écrire.

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

Optimisation

Lors du déploiement en production, mettez en cache la configuration, les événements, les routes et les vues pour améliorer les performances. La commande optimize effectue tout cela en une fois.

php artisan optimize

Pour vider les caches, utilisez optimize:clear.

php artisan optimize:clear

Commandes d’optimisation individuelles

optimize regroupe les commandes suivantes, exécutables séparément si besoin.

Commande	Description
`php artisan config:cache`	Fusionne les fichiers de configuration en un seul fichier mis en cache
`php artisan event:cache`	Met en cache le mapping événement → listener
`php artisan route:cache`	Met en cache les définitions de routes pour accélérer leur enregistrement
`php artisan view:cache`	Précompile les vues Blade pour accélérer les requêtes

Après avoir exécuté config:cache, n’appelez env() qu’à l’intérieur des fichiers de configuration. Une fois le cache généré, le fichier .env n’est plus lu, et env() renvoie null en dehors des fichiers de configuration.

Rechargement des services

Après un déploiement, les services longue durée comme les queue workers, Laravel Reverb ou Laravel Octane doivent être redémarrés pour utiliser le nouveau code.

php artisan reload

Cette commande arrête les services rechargeables. Configurez votre superviseur de processus (Supervisor, par exemple) pour les redémarrer automatiquement.

Si vous utilisez Laravel Cloud, le rechargement gracieux de tous les services est géré automatiquement ; la commande reload n’est pas nécessaire.

Mode debug

L’option debug de config/app.php contrôle le niveau d’information d’erreur affiché à l’utilisateur. Par défaut, elle prend la valeur de la variable APP_DEBUG du fichier .env.

En production, APP_DEBUG doit obligatoirement être à false. Si APP_DEBUG=true reste actif en production, des informations sensibles (connexion base de données, clés secrètes) risquent d’être exposées aux utilisateurs.

# .env (production)
APP_DEBUG=false

Route de health check

Laravel inclut une route de health check intégrée pour surveiller l’état de l’application. Elle s’intègre avec les moniteurs d’uptime, les load balancers ou des systèmes d’orchestration comme Kubernetes. Par défaut, l’endpoint /up est fourni : il retourne 200 si l’application démarre correctement, et 500 en cas d’exception au démarrage. L’URI peut être personnalisé dans bootstrap/app.php.

->withRouting(
    web: __DIR__.'/../routes/web.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/status', // Par défaut /up
)

À chaque requête sur cette route, l’événement Illuminate\Foundation\Events\DiagnosingHealth est déclenché, ce qui vous permet d’ajouter des vérifications supplémentaires (base de données, cache…) via des listeners.

Déployer avec Laravel Cloud ou Forge

Laravel Cloud

Si vous cherchez une plateforme de déploiement entièrement managée avec auto-scaling, Laravel Cloud est la solution. C’est un PaaS optimisé pour Laravel offrant compute managé, base de données, cache et stockage objet. Réglée directement par l’équipe Laravel, elle s’intègre parfaitement au framework.

Laravel Forge

Si vous préférez gérer vous-même votre serveur sans configurer manuellement Nginx, MySQL et autres services, Laravel Forge est très utile. Il crée des serveurs sur les principaux fournisseurs cloud (DigitalOcean, Linode, AWS…) et installe et gère automatiquement Nginx, MySQL, Redis, Memcached, Beanstalk, etc.

Prochaines étapes

Déploiement — Documentation officielle

Consultez la documentation officielle pour les derniers détails de configuration de déploiement.

​Introduction

​Flux de déploiement

​Prérequis serveur

​Configuration serveur

​Nginx

​FrankenPHP

​Permissions des répertoires

​Optimisation

​Commandes d’optimisation individuelles

​Rechargement des services

​Mode debug

​Route de health check

​Déployer avec Laravel Cloud ou Forge

​Laravel Cloud

​Laravel Forge

​Prochaines étapes

Déploiement — Documentation officielle

Introduction

Flux de déploiement

Prérequis serveur

Configuration serveur

Nginx

FrankenPHP

Permissions des répertoires

Optimisation

Commandes d’optimisation individuelles

Rechargement des services

Mode debug

Route de health check

Déployer avec Laravel Cloud ou Forge

Laravel Cloud

Laravel Forge

Prochaines étapes