Laravel Sail - Knowledge of Laravel

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.

Ajouter le package Sail

composer require laravel/sail --dev

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.

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

​Qu’est-ce que Sail

​Installation

​Sur un projet existant

​Ajouter des services

​Devcontainer

​Configuration

​Alias shell

​Reconstruire les images

​Démarrer et arrêter

​Flux de démarrage

​Exécution de commandes

​PHP

​Composer

​Artisan

​Node / NPM

​Shell dans le conteneur

​Services

​MySQL

​Redis

​Valkey

​Mailpit

​Meilisearch / Typesense

​RustFS (compatible S3)

​Tests

​Laravel Dusk

​Versions PHP / Node

​Changer PHP

​Extensions PHP supplémentaires

​Changer Node

​Partager le site

​Xdebug

​Activer

​Débogage CLI

​Débogage navigateur

​Personnalisation

​Différences avec la production

Qu’est-ce que Sail

Installation

Sur un projet existant

Ajouter des services

Devcontainer

Configuration

Alias shell

Reconstruire les images

Démarrer et arrêter

Flux de démarrage

Exécution de commandes

PHP

Composer

Artisan

Node / NPM

Shell dans le conteneur

Services

MySQL

Redis

Valkey

Mailpit

Meilisearch / Typesense

RustFS (compatible S3)

Tests

Laravel Dusk

Versions PHP / Node

Changer PHP

Extensions PHP supplémentaires

Changer Node

Partager le site

Xdebug

Activer

Débogage CLI

Débogage navigateur

Personnalisation

Différences avec la production