Laravel Sail - Knowledge of Laravel

Wat is Sail

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

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.

composer setup
composer dev

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

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

Installatie

Installeren in een bestaand project

Installeer het pakket met Composer.

Het Sail-pakket toevoegen

composer require laravel/sail --dev

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.

php artisan sail:install

Je kunt interactief services kiezen. Selecteer bijvoorbeeld MySQL, Redis en Mailpit.

Sail starten

./vendor/bin/sail up

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

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.

Extra services toevoegen

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

php artisan sail:add

Devcontainers gebruiken

Wil je ontwikkelen binnen een Devcontainer, gebruik dan de optie --devcontainer.

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.

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

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

sail up

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

Images opnieuw bouwen

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

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.

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

sail stop

Opstartflow

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.

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.

PHP-commando’s

sail php --version

sail php script.php

Composer-commando’s

sail composer require laravel/sanctum

Artisan-commando’s

sail artisan migrate

sail artisan queue:work

Node/NPM-commando’s

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.

sail shell

# Verbinden als root-gebruiker
sail root-shell

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

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.

DB_HOST=mysql
DB_PORT=3306

Om vanaf je lokale machine te verbinden gebruik je een GUI-tool zoals TablePlus. De standaardpoort is 3306.

Redis

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

REDIS_HOST=redis
REDIS_PORT=6379

Valkey

Wil je Valkey 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.

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

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

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.

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

Gebruik op Apple Silicon (M1/M2/M3) het image selenium/standalone-chromium.

Voer daarna de Dusk-tests uit.

sail dusk

PHP-/Node-versies

De PHP-versie wijzigen

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

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

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.

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

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

sail build --no-cache
sail up

De Node-versie wijzigen

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.

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.

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

Je kunt ook een subdomein opgeven.

sail share --subdomain=my-sail-site

Xdebug

Inschakelen

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

SAIL_XDEBUG_MODE=develop,debug,coverage

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

[xdebug]
xdebug.mode=${XDEBUG_MODE}

Bouw na de wijziging het image opnieuw.

sail build --no-cache

CLI-debugging

# 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. Gebruik je PhpStorm, dan is de configuratie van Zero-configuration debugging handig.

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.

Aanpassen

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

sail artisan sail:publish

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

sail build --no-cache

Verschillen met productie

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.

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

​Wat is Sail

​Installatie

​Installeren in een bestaand project

​Extra services toevoegen

​Devcontainers gebruiken

​Configuratie

​Een shell-alias instellen

​Images opnieuw bouwen

​Starten en stoppen

​Opstartflow

​Commando’s uitvoeren

​PHP-commando’s

​Composer-commando’s

​Artisan-commando’s

​Node/NPM-commando’s

​Container-CLI (shell)

​Services

​MySQL

​Redis

​Valkey

​Mailpit

​Meilisearch / Typesense

​RustFS (S3-compatibele opslag)

​Tests uitvoeren

​Laravel Dusk

​PHP-/Node-versies

​De PHP-versie wijzigen

​Extra PHP-extensies

​De Node-versie wijzigen

​Je site publiekelijk delen

​Xdebug

​Inschakelen

​CLI-debugging

​Browser-debugging

​Aanpassen

​Verschillen met productie

Wat is Sail

Installatie

Installeren in een bestaand project

Extra services toevoegen

Devcontainers gebruiken

Configuratie

Een shell-alias instellen

Images opnieuw bouwen

Starten en stoppen

Opstartflow

Commando’s uitvoeren

PHP-commando’s

Composer-commando’s

Artisan-commando’s

Node/NPM-commando’s

Container-CLI (shell)

Services

MySQL

Redis

Valkey

Mailpit

Meilisearch / Typesense

RustFS (S3-compatibele opslag)

Tests uitvoeren

Laravel Dusk

PHP-/Node-versies

De PHP-versie wijzigen

Extra PHP-extensies

De Node-versie wijzigen

Je site publiekelijk delen

Xdebug

Inschakelen

CLI-debugging

Browser-debugging

Aanpassen

Verschillen met productie