Laravel Sail

Construisez un environnement de développement local basé sur Docker sans configuration avec Laravel Sail.

​

Qu’est-ce que Sail

Laravel Sail est une interface CLI légère pour piloter un environnement de développement Laravel Docker. Vous pouvez construire une application Laravel avec PHP, MySQL et Redis sans connaître Docker.

Au cœur de Sail se trouvent le fichier compose.yaml à la racine du projet et le script sail. Ce script fournit des méthodes CLI pratiques pour piloter les conteneurs définis dans compose.yaml.

Laravel Sail fonctionne sur macOS, Linux et Windows (via WSL2).

Sous Laravel 13, Sail n’est plus l’environnement de développement par défaut. laravel/sail a été retiré du composer.json du skeleton ; à la place, la commande composer setup est fournie. Le défaut est PHP local + SQLite.

composer setup
composer dev

Si vous avez besoin de conteneurs Docker, vous pouvez toujours installer et utiliser Sail.

Sail est destiné au développement local uniquement. Pas prévu pour la production. Pour la production, préparez une configuration Docker / cloud dédiée.

---

​

Installation

​

Sur un projet existant

Installez le package via Composer.

1. Ajouter le package Sail

   composer require laravel/sail --dev
   
2. Publier les fichiers de configuration

   php artisan sail:install
   

   Sélectionnez interactivement les services (MySQL, Redis, Mailpit, etc.). Cette commande publie compose.yaml à la racine et ajoute les variables d’environnement nécessaires à .env.

3. Démarrer Sail

   ./vendor/bin/sail up
   

   Le premier démarrage télécharge les images Docker. Ensuite, l’application est disponible sur http://localhost.

Sous Docker Desktop pour Linux, exécutez docker context use default pour utiliser le contexte default. En cas d’erreur de permissions dans le conteneur, définissez SUPERVISOR_PHP_USER sur root.

​

Ajouter des services

Pour ajouter des services à une installation Sail existante :

php artisan sail:add

​

Devcontainer

Pour développer dans un Devcontainer :

php artisan sail:install --devcontainer

---

​

Configuration

​

Alias shell

Par défaut, il faut taper ./vendor/bin/sail à chaque fois. Créez un alias.

alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'

Ajoutez-le à ~/.zshrc ou ~/.bashrc puis redémarrez le shell.

sail up

Après cet alias, remplacez tous les ./vendor/bin/sail de la documentation par sail.

​

Reconstruire les images

Pour maintenir les packages à jour :

docker compose down -v

sail build --no-cache

sail up

---

​

Démarrer et arrêter

Lancer tous les conteneurs :

# Foreground
sail up

# Background
sail up -d

Arrêter avec stop, ou Ctrl + C en foreground.

sail stop

​

Flux de démarrage

---

​

Exécution de commandes

L’application tourne dans Docker : préfixez les commandes PHP, Artisan, Composer, Node/NPM par sail.

Les commandes Laravel classiques (php artisan, composer, npm) doivent être précédées de sail sous Sail.

​

PHP

sail php --version

sail php script.php

​

Composer

sail composer require laravel/sanctum

​

Artisan

sail artisan migrate

sail artisan queue:work

​

Node / NPM

sail node --version

sail npm run dev

# Yarn
sail yarn

​

Shell dans le conteneur

sail shell

# En tant que root
sail root-shell

Session Tinker :

sail tinker

---

​

Services

Voici les services proposés (choisis via sail:install).

​

MySQL

Inclus par défaut dans compose.yaml. Les données persistent via un volume Docker. Une base app et une base testing sont créées au premier démarrage.

Dans .env, réglez DB_HOST sur mysql.

DB_HOST=mysql
DB_PORT=3306

Utilisez un client GUI (comme TablePlus) sur le port 3306.

​

Redis

Dans .env, REDIS_HOST=redis.

REDIS_HOST=redis
REDIS_PORT=6379

​

Valkey

Pour utiliser Valkey à la place de Redis, REDIS_HOST=valkey.

​

Mailpit

Capture les e-mails et les affiche dans une UI web pendant le développement.

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Interface web sur http://localhost:8025.

​

Meilisearch / Typesense

Recherche plein texte via Laravel Scout.

• Meilisearch : MEILISEARCH_HOST=http://meilisearch:7700
• Typesense : TYPESENSE_HOST=typesense, TYPESENSE_PORT=8108, etc.

​

RustFS (compatible S3)

Émulez un stockage S3 en local.

FILESYSTEM_DISK=s3
AWS_ACCESS_KEY_ID=sail
AWS_SECRET_ACCESS_KEY=password
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=local
AWS_ENDPOINT=http://rustfs:9000
AWS_USE_PATH_STYLE_ENDPOINT=true

---

​

Tests

sail test

sail test --group orders

sail test équivaut à sail artisan test. Une base testing dédiée est utilisée.

​

Laravel Dusk

Sans installer Selenium localement. Décommentez le service Selenium dans compose.yaml.

selenium:
    image: 'selenium/standalone-chrome'
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

Sur Apple Silicon (M1/M2/M3), utilisez l’image selenium/standalone-chromium.

Puis :

sail dusk

---

​

Versions PHP / Node

​

Changer PHP

Dans compose.yaml, modifiez build.context du service laravel.test.

# PHP 8.5 (défaut)
context: ./vendor/laravel/sail/runtimes/8.5

# PHP 8.4
context: ./vendor/laravel/sail/runtimes/8.4

# PHP 8.3
context: ./vendor/laravel/sail/runtimes/8.3

Puis rebuildez.

sail build --no-cache
sail up

​

Extensions PHP supplémentaires

L’image contient les extensions courantes. Ajoutez-en via PHP_EXTENSIONS.

build:
    args:
        WWWGROUP: '${WWWGROUP}'
        PHP_EXTENSIONS: 'gmp imagick'

Rebuildez :

sail build --no-cache
sail up

​

Changer Node

build:
    args:
        WWWGROUP: '${WWWGROUP}'
        NODE_VERSION: '20'

---

​

Partager le site

Exposez temporairement le site (revue par un collègue, test de webhook).

sail share

Une URL laravel-sail.site aléatoire est générée. Pour que les helpers d’URL fonctionnent, configurez les proxies de confiance dans bootstrap/app.php.

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: '*');
})

Sous-domaine personnalisé :

sail share --subdomain=my-sail-site

---

​

Xdebug

​

Activer

sail:publish pour publier la configuration, puis dans .env :

SAIL_XDEBUG_MODE=develop,debug,coverage

Vérifiez que le php.ini publié contient :

[xdebug]
xdebug.mode=${XDEBUG_MODE}

Rebuildez :

sail build --no-cache

​

Débogage CLI

# Sans Xdebug
sail artisan migrate

# Avec Xdebug
sail debug migrate

​

Débogage navigateur

Voir la doc Xdebug. Sous PhpStorm, Zero-configuration debugging est pratique.

Sail utilise artisan serve. Le support de XDEBUG_CONFIG et XDEBUG_MODE requiert Laravel 8.53.0+.

---

​

Personnalisation

Publiez le Dockerfile et les fichiers de config :

sail artisan sail:publish

Le répertoire docker/ est créé. Rebuildez après modification.

sail build --no-cache

---

​

Différences avec la production

Sail est un environnement de développement local. Pas prévu pour la production. Pour déployer avec Docker, envisagez Laravel Cloud, Forge, Ploi ou votre propre config Compose / Kubernetes.

Différences principales :

Aspect	Sail (local)	Production
But	Développement / débogage	Fournir un service
Xdebug	Activable	À désactiver
Mailpit	Capture les e-mails	Serveur SMTP réel
Persistance	Volume Docker	DB managée, etc.
Performance	Non optimisée	Optimisée