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

> Come costruire un ambiente di sviluppo locale basato su Docker senza configurazioni usando Laravel Sail.

## Cos'è Sail

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

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

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

  Se ti servono i container Docker, puoi comunque installare e usare Sail.
</Warning>

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

***

## Installazione

### Installazione in un progetto esistente

Installa il pacchetto con Composer.

<Steps>
  <Step title="Aggiungi il pacchetto Sail">
    ```shell theme={null}
    composer require laravel/sail --dev
    ```
  </Step>

  <Step title="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`.

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

    Puoi scegliere i servizi in modo interattivo. Seleziona MySQL, Redis, Mailpit, ecc.
  </Step>

  <Step title="Avvia Sail">
    ```shell theme={null}
    ./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`.
  </Step>
</Steps>

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

### Aggiungere servizi aggiuntivi

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

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

### Uso di Devcontainer

Se vuoi sviluppare all'interno di un [Devcontainer](https://code.visualstudio.com/docs/remote/containers), usa l'opzione `--devcontainer`.

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

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

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

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

<Tip>
  Dopo aver impostato l'alias, in tutti gli esempi di comando di questa documentazione puoi scrivere `sail` al posto di `./vendor/bin/sail`.
</Tip>

### Ricostruzione delle immagini

Se vuoi mantenere i pacchetti aggiornati, ricostruisci le immagini.

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

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

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

### Flusso di avvio

```mermaid theme={null}
flowchart TD
    A["Esegui sail up"] --> B{"L'immagine Docker<br>esiste?"}
    B -- No --> C["Build/<br>download dell'immagine"]
    C --> D["Avvio dei container"]
    B -- Sì --> D
    D --> E["Avvio container laravel.test<br>(app)"]
    D --> F["Avvio container mysql"]
    D --> G["Avvio container redis"]
    D --> H["Avvio container mailpit"]
    E --> I["Accessibile su http://localhost"]
```

***

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

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

### Comandi PHP

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

sail php script.php
```

### Comandi Composer

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

### Comandi Artisan

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

sail artisan queue:work
```

### Comandi Node / NPM

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

```shell theme={null}
sail shell

# Collegati come utente root
sail root-shell
```

Per aprire una sessione Tinker:

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

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

Per collegarti dalla macchina locale usa un tool GUI come [TablePlus](https://tableplus.com). La porta predefinita è `3306`.

### Redis

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

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

### Valkey

Se usi [Valkey](https://valkey.io/) 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.

```ini theme={null}
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](/it/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.

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

***

## Esecuzione dei test

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

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

<Tip>
  Su Apple Silicon (M1/M2/M3) usa l'immagine `selenium/standalone-chromium`.
</Tip>

Poi esegui i test Dusk.

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

***

## Versione di PHP / Node

### Cambiare la versione di PHP

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

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

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

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

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

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

### Cambiare la versione di Node

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

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

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

Puoi anche specificare un sottodominio.

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

***

## Xdebug

### Attivazione

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

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

Verifica che il file `php.ini` pubblicato contenga:

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

Dopo la modifica ricostruisci l'immagine.

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

### Debug via CLI

```shell theme={null}
# 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](https://xdebug.org/docs/step_debug#web-application).
Se usi PhpStorm è comoda la configurazione [Zero-configuration debugging](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html).

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

***

## Personalizzazione

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

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

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

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

***

## Differenze rispetto alla produzione

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

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 |


## Related topics

- [Laravel Boost Custom Agent for GitHub Copilot CLI](/it/packages/laravel-boost-copilot-cli.md)
- [Redis](/it/redis.md)
- [Console Artisan](/it/artisan.md)
- [Laravel Scout](/it/scout.md)
- [Conoscenze necessarie prima di iniziare con Laravel](/it/true-tutorial.md)