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

> Uitleg over hoe je met Laravel Sail zonder configuratie een Docker-gebaseerde lokale ontwikkelomgeving opzet.

## Wat is Sail

[Laravel Sail](https://github.com/laravel/sail) is een lichtgewicht command-line interface voor het werken met de Docker-ontwikkelomgeving van Laravel.
Je kunt er een Laravel-applicatie met PHP, MySQL en Redis mee opzetten, zonder voorkennis van Docker.

Het hart van Sail bestaat uit het bestand `compose.yaml` in de projectroot en het `sail`-script.
Het `sail`-script biedt handige CLI-methoden om de Docker-containers uit `compose.yaml` te bedienen.

Laravel Sail werkt op macOS, Linux en Windows (via [WSL2](https://docs.microsoft.com/en-us/windows/wsl/about)).

<Warning>
  **In Laravel 13 is Sail niet langer de standaard ontwikkelomgeving.**
  `laravel/sail` is verwijderd uit de `composer.json` van het skeleton; in plaats daarvan is er het commando `composer setup`.
  De standaard is een opzet met lokale PHP + SQLite.

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

  Heb je Docker-containers nodig, dan kun je Sail nog steeds installeren en gebruiken.
</Warning>

<Info>
  Sail is een tool die uitsluitend bedoeld is voor lokale ontwikkeling en niet voor productiegebruik.
  Zorg voor productie voor een eigen, passende Docker-/cloudconfiguratie.
</Info>

***

## Installatie

### Installeren in een bestaand project

Installeer het pakket met Composer.

<Steps>
  <Step title="Het Sail-pakket toevoegen">
    ```shell theme={null}
    composer require laravel/sail --dev
    ```
  </Step>

  <Step title="Configuratiebestanden publiceren">
    Voer het Artisan-commando `sail:install` uit.
    Dit commando publiceert `compose.yaml` naar de projectroot en voegt de benodigde omgevingsvariabelen toe aan `.env`.

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

    Je kunt interactief services kiezen. Selecteer bijvoorbeeld MySQL, Redis en Mailpit.
  </Step>

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

    Bij de eerste start duurt het downloaden van de Docker-images even.
    Daarna is je applicatie bereikbaar op `http://localhost`.
  </Step>
</Steps>

<Warning>
  Gebruik je Docker Desktop for Linux, voer dan `docker context use default` uit om de `default`-context te gebruiken.
  Krijg je in de container bestandsrechtenfouten, stel dan de omgevingsvariabele `SUPERVISOR_PHP_USER` in op `root`.
</Warning>

### Extra services toevoegen

Om services toe te voegen aan een bestaande Sail-installatie gebruik je het commando `sail:add`.

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

### Devcontainers gebruiken

Wil je ontwikkelen binnen een [Devcontainer](https://code.visualstudio.com/docs/remote/containers), gebruik dan de optie `--devcontainer`.

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

***

## Configuratie

### Een shell-alias instellen

Standaard moet je telkens `./vendor/bin/sail` intypen.
Stel je een shell-alias in, dan volstaat het om alleen `sail` te typen.

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

Voeg dit toe aan `~/.zshrc` of `~/.bashrc` en herstart je shell.

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

<Tip>
  Nadat je de alias hebt ingesteld, kun je in alle commandovoorbeelden van deze documentatie `sail` typen in plaats van `./vendor/bin/sail`.
</Tip>

### Images opnieuw bouwen

Wil je je pakketten up-to-date houden, bouw dan de images opnieuw.

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

sail build --no-cache

sail up
```

***

## Starten en stoppen

Om alle Docker-containers uit `compose.yaml` te starten gebruik je het `up`-commando.

```shell theme={null}
# Op de voorgrond starten
sail up

# Op de achtergrond starten
sail up -d
```

Om te stoppen gebruik je het `stop`-commando, of druk je op `Ctrl + C` als de containers op de voorgrond draaien.

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

### Opstartflow

```mermaid theme={null}
flowchart TD
    A["sail up uitvoeren"] --> B{"Bestaat het<br>Docker-image?"}
    B -- Nee --> C["Image bouwen/<br>downloaden"]
    C --> D["Containers starten"]
    B -- Ja --> D
    D --> E["laravel.test-container<br>(app) start"]
    D --> F["mysql-container start"]
    D --> G["redis-container start"]
    D --> H["mailpit-container start"]
    E --> I["Bereikbaar op http://localhost"]
```

***

## Commando's uitvoeren

Met Sail draait je applicatie in een Docker-container.
PHP-commando's, Artisan-commando's, Composer-commando's en Node/NPM-commando's voer je allemaal uit via `sail`.

<Info>
  De commando's `php artisan`, `composer` en `npm` die je vaak in de officiële Laravel-documentatie ziet,
  voer je in een Sail-omgeving uit met `sail` ervoor.
</Info>

### PHP-commando's

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

sail php script.php
```

### Composer-commando's

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

### Artisan-commando's

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

sail artisan queue:work
```

### Node/NPM-commando's

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

sail npm run dev

# Bij gebruik van Yarn
sail yarn
```

### Container-CLI (shell)

Je kunt ook rechtstreeks een Bash-sessie in de container openen.

```shell theme={null}
sail shell

# Verbinden als root-gebruiker
sail root-shell
```

Om een Tinker-sessie te openen gebruik je dit commando:

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

***

## Services

Een overzicht van de services die Sail biedt. Je selecteert ze bij de installatie met `sail:install`.

### MySQL

Standaard opgenomen in `compose.yaml`.
De data wordt bewaard in een Docker Volume. Bij de eerste start worden automatisch twee databases aangemaakt: één voor de app en één voor `testing`.

Stel `DB_HOST` in `.env` in op `mysql` zodat je app er verbinding mee kan maken.

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

Om vanaf je lokale machine te verbinden gebruik je een GUI-tool zoals [TablePlus](https://tableplus.com). De standaardpoort is `3306`.

### Redis

Stel `REDIS_HOST` in `.env` in op `redis` zodat je app toegang heeft tot Redis.

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

### Valkey

Wil je [Valkey](https://valkey.io/) gebruiken als alternatief voor Redis, stel dan `REDIS_HOST` in op `valkey`.

### Mailpit

Vangt e-mails op die tijdens lokale ontwikkeling worden verstuurd en toont ze in een web-UI.

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

Terwijl Sail draait, is de web-UI van Mailpit bereikbaar op `http://localhost:8025`.

### Meilisearch / Typesense

Integreer met [Laravel Scout](/nl/scout) om full-text zoeken uit te proberen.

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

### RustFS (S3-compatibele opslag)

Ben je van plan in productie Amazon S3 te gebruiken, dan kun je lokaal S3-compatibele opslag emuleren.

```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 uitvoeren

```shell theme={null}
sail test

sail test --group orders
```

`sail test` komt intern overeen met `sail artisan test`. Er is standaard een aparte `testing`-database, zodat je ontwikkeldata onaangetast blijft.

### Laravel Dusk

Met Sail voer je Dusk-browsertests uit zonder Selenium lokaal te installeren.
Verwijder de commentaartekens bij de Selenium-service in `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>
  Gebruik op Apple Silicon (M1/M2/M3) het image `selenium/standalone-chromium`.
</Tip>

Voer daarna de Dusk-tests uit.

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

***

## PHP-/Node-versies

### De PHP-versie wijzigen

Wijzig de `build.context` van de `laravel.test`-container in `compose.yaml`.

```yaml theme={null}
# PHP 8.5 (standaard)
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
```

Bouw na de wijziging het image opnieuw.

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

### Extra PHP-extensies

De runtime-images van Sail bevatten de gangbare PHP-extensies. Heeft je applicatie extra extensies nodig, dan kun je aan de `laravel.test`-service in `compose.yaml` het build-argument `PHP_EXTENSIONS` toevoegen (gescheiden door spaties) zodat ze tijdens het bouwen van het image worden geïnstalleerd.

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

Bouw na het bijwerken van `compose.yaml` het containerimage opnieuw.

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

### De Node-versie wijzigen

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

***

## Je site publiekelijk delen

Voor previews voor collega's of het testen van webhooks kun je je site tijdelijk publiek toegankelijk maken.

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

Er wordt een willekeurige `laravel-sail.site`-URL uitgegeven. Stel in `bootstrap/app.php` de vertrouwde proxy's in zodat de URL-generatiehelpers correct werken.

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

Je kunt ook een subdomein opgeven.

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

***

## Xdebug

### Inschakelen

Publiceer eerst de configuratiebestanden met `sail:publish` en voeg daarna het volgende toe aan `.env`.

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

Controleer of het gepubliceerde `php.ini`-bestand de volgende instelling bevat.

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

Bouw na de wijziging het image opnieuw.

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

### CLI-debugging

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

# Uitvoeren met Xdebug
sail debug migrate
```

### Browser-debugging

Voor de stappen om een debugsessie vanuit de browser te starten, zie de [officiële Xdebug-documentatie](https://xdebug.org/docs/step_debug#web-application).
Gebruik je PhpStorm, dan is de configuratie van [Zero-configuration debugging](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html) handig.

<Warning>
  Sail serveert je app via `artisan serve`.
  `XDEBUG_CONFIG` en `XDEBUG_MODE` worden pas geaccepteerd vanaf Laravel 8.53.0.
  In oudere versies werkt de debugverbinding niet.
</Warning>

***

## Aanpassen

Om de Dockerfiles en configuratiebestanden van Sail aan te passen publiceer je ze met het commando `sail:publish`.

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

Na het publiceren staan de Dockerfiles in de map `docker/`.
Bouw na je wijzigingen de containers opnieuw.

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

***

## Verschillen met productie

<Warning>
  Sail is een omgeving die uitsluitend bedoeld is voor lokale ontwikkeling en niet voor productiegebruik.
  Overweeg voor Docker-deployments naar productie diensten zoals Laravel Cloud, Forge of Ploi,
  of een eigen Docker Compose-/Kubernetes-configuratie.
</Warning>

De belangrijkste verschillen tussen Sail en productie op een rij:

| Onderdeel        | Sail (lokaal)                 | Productie               |
| ---------------- | ----------------------------- | ----------------------- |
| Doel             | Ontwikkelen en debuggen       | Diensten aanbieden      |
| Xdebug           | Kan worden ingeschakeld       | Uitschakelen aanbevolen |
| Mailpit          | Vangt e-mails op voor preview | Echte mailserver        |
| Datapersistentie | Docker Volume                 | Managed database e.d.   |
| Performance      | Niet geoptimaliseerd          | Optimalisatie vereist   |


## Related topics

- [Laravel Scout](/nl/scout.md)
- [Artisan-console](/nl/artisan.md)
- [Redis](/nl/redis.md)
- [Kennis die je nodig hebt voordat je met Laravel begint](/nl/true-tutorial.md)
- [Laravel LSP — IDE-functionaliteit via het Language Server Protocol](/nl/blog/laravel-lsp-introduction.md)