> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Déploiement

> Guide de configuration, d'optimisation et d'exploitation pour déployer une application Laravel en production.

## 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

```mermaid theme={null}
flowchart TD
    A["Push du code"] --> B["php artisan optimize"]
    B --> C["Distribution via Nginx / FrankenPHP"]
    C --> D["php artisan reload"]
    D --> E["Redémarrage des queue workers,<br>Reverb / Octane"]
    E --> F["Déploiement terminé"]
```

## 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.

```nginx theme={null}
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](https://frankenphp.dev/) est un serveur d'applications PHP moderne écrit en Go.
Vous pouvez démarrer votre application Laravel avec cette seule commande.

```shell theme={null}
frankenphp php-server -r public/
```

Pour des fonctionnalités avancées telles que HTTP/3, la compression moderne, l'intégration avec [Laravel Octane](https://laravel.com/docs/octane) ou la mise en binaire autonome, consultez la [documentation Laravel de FrankenPHP](https://frankenphp.dev/docs/laravel/).

### 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.

```shell theme={null}
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.

```shell theme={null}
php artisan optimize
```

Pour vider les caches, utilisez `optimize:clear`.

```shell theme={null}
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                     |

<Info>
  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.
</Info>

## 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.

```shell theme={null}
php artisan reload
```

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

<Info>
  Si vous utilisez Laravel Cloud, le rechargement gracieux de tous les services est géré automatiquement ; la commande `reload` n'est pas nécessaire.
</Info>

## 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`.

<Warning>
  **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.
</Warning>

```ini theme={null}
# .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`.

```php theme={null}
->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](https://cloud.laravel.com) 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](https://forge.laravel.com) 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

<Card title="Déploiement — Documentation officielle" icon="arrow-right" href="https://laravel.com/docs/deployment">
  Consultez la documentation officielle pour les derniers détails de configuration de déploiement.
</Card>


## Related topics

- [Laravel Cloud CLI — piloter Laravel Cloud depuis le terminal](/fr/blog/laravel-cloud-cli.md)
- [Laravel Horizon](/fr/horizon.md)
- [Bundle du Copilot CLI](/fr/packages/laravel-copilot-sdk/bundle-cli.md)
- [Feedable](/fr/packages/feedable/index.md)
- [laravel/agent-skills — la collection officielle de skills d'agents IA Laravel](/fr/blog/agent-skills-introduction.md)