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

# Envoy

> Come usare Laravel Envoy per definire ed eseguire task di deploy e comandi Artisan su server remoti usando la sintassi Blade.

## Introduzione

[Laravel Envoy](https://github.com/laravel/envoy) è uno strumento per eseguire task comuni su server remoti. Con la stessa sintassi di [Blade](/it/blade), definisci facilmente task come deploy o esecuzione di comandi Artisan.

<Info>
  Al momento Envoy supporta solo macOS e Linux. Su Windows va usato tramite [WSL2](https://docs.microsoft.com/it-it/windows/wsl/install-win10).
</Info>

## Installazione

Installa Envoy nel progetto tramite Composer.

```shell theme={null}
composer require laravel/envoy --dev
```

Dopo l'installazione, l'eseguibile di Envoy è disponibile in `vendor/bin`.

```shell theme={null}
php vendor/bin/envoy
```

## Creare task

### Definire un task

I task sono il mattone di base di Envoy. Un task definisce i comandi shell da eseguire sul server remoto quando lo si esegue. Ad esempio puoi definire un task che esegue `php artisan queue:restart` su tutti i server dei worker della coda.

Tutti i task di Envoy si definiscono nel file `Envoy.blade.php` nella root dell'applicazione.

```blade theme={null}
@servers(['web' => ['user@192.168.1.1'], 'workers' => ['user@192.168.1.2']])

@task('restart-queues', ['on' => 'workers'])
    cd /home/user/example.com
    php artisan queue:restart
@endtask
```

Come mostrato, definisci l'array `@servers` all'inizio del file e nei task fai riferimento a questi server tramite l'opzione `on`. La dichiarazione `@servers` va scritta obbligatoriamente su una sola riga. Dentro `@task` scrivi i comandi shell da eseguire sul server quando il task viene lanciato.

#### Task locali

Specificando come indirizzo IP `127.0.0.1` puoi forzare l'esecuzione dello script sul computer locale.

```blade theme={null}
@servers(['localhost' => '127.0.0.1'])
```

#### Importare task Envoy

Con la direttiva `@import` puoi importare altri file Envoy e aggiungere le loro story e i loro task al tuo file. Dopo l'import puoi eseguire i task come se fossero definiti nel tuo Envoy file.

```blade theme={null}
@import('vendor/package/Envoy.blade.php')
```

### Più server

Con Envoy puoi eseguire facilmente un task su più server. Aggiungi i server nella dichiarazione `@servers` assegnando un nome univoco a ciascuno, poi elencali nell'array `on` del task.

```blade theme={null}
@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])

@task('deploy', ['on' => ['web-1', 'web-2']])
    cd /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate --force
@endtask
```

#### Esecuzione in parallelo

Per default il task viene eseguito in serie: dopo che è terminato sul primo server passa al secondo. Per eseguire il task in parallelo su più server, aggiungi l'opzione `parallel` alla dichiarazione del task.

```blade theme={null}
@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])

@task('deploy', ['on' => ['web-1', 'web-2'], 'parallel' => true])
    cd /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate --force
@endtask
```

### Setup

Se devi eseguire del codice PHP prima di lanciare i task Envoy, usa la direttiva `@setup`.

```php theme={null}
@setup
    $now = new DateTime;
@endsetup
```

Se devi caricare altri file PHP prima dell'esecuzione dei task, usa la direttiva `@include` all'inizio di `Envoy.blade.php`.

```blade theme={null}
@include('vendor/autoload.php')

@task('restart-queues')
    # ...
@endtask
```

### Variabili

Quando esegui un task Envoy puoi passare argomenti da riga di comando.

```shell theme={null}
php vendor/bin/envoy run deploy --branch=master
```

All'interno del task, con la sintassi "echo" di Blade accedi alle opzioni. Puoi usare anche `if` e cicli di Blade. Ad esempio, per verificare che la variabile `$branch` esista prima di eseguire `git pull`:

```blade theme={null}
@servers(['web' => ['user@192.168.1.1']])

@task('deploy', ['on' => 'web'])
    cd /home/user/example.com

    @if ($branch)
        git pull origin {{ $branch }}
    @endif

    php artisan migrate --force
@endtask
```

### Story

Una story raggruppa una sequenza di task sotto un unico nome comodo. Ad esempio la story `deploy` esegue insieme i task `update-code` e `install-dependencies`.

```blade theme={null}
@servers(['web' => ['user@192.168.1.1']])

@story('deploy')
    update-code
    install-dependencies
@endstory

@task('update-code')
    cd /home/user/example.com
    git pull origin master
@endtask

@task('install-dependencies')
    cd /home/user/example.com
    composer install
@endtask
```

Una story si esegue come un normale task.

```shell theme={null}
php vendor/bin/envoy run deploy
```

### Hook di completamento

Durante l'esecuzione di task e story vengono lanciati diversi hook. Envoy supporta `@before`, `@after`, `@error`, `@success` e `@finished`. Il codice dentro questi hook è interpretato come PHP e viene eseguito **in locale**, non sui server remoti su cui opera il task.

Puoi definire tutti gli hook che vuoi; vengono eseguiti nell'ordine in cui compaiono nello script Envoy.

```blade theme={null}
@before
    if ($task === 'deploy') {
        // ...
    }
@endbefore

@after
    if ($task === 'deploy') {
        // ...
    }
@endafter

@error
    if ($task === 'deploy') {
        // ...
    }
@enderror

@success
    // ...
@endsuccess

@finished
    if ($exitCode > 0) {
        // uno dei task ha avuto un errore...
    }
@endfinished
```

L'hook `@finished` riceve lo status code del task completato. Lo status code è `null` oppure un intero >= 0.

## Eseguire i task

Per eseguire un task o una story definiti in `Envoy.blade.php`, esegui il comando `run` di Envoy passandone il nome. Envoy esegue il task e mostra in tempo reale l'output dai server remoti.

```shell theme={null}
php vendor/bin/envoy run deploy
```

### Conferma dell'esecuzione

Se vuoi chiedere conferma prima di eseguire un task, aggiungi la direttiva `confirm` alla dichiarazione. È utile soprattutto per operazioni distruttive.

```blade theme={null}
@task('deploy', ['on' => 'web', 'confirm' => true])
    cd /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate
@endtask
```

## Notifiche

### Slack

Envoy può inviare una notifica a [Slack](https://slack.com) dopo ogni esecuzione. La direttiva `@slack` accetta l'URL del webhook Slack e il nome del canale (o utente). L'URL del webhook si ottiene creando un'integrazione "Incoming WebHooks" dal pannello di Slack.

Come primo argomento passi l'intero URL del webhook; come secondo, un canale (`#channel`) o un utente (`@user`).

```blade theme={null}
@finished
    @slack('webhook-url', '#bots')
@endfinished
```

Di default viene inviato un messaggio che descrive il task eseguito. Passando un terzo argomento a `@slack` puoi sovrascriverlo con un messaggio personalizzato.

```blade theme={null}
@finished
    @slack('webhook-url', '#bots', 'Hello, Slack.')
@endfinished
```

### Discord

Envoy supporta anche l'invio di notifiche a [Discord](https://discord.com) dopo ogni esecuzione. La direttiva `@discord` accetta URL del webhook Discord e messaggio. Il webhook si crea nelle impostazioni del server scegliendo "Webhook" e il canale di destinazione.

```blade theme={null}
@finished
    @discord('discord-webhook-url')
@endfinished
```

### Telegram

Envoy supporta anche notifiche a [Telegram](https://telegram.org) dopo ogni esecuzione. La direttiva `@telegram` accetta Bot ID e Chat ID Telegram. Il Bot ID si ottiene creando un nuovo bot con [BotFather](https://t.me/botfather); il Chat ID si ricava con [@username\_to\_id\_bot](https://t.me/username_to_id_bot).

```blade theme={null}
@finished
    @telegram('bot-id','chat-id')
@endfinished
```

### Microsoft Teams

Envoy supporta anche notifiche a [Microsoft Teams](https://www.microsoft.com/microsoft-teams) dopo ogni esecuzione. La direttiva `@teams` accetta il webhook Teams (obbligatorio), un messaggio, il colore del tema (success, info, warning, error) e un array di configurazione opzionale. Il webhook Teams si ottiene creando un [Incoming Webhook](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook). L'API Teams ha molte altre opzioni con cui puoi comporre le tue message card. Per i dettagli consulta la [documentazione di Microsoft Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using).

```blade theme={null}
@finished
    @teams('webhook-url')
@endfinished
```

<Warning>
  Envoy presuppone una connessione [SSH](https://it.wikipedia.org/wiki/Secure_Shell) ai server remoti. In base all'ambiente devi predisporre autenticazione a chiave e controlli di accesso. Per un'automazione di deploy più avanzata, valuta anche la guida [Deployment](/it/deployment) o l'integrazione con [GitHub Actions](/it/advanced/github-actions-pinning).
</Warning>