Laravel Sail - Knowledge of Laravel

Cos’è Sail

Laravel Sail è un’interfaccia a riga di comando leggera per gestire l’ambiente di sviluppo Docker di Laravel. Ti permette di costruire un’applicazione Laravel con PHP, MySQL e Redis senza conoscenze preliminari di Docker. Il cuore di Sail è il file compose.yaml collocato nella root del progetto e lo script sail. Lo script sail fornisce comodi metodi CLI per gestire i container Docker definiti in compose.yaml. Laravel Sail funziona su macOS, Linux e Windows (tramite WSL2).

In Laravel 13 Sail non è più l’ambiente di sviluppo standard. laravel/sail è stato rimosso dal composer.json dello scheletro e al suo posto è disponibile il comando composer setup. Lo standard è la configurazione con PHP locale + SQLite.

composer setup
composer dev

Se ti servono i container Docker, puoi comunque installare e usare Sail.

Sail è uno strumento pensato esclusivamente per lo sviluppo locale. Non è pensato per l’uso in produzione. Per la produzione prepara separatamente una configurazione Docker / cloud adeguata.

Installazione

Installazione in un progetto esistente

Installa il pacchetto con Composer.

Aggiungi il pacchetto Sail

composer require laravel/sail --dev

Pubblica i file di configurazione

Esegui il comando Artisan sail:install. Questo comando pubblica compose.yaml nella root del progetto e aggiunge le variabili d’ambiente necessarie a .env.

php artisan sail:install

Puoi scegliere i servizi in modo interattivo. Seleziona MySQL, Redis, Mailpit, ecc.

Avvia Sail

./vendor/bin/sail up

Al primo avvio il download delle immagini Docker richiede un po’ di tempo. Dopo l’avvio puoi accedere all’applicazione su http://localhost.

Se usi Docker Desktop for Linux, esegui docker context use default per usare il contesto default. Se all’interno dei container si verificano errori di permessi sui file, imposta la variabile d’ambiente SUPERVISOR_PHP_USER su root.

Aggiungere servizi aggiuntivi

Per aggiungere servizi a un’installazione Sail esistente, usa il comando sail:add.

php artisan sail:add

Uso di Devcontainer

Se vuoi sviluppare all’interno di un Devcontainer, usa l’opzione --devcontainer.

php artisan sail:install --devcontainer

Configurazione

Impostazione degli alias della shell

Di default devi digitare ogni volta ./vendor/bin/sail. Con un alias della shell puoi digitare solo sail.

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

Aggiungilo a ~/.zshrc o ~/.bashrc e riavvia la shell.

sail up

Dopo aver impostato l’alias, in tutti gli esempi di comando di questa documentazione puoi scrivere sail al posto di ./vendor/bin/sail.

Ricostruzione delle immagini

Se vuoi mantenere i pacchetti aggiornati, ricostruisci le immagini.

docker compose down -v

sail build --no-cache

sail up

Avvio e arresto

Per avviare tutti i container Docker definiti in compose.yaml usa il comando up.

# Avvio in foreground
sail up

# Avvio in background
sail up -d

Per fermarli usa il comando stop, oppure premi Ctrl + C se sono in foreground.

sail stop

Flusso di avvio

Esecuzione dei comandi

Con Sail l’applicazione gira all’interno di container Docker. I comandi PHP, Artisan, Composer, Node / NPM si eseguono tutti tramite sail.

I comandi php artisan, composer e npm frequenti nella documentazione ufficiale di Laravel devono essere eseguiti in ambiente Sail anteponendo sail.

Comandi PHP

sail php --version

sail php script.php

Comandi Composer

sail composer require laravel/sanctum

Comandi Artisan

sail artisan migrate

sail artisan queue:work

Comandi Node / NPM

sail node --version

sail npm run dev

# Se usi Yarn
sail yarn

CLI del container (shell)

Puoi anche aprire direttamente una sessione Bash all’interno del container.

sail shell

# Collegati come utente root
sail root-shell

Per aprire una sessione Tinker:

sail tinker

Servizi

Panoramica dei servizi forniti da Sail. Puoi selezionarli con sail:install durante l’installazione.

MySQL

Incluso di default in compose.yaml. I dati sono persistenti tramite Docker Volume. Al primo avvio vengono create automaticamente due database: uno per l’app e uno per il testing. Imposta DB_HOST a mysql in .env per accedervi dall’app.

DB_HOST=mysql
DB_PORT=3306

Per collegarti dalla macchina locale usa un tool GUI come TablePlus. La porta predefinita è 3306.

Redis

Impostando REDIS_HOST a redis in .env puoi accedere a Redis dall’app.

REDIS_HOST=redis
REDIS_PORT=6379

Valkey

Se usi Valkey come alternativa a Redis, imposta REDIS_HOST su valkey.

Mailpit

Cattura le email inviate durante lo sviluppo locale e le mostra nell’anteprima Web UI.

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Con Sail attivo puoi accedere alla Web UI di Mailpit su http://localhost:8025.

Meilisearch / Typesense

Puoi provare la ricerca full-text integrata con Laravel Scout.

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

RustFS (storage S3-compatibile)

Se prevedi di usare Amazon S3 in produzione, puoi emulare in locale uno storage S3-compatibile.

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

Esecuzione dei test

sail test

sail test --group orders

sail test è internamente equivalente a sail artisan test. Di default viene predisposto un database testing dedicato, così non influisci sui dati di sviluppo.

Laravel Dusk

Con Sail puoi eseguire i test browser Dusk senza installare Selenium in locale. Rimuovi il commento dal servizio Selenium in compose.yaml.

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

Su Apple Silicon (M1/M2/M3) usa l’immagine selenium/standalone-chromium.

Poi esegui i test Dusk.

sail dusk

Versione di PHP / Node

Cambiare la versione di PHP

Modifica build.context del container laravel.test in compose.yaml.

# PHP 8.5 (predefinito)
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

Dopo la modifica ricostruisci l’immagine.

sail build --no-cache
sail up

Estensioni PHP aggiuntive

L’immagine runtime di Sail include estensioni PHP comuni. Se l’applicazione richiede estensioni aggiuntive, aggiungi l’argomento di build PHP_EXTENSIONS separando i valori con spazi al servizio laravel.test di compose.yaml per installarle durante il build dell’immagine.

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

Dopo aver aggiornato compose.yaml, ricostruisci le immagini dei container.

sail build --no-cache
sail up

Cambiare la versione di Node

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

Condivisione pubblica del sito

Per anteprima ai colleghi o test di webhook, puoi pubblicare temporaneamente il sito all’esterno.

sail share

Viene generato un URL casuale su laravel-sail.site. Perché gli helper di generazione URL funzionino correttamente, configura i proxy fidati in bootstrap/app.php.

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

Puoi anche specificare un sottodominio.

sail share --subdomain=my-sail-site

Xdebug

Attivazione

Prima pubblica i file di configurazione con sail:publish, poi aggiungi in .env:

SAIL_XDEBUG_MODE=develop,debug,coverage

Verifica che il file php.ini pubblicato contenga:

[xdebug]
xdebug.mode=${XDEBUG_MODE}

Dopo la modifica ricostruisci l’immagine.

sail build --no-cache

Debug via CLI

# Esecuzione senza Xdebug
sail artisan migrate

# Esecuzione con Xdebug
sail debug migrate

Debug via browser

Per le istruzioni per avviare una sessione di debug dal browser consulta la documentazione ufficiale di Xdebug. Se usi PhpStorm è comoda la configurazione Zero-configuration debugging.

Sail serve l’app con artisan serve. L’accettazione di XDEBUG_CONFIG e XDEBUG_MODE è a partire da Laravel 8.53.0. Nelle versioni precedenti la connessione di debug non funzionerà.

Personalizzazione

Per personalizzare i Dockerfile e i file di configurazione di Sail, pubblicali con il comando sail:publish.

sail artisan sail:publish

Dopo la pubblicazione i Dockerfile si trovano nella directory docker/. Dopo le modifiche ricostruisci i container.

sail build --no-cache

Differenze rispetto alla produzione

Sail è un ambiente dedicato allo sviluppo locale. Non è pensato per l’uso in produzione. Per il deploy Docker in produzione valuta servizi come Laravel Cloud, Forge, Ploi o una tua configurazione Docker Compose / Kubernetes.

Le principali differenze tra Sail e la produzione sono riassunte qui sotto.

Aspetto	Sail (locale)	Produzione
Obiettivo	Sviluppo, debug	Erogazione del servizio
Xdebug	Attivabile	Consigliato disattivato
Mailpit	Cattura ed anteprima delle email	Vero server di posta
Persistenza dati	Docker Volume	DB gestito, ecc.
Performance	Nessuna ottimizzazione	Ottimizzazione essenziale

​Cos’è Sail

​Installazione

​Installazione in un progetto esistente

​Aggiungere servizi aggiuntivi

​Uso di Devcontainer

​Configurazione

​Impostazione degli alias della shell

​Ricostruzione delle immagini

​Avvio e arresto

​Flusso di avvio

​Esecuzione dei comandi

​Comandi PHP

​Comandi Composer

​Comandi Artisan

​Comandi Node / NPM

​CLI del container (shell)

​Servizi

​MySQL

​Redis

​Valkey

​Mailpit

​Meilisearch / Typesense

​RustFS (storage S3-compatibile)

​Esecuzione dei test

​Laravel Dusk

​Versione di PHP / Node

​Cambiare la versione di PHP

​Estensioni PHP aggiuntive

​Cambiare la versione di Node

​Condivisione pubblica del sito

​Xdebug

​Attivazione

​Debug via CLI

​Debug via browser

​Personalizzazione

​Differenze rispetto alla produzione

Cos’è Sail

Installazione

Installazione in un progetto esistente

Aggiungere servizi aggiuntivi

Uso di Devcontainer

Configurazione

Impostazione degli alias della shell

Ricostruzione delle immagini

Avvio e arresto

Flusso di avvio

Esecuzione dei comandi

Comandi PHP

Comandi Composer

Comandi Artisan

Comandi Node / NPM

CLI del container (shell)

Servizi

MySQL

Redis

Valkey

Mailpit

Meilisearch / Typesense

RustFS (storage S3-compatibile)

Esecuzione dei test

Laravel Dusk

Versione di PHP / Node

Cambiare la versione di PHP

Estensioni PHP aggiuntive

Cambiare la versione di Node

Condivisione pubblica del sito

Xdebug

Attivazione

Debug via CLI

Debug via browser

Personalizzazione

Differenze rispetto alla produzione