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

> Uitleg over het definiëren en uitvoeren van deploytaken en Artisan-commando's op remote servers met Laravel Envoy en Blade-syntaxis.

## Aan de slag

[Laravel Envoy](https://github.com/laravel/envoy) is een tool om veelgebruikte taken op remote servers uit te voeren. Met dezelfde syntaxis als [Blade](/nl/blade) kun je eenvoudig taken definiëren zoals deploys en het uitvoeren van Artisan-commando's.

<Info>
  Envoy ondersteunt momenteel alleen macOS en Linux. Wil je het op Windows gebruiken, dan moet dat via [WSL2](https://docs.microsoft.com/ja-jp/windows/wsl/install-win10).
</Info>

## Installatie

Installeer Envoy in je project met de Composer-pakketmanager.

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

Na de installatie is het uitvoerbare bestand van Envoy beschikbaar in de map `vendor/bin`.

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

## Taken schrijven

### Taken definiëren

Taken zijn de fundamentele bouwsteen van Envoy. Een taak definieert de shellcommando's die op de remote server moeten worden uitgevoerd wanneer de taak wordt uitgevoerd. Je kunt bijvoorbeeld een taak definiëren die het commando `php artisan queue:restart` op alle queue-workerservers uitvoert.

Alle Envoy-taken definieer je in het bestand `Envoy.blade.php` in de root van je applicatie.

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

Zoals hierboven te zien is, definieer je bovenaan het bestand een `@servers`-array en verwijs je met de `on`-optie van elke taakdeclaratie naar deze servers. Schrijf de `@servers`-declaratie altijd op één regel. Binnen een `@task`-declaratie schrijf je de shellcommando's die bij het uitvoeren van de taak op de server worden uitgevoerd.

#### Lokale taken

Door het IP-adres van de server op te geven als `127.0.0.1`, kun je een script geforceerd op je lokale computer laten draaien.

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

#### Envoy-taken importeren

Met de `@import`-directive kun je andere Envoy-bestanden importeren en hun stories en taken aan je eigen bestand toevoegen. Na het importeren kun je die taken uitvoeren alsof je ze in je eigen Envoy-bestand hebt gedefinieerd.

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

### Meerdere servers

Met Envoy kun je één taak gemakkelijk op meerdere servers uitvoeren. Registreer eerst extra servers in de `@servers`-declaratie en geef elke server een unieke naam. Zodra je servers hebt toegevoegd, som je ze op in de `on`-array van de taak.

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

#### Parallelle uitvoering

Standaard wordt een taak serieel op elke server uitgevoerd. Dat wil zeggen: pas nadat een taak op de eerste server is voltooid, gaat de uitvoering verder op de tweede server. Wil je een taak parallel op meerdere servers uitvoeren, voeg dan de optie `parallel` toe aan de taakdeclaratie.

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

Moet je willekeurige PHP-code uitvoeren voordat een Envoy-taak wordt uitgevoerd, gebruik dan de `@setup`-directive.

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

Moet je vóór de taakuitvoering andere PHP-bestanden inladen, gebruik dan de `@include`-directive bovenaan je `Envoy.blade.php`-bestand.

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

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

### Variabelen

Bij het aanroepen van een Envoy-taak kun je argumenten opgeven op de commandoregel en aan de taak doorgeven.

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

Binnen een taak heb je via de "echo"-syntaxis van Blade toegang tot de opties. Je kunt ook Blade-`if`-statements en lussen definiëren. Wil je bijvoorbeeld het bestaan van de variabele `$branch` controleren voordat je het `git pull`-commando uitvoert, dan doe je dat zo:

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

### Stories

Stories groeperen een reeks taken onder één handige naam. Zo kun je bijvoorbeeld met een `deploy`-story de taken `update-code` en `install-dependencies` gebundeld uitvoeren.

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

Zodra je de story hebt geschreven, roep je die op dezelfde manier aan als een taak.

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

### Voltooiingshooks

Bij het uitvoeren van taken en stories worden meerdere hooks uitgevoerd. De hooktypen die Envoy ondersteunt zijn `@before`, `@after`, `@error`, `@success` en `@finished`. Alle code binnen deze hooks wordt geïnterpreteerd als PHP en **lokaal** uitgevoerd, niet op de remote servers waar je taken op werken.

Je kunt van elke hook zoveel definiëren als je wilt; ze worden uitgevoerd in de volgorde waarin ze in je Envoy-script staan.

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

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

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

@success
    // ...
@endsuccess

@finished
    if ($exitCode > 0) {
        // Er is in een van de taken een fout opgetreden...
    }
@endfinished
```

De `@finished`-hook ontvangt de statuscode van de voltooide taak. De statuscode is `null` of een geheel getal van `0` of hoger.

## Taken uitvoeren

Om taken of stories uit te voeren die je in het `Envoy.blade.php`-bestand van je applicatie hebt gedefinieerd, voer je het `run`-commando van Envoy uit met de naam van de taak of story die je wilt uitvoeren. Envoy voert de taak uit en toont tijdens de uitvoering de uitvoer van de remote servers.

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

### Bevestiging van taakuitvoering

Wil je om bevestiging vragen voordat een bepaalde taak op je servers wordt uitgevoerd, voeg dan de `confirm`-directive toe aan de taakdeclaratie. Deze functie is vooral handig bij destructieve operaties.

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

## Notificaties

### Slack

Envoy kan na elke taakuitvoering een notificatie naar [Slack](https://slack.com) sturen. De `@slack`-directive ontvangt een Slack-webhook-URL en een kanaalnaam (of gebruikersnaam). De webhook-URL verkrijg je door in het Slack-configuratiescherm een "Incoming WebHooks"-integratie aan te maken.

Als eerste argument van de `@slack`-directive geef je de volledige webhook-URL door. Als tweede argument geef je een kanaalnaam (`#channel`) of gebruikersnaam (`@user`) op.

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

Standaard wordt een bericht dat de uitgevoerde taak beschrijft naar het notificatiekanaal gestuurd. Door een derde argument aan de `@slack`-directive door te geven, kun je dit overschrijven met je eigen bericht.

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

### Discord

Envoy ondersteunt ook het sturen van notificaties naar [Discord](https://discord.com) na elke taakuitvoering. De `@discord`-directive ontvangt een Discord-webhook-URL en een bericht. De webhook-URL verkrijg je door in de serverinstellingen een "Webhook" aan te maken en het kanaal te kiezen waarin gepost moet worden.

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

### Telegram

Envoy ondersteunt ook het sturen van notificaties naar [Telegram](https://telegram.org) na elke taakuitvoering. De `@telegram`-directive ontvangt een Telegram-bot-ID en een chat-ID. De bot-ID verkrijg je door een nieuwe bot aan te maken via [BotFather](https://t.me/botfather). De chat-ID kun je verkrijgen met [@username\_to\_id\_bot](https://t.me/username_to_id_bot).

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

### Microsoft Teams

Envoy ondersteunt ook het sturen van notificaties naar [Microsoft Teams](https://www.microsoft.com/microsoft-teams) na elke taakuitvoering. De `@teams`-directive ontvangt een Teams-webhook (vereist), een bericht, een themakleur (success, info, warning, error) en een optionele configuratie-array. De Teams-webhook verkrijg je door een [Incoming Webhook](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook) aan te maken. De Teams-API heeft nog veel meer configuratieopties waarmee je vrij je eigen berichtkaarten kunt samenstellen. Zie de [Microsoft Teams-documentatie](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using) voor details.

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

<Warning>
  Envoy gaat uit van een [SSH](https://ja.wikipedia.org/wiki/Secure_Shell)-verbinding naar de remote server. Afhankelijk van je omgeving moet je vooraf sleutelauthenticatie configureren en de toegangscontrole tot je servers regelen. Heb je geavanceerdere deploy-automatisering nodig, overweeg dan ook de [deployment](/nl/deployment)-gids of een combinatie met [GitHub Actions](/nl/advanced/github-actions-pinning).
</Warning>