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

> Découvrez comment définir et exécuter des tâches de déploiement et des commandes Artisan sur des serveurs distants avec Laravel Envoy en utilisant la syntaxe Blade.

## Introduction

[Laravel Envoy](https://github.com/laravel/envoy) est un outil qui permet d'exécuter des tâches courantes sur des serveurs distants. Grâce à la même syntaxe que [Blade](/fr/blade), vous pouvez définir facilement des tâches de déploiement ou d'exécution de commandes Artisan.

<Info>
  Envoy ne prend actuellement en charge que macOS et Linux. Sous Windows, vous devrez l'utiliser via [WSL2](https://docs.microsoft.com/fr-fr/windows/wsl/install-win10).
</Info>

## Installation

Installez Envoy dans votre projet via le gestionnaire de packages Composer.

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

Une fois installé, l'exécutable d'Envoy est disponible dans le répertoire `vendor/bin`.

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

## Création de tâches

### Définir une tâche

Les tâches sont l'élément de base d'Envoy. Une tâche définit les commandes shell à exécuter sur un serveur distant lorsque la tâche est lancée. Vous pouvez par exemple définir une tâche qui exécute `php artisan queue:restart` sur tous les serveurs de workers de queue.

Toutes les tâches Envoy se déclarent dans le fichier `Envoy.blade.php` à la racine de votre application.

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

Comme ci-dessus, on définit d'abord un tableau `@servers` en haut du fichier, puis on référence ces serveurs via l'option `on` de chaque déclaration de tâche. La déclaration `@servers` doit tenir sur une seule ligne. À l'intérieur d'un `@task`, vous décrivez les commandes shell à exécuter sur le serveur lors de l'exécution.

#### Tâches locales

En précisant l'adresse IP `127.0.0.1` du serveur, vous forcez l'exécution du script sur votre machine locale.

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

#### Importer un fichier Envoy

La directive `@import` permet d'importer d'autres fichiers Envoy afin d'ajouter leurs stories et leurs tâches au fichier courant. Une fois importées, vous exécutez ces tâches exactement comme celles définies dans votre propre fichier Envoy.

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

### Plusieurs serveurs

Envoy permet d'exécuter facilement une même tâche sur plusieurs serveurs. Enregistrez d'abord les serveurs supplémentaires dans la déclaration `@servers` en leur donnant à chacun un nom unique. Ensuite, listez ces serveurs dans le tableau `on` de la tâche.

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

#### Exécution en parallèle

Par défaut, la tâche s'exécute en série sur chaque serveur : l'exécution sur le second serveur ne démarre qu'une fois terminée sur le premier. Pour exécuter la tâche en parallèle, ajoutez l'option `parallel` à la déclaration de la tâche.

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

Utilisez la directive `@setup` pour exécuter du code PHP quelconque avant d'exécuter les tâches Envoy.

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

Si vous devez charger d'autres fichiers PHP avant les tâches, utilisez `@include` en haut de votre `Envoy.blade.php`.

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

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

### Variables

Lors du lancement d'une tâche Envoy, vous pouvez lui passer des arguments depuis la ligne de commande.

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

À l'intérieur de la tâche, ces options sont accessibles via la syntaxe « echo » de Blade. Les instructions `if` et les boucles Blade sont également disponibles. Par exemple, pour vérifier l'existence de la variable `$branch` avant d'exécuter `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
```

### Stories

Une story regroupe plusieurs tâches sous un nom pratique. Par exemple, une story `deploy` peut lancer à la suite les tâches `update-code` et `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
```

Une fois écrite, la story s'appelle comme n'importe quelle tâche.

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

### Hooks d'exécution

Plusieurs hooks sont déclenchés lors de l'exécution d'une tâche ou d'une story. Envoy prend en charge `@before`, `@after`, `@error`, `@success` et `@finished`. Le code de ces hooks est interprété comme du PHP et s'exécute **en local**, pas sur les serveurs distants ciblés par la tâche.

Vous pouvez définir autant de hooks que vous voulez ; ils s'exécutent dans l'ordre où ils apparaissent dans votre 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) {
        // Une des tâches a échoué...
    }
@endfinished
```

Le hook `@finished` reçoit le code de sortie de la tâche terminée. Ce code peut être `null` ou un entier positif ou nul.

## Exécuter les tâches

Pour exécuter une tâche ou une story définie dans `Envoy.blade.php`, lancez la commande `run` d'Envoy en lui passant le nom de la tâche ou de la story. Envoy exécute la tâche et affiche en direct la sortie des serveurs distants.

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

### Confirmation avant exécution

Pour demander une confirmation avant d'exécuter une tâche donnée sur les serveurs, ajoutez la directive `confirm` à la déclaration de la tâche. C'est particulièrement utile pour les opérations destructrices.

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

## Notifications

### Slack

Envoy peut envoyer une notification vers [Slack](https://slack.com) à la fin de chaque tâche. La directive `@slack` accepte une URL de webhook Slack ainsi qu'un nom de canal (ou d'utilisateur). L'URL de webhook s'obtient en créant une intégration « Incoming WebHooks » dans le panneau de contrôle Slack.

Passez l'URL complète du webhook comme premier argument de `@slack`. Le deuxième argument est un nom de canal (`#channel`) ou d'utilisateur (`@user`).

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

Par défaut, un message décrivant la tâche exécutée est envoyé sur le canal. Vous pouvez le surcharger en passant un troisième argument à `@slack`.

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

### Discord

Envoy peut également notifier [Discord](https://discord.com) après chaque tâche. La directive `@discord` accepte l'URL de webhook Discord et un message. L'URL de webhook s'obtient en créant un « Webhook » dans les paramètres du serveur, en choisissant le canal cible.

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

### Telegram

Envoy peut aussi notifier [Telegram](https://telegram.org) après chaque tâche. La directive `@telegram` prend un Bot ID Telegram et un Chat ID. Le Bot ID s'obtient en créant un bot avec [BotFather](https://t.me/botfather). Pour le Chat ID, vous pouvez utiliser [@username\_to\_id\_bot](https://t.me/username_to_id_bot).

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

### Microsoft Teams

Envoy peut également notifier [Microsoft Teams](https://www.microsoft.com/microsoft-teams) après chaque tâche. La directive `@teams` prend un webhook Teams (obligatoire), un message, une couleur de thème (`success`, `info`, `warning`, `error`) et, en option, un tableau de configuration. Vous obtenez le webhook Teams en créant un [Incoming Webhook](https://learn.microsoft.com/fr-fr/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook). L'API Teams offre de nombreuses options pour composer vos propres cartes de message : consultez la [documentation Microsoft Teams](https://learn.microsoft.com/fr-fr/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using) pour plus de détails.

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

<Warning>
  Envoy s'appuie sur des connexions [SSH](https://fr.wikipedia.org/wiki/Secure_Shell) vers les serveurs distants. Selon votre environnement, vous devrez configurer préalablement l'authentification par clé et le contrôle d'accès. Pour une automatisation de déploiement plus poussée, consultez également le guide [Déploiement](/fr/deployment) ou l'utilisation combinée avec [GitHub Actions](/fr/advanced/github-actions-pinning).
</Warning>


## Related topics

- [Laravel Console Starter](/fr/packages/laravel-console-starter/index.md)
- [Démarrer - GitHub Copilot SDK pour Laravel](/fr/packages/laravel-copilot-sdk/getting-started.md)
- [Laravel Notification for Discord (Webhook)](/fr/packages/laravel-notification-discord-webhook.md)
- [Envoi d'e-mails](/fr/mail.md)
- [Cloud Sessions](/fr/packages/laravel-copilot-sdk/cloud-sessions.md)