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

# Laravel Sail

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

## Qu'est-ce que Sail

[Laravel Sail](https://github.com/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](https://docs.microsoft.com/fr-fr/windows/wsl/about)).

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

  ```shell theme={null}
  composer setup
  composer dev
  ```

  Si vous avez besoin de conteneurs Docker, vous pouvez toujours installer et utiliser Sail.
</Warning>

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

***

## Installation

### Sur un projet existant

Installez le package via Composer.

<Steps>
  <Step title="Ajouter le package Sail">
    ```shell theme={null}
    composer require laravel/sail --dev
    ```
  </Step>

  <Step title="Publier les fichiers de configuration">
    ```shell theme={null}
    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`.
  </Step>

  <Step title="Démarrer Sail">
    ```shell theme={null}
    ./vendor/bin/sail up
    ```

    Le premier démarrage télécharge les images Docker.
    Ensuite, l'application est disponible sur `http://localhost`.
  </Step>
</Steps>

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

### Ajouter des services

Pour ajouter des services à une installation Sail existante :

```shell theme={null}
php artisan sail:add
```

### Devcontainer

Pour développer dans un [Devcontainer](https://code.visualstudio.com/docs/remote/containers) :

```shell theme={null}
php artisan sail:install --devcontainer
```

***

## Configuration

### Alias shell

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

```shell theme={null}
alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'
```

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

```shell theme={null}
sail up
```

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

### Reconstruire les images

Pour maintenir les packages à jour :

```shell theme={null}
docker compose down -v

sail build --no-cache

sail up
```

***

## Démarrer et arrêter

Lancer tous les conteneurs :

```shell theme={null}
# Foreground
sail up

# Background
sail up -d
```

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

```shell theme={null}
sail stop
```

### Flux de démarrage

```mermaid theme={null}
flowchart TD
    A["sail up"] --> B{"Image Docker<br>présente ?"}
    B -- Non --> C["Build / téléchargement"]
    C --> D["Démarrage des conteneurs"]
    B -- Oui --> D
    D --> E["Conteneur laravel.test<br>(app)"]
    D --> F["Conteneur mysql"]
    D --> G["Conteneur redis"]
    D --> H["Conteneur mailpit"]
    E --> I["Accès via http://localhost"]
```

***

## Exécution de commandes

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

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

### PHP

```shell theme={null}
sail php --version

sail php script.php
```

### Composer

```shell theme={null}
sail composer require laravel/sanctum
```

### Artisan

```shell theme={null}
sail artisan migrate

sail artisan queue:work
```

### Node / NPM

```shell theme={null}
sail node --version

sail npm run dev

# Yarn
sail yarn
```

### Shell dans le conteneur

```shell theme={null}
sail shell

# En tant que root
sail root-shell
```

Session Tinker :

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

```ini theme={null}
DB_HOST=mysql
DB_PORT=3306
```

Utilisez un client GUI (comme [TablePlus](https://tableplus.com)) sur le port `3306`.

### Redis

Dans `.env`, `REDIS_HOST=redis`.

```ini theme={null}
REDIS_HOST=redis
REDIS_PORT=6379
```

### Valkey

Pour utiliser [Valkey](https://valkey.io/) à la place de Redis, `REDIS_HOST=valkey`.

### Mailpit

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

```ini theme={null}
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null
```

Interface web sur `http://localhost:8025`.

### Meilisearch / Typesense

Recherche plein texte via [Laravel Scout](/fr/scout).

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

### RustFS (compatible S3)

Émulez un stockage S3 en local.

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

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

```yaml theme={null}
selenium:
    image: 'selenium/standalone-chrome'
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail
```

<Tip>
  Sur Apple Silicon (M1/M2/M3), utilisez l'image `selenium/standalone-chromium`.
</Tip>

Puis :

```shell theme={null}
sail dusk
```

***

## Versions PHP / Node

### Changer PHP

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

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

```shell theme={null}
sail build --no-cache
sail up
```

### Extensions PHP supplémentaires

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

```yaml theme={null}
build:
    args:
        WWWGROUP: '${WWWGROUP}'
        PHP_EXTENSIONS: 'gmp imagick'
```

Rebuildez :

```shell theme={null}
sail build --no-cache
sail up
```

### Changer Node

```yaml theme={null}
build:
    args:
        WWWGROUP: '${WWWGROUP}'
        NODE_VERSION: '20'
```

***

## Partager le site

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

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

```php theme={null}
->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: '*');
})
```

Sous-domaine personnalisé :

```shell theme={null}
sail share --subdomain=my-sail-site
```

***

## Xdebug

### Activer

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

```ini theme={null}
SAIL_XDEBUG_MODE=develop,debug,coverage
```

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

```ini theme={null}
[xdebug]
xdebug.mode=${XDEBUG_MODE}
```

Rebuildez :

```shell theme={null}
sail build --no-cache
```

### Débogage CLI

```shell theme={null}
# Sans Xdebug
sail artisan migrate

# Avec Xdebug
sail debug migrate
```

### Débogage navigateur

Voir la [doc Xdebug](https://xdebug.org/docs/step_debug#web-application). Sous PhpStorm, [Zero-configuration debugging](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html) est pratique.

<Warning>
  Sail utilise `artisan serve`. Le support de `XDEBUG_CONFIG` et `XDEBUG_MODE` requiert Laravel 8.53.0+.
</Warning>

***

## Personnalisation

Publiez le Dockerfile et les fichiers de config :

```shell theme={null}
sail artisan sail:publish
```

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

```shell theme={null}
sail build --no-cache
```

***

## Différences avec la production

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

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          |


## Related topics

- [Laravel Boost Custom Agent for GitHub Copilot CLI](/fr/packages/laravel-boost-copilot-cli.md)
- [Console Artisan](/fr/artisan.md)
- [Redis](/fr/redis.md)
- [Connaissances requises avant de commencer avec Laravel](/fr/true-tutorial.md)
- [Laravel LSP — extension IDE via Language Server Protocol](/fr/blog/laravel-lsp-introduction.md)