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

> Explica cómo definir y ejecutar tareas de despliegue y comandos Artisan sobre servidores remotos con sintaxis Blade usando Laravel Envoy.

## Introducción

[Laravel Envoy](https://github.com/laravel/envoy) es una herramienta para ejecutar tareas habituales en servidores remotos. Con la misma sintaxis de [Blade](/es/blade) puedes definir fácilmente tareas como despliegues o la ejecución de comandos Artisan.

<Info>
  Envoy solo soporta actualmente macOS y Linux. Para usarlo en Windows necesitas hacerlo a través de [WSL2](https://docs.microsoft.com/es-es/windows/wsl/install-win10).
</Info>

## Instalación

Instala Envoy en el proyecto con el gestor de paquetes Composer.

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

Tras la instalación, el ejecutable de Envoy quedará disponible en el directorio `vendor/bin`.

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

## Creación de tareas

### Definir una tarea

Las tareas son la unidad básica de Envoy. Una tarea define los comandos de shell que deben ejecutarse en el servidor remoto al lanzarla. Por ejemplo, puedes definir una tarea que ejecute `php artisan queue:restart` en todos los servidores de workers de cola.

Todas las tareas de Envoy se definen en el archivo `Envoy.blade.php` que está en la raíz de la aplicación.

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

Como se ve arriba, al principio del archivo defines el array `@servers` y en la opción `on` de cada declaración de tarea haces referencia a esos servidores. La declaración `@servers` debe escribirse siempre en una sola línea. Dentro de la declaración `@task` describes los comandos de shell que se ejecutarán en el servidor al lanzar la tarea.

#### Tareas locales

Si indicas `127.0.0.1` como IP del servidor, forzarás la ejecución del script en tu equipo local.

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

#### Importar tareas de Envoy

Con la directiva `@import` puedes importar otros archivos de Envoy y añadir sus stories y tareas a tu propio archivo. Tras la importación, puedes ejecutar las tareas igual que si las hubieras definido en tu archivo Envoy.

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

### Múltiples servidores

Con Envoy puedes ejecutar fácilmente una misma tarea en varios servidores. Primero añade servidores adicionales a la declaración `@servers` asignándoles un nombre único. Una vez añadidos, enuméralos en el array `on` de la tarea.

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

#### Ejecución en paralelo

Por defecto, las tareas se ejecutan de forma serial en cada servidor. Es decir, cuando una tarea finaliza en el primer servidor, pasa al segundo. Para ejecutar la tarea en paralelo en varios servidores, añade la opción `parallel` a la declaración.

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

Si necesitas ejecutar código PHP arbitrario antes de que se lancen las tareas de Envoy, usa la directiva `@setup`.

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

Si necesitas incluir otros archivos PHP antes de ejecutar las tareas, utiliza `@include` al principio del archivo `Envoy.blade.php`.

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

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

### Variables

Al invocar una tarea de Envoy, puedes pasar argumentos desde la línea de comandos.

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

Dentro de la tarea puedes acceder a las opciones con la sintaxis «echo» de Blade. También puedes usar los `if` y bucles de Blade. Por ejemplo, para comprobar si existe la variable `$branch` antes de ejecutar `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

Una story agrupa un conjunto de tareas bajo un nombre cómodo. Por ejemplo, una story `deploy` puede ejecutar juntas las tareas `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 vez escrita la story, puedes invocarla igual que una tarea.

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

### Hooks de finalización

Al ejecutar tareas o stories se ejecutan varios hooks. Los tipos que soporta Envoy son `@before`, `@after`, `@error`, `@success` y `@finished`. Todo el código dentro de estos hooks se interpreta como PHP y se ejecuta **en local**, no en los servidores remotos sobre los que opera la tarea.

Puedes definir tantos hooks como quieras, y se ejecutarán en el orden en que aparezcan en el script de 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) {
        // Alguna de las tareas ha fallado...
    }
@endfinished
```

El hook `@finished` recibe el código de estado de la ejecución de las tareas. Es `null` o un entero mayor o igual que 0.

## Ejecutar tareas

Para ejecutar una tarea o story definida en el archivo `Envoy.blade.php` de la aplicación, ejecuta el comando `run` de Envoy y pásale el nombre de la tarea o story. Envoy ejecutará la tarea y mostrará la salida del servidor remoto durante la ejecución.

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

### Confirmar la ejecución de la tarea

Si quieres solicitar confirmación antes de ejecutar una tarea concreta en el servidor, añade la directiva `confirm` a la declaración de la tarea. Es especialmente útil para operaciones destructivas.

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

## Notificaciones

### Slack

Envoy puede enviar notificaciones a [Slack](https://slack.com) tras la ejecución de cada tarea. La directiva `@slack` recibe la URL del webhook de Slack y el nombre del canal (o del usuario). La URL del webhook se obtiene creando una integración «Incoming WebHooks» en el panel de control de Slack.

En el primer argumento de `@slack` pasa la URL completa del webhook. En el segundo indica el nombre del canal (`#channel`) o del usuario (`@user`).

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

Por defecto, se envía al canal un mensaje que describe la tarea ejecutada. Puedes sobrescribirlo con tu propio mensaje pasando un tercer argumento a `@slack`.

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

### Discord

Envoy también permite enviar notificaciones a [Discord](https://discord.com) tras cada ejecución. La directiva `@discord` recibe la URL del webhook de Discord y un mensaje. La URL se obtiene creando un «Webhook» en la configuración del servidor y seleccionando el canal de destino.

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

### Telegram

Envoy también admite enviar notificaciones a [Telegram](https://telegram.org) tras cada ejecución. La directiva `@telegram` recibe el ID del bot de Telegram y el Chat ID. El ID del bot se obtiene creando un nuevo bot en [BotFather](https://t.me/botfather). El Chat ID puede obtenerse 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 también admite enviar notificaciones a [Microsoft Teams](https://www.microsoft.com/microsoft-teams) tras cada ejecución. La directiva `@teams` recibe el webhook de Teams (obligatorio), el mensaje, un color de tema (success, info, warning, error) y, opcionalmente, un array de configuración. El webhook de Teams se obtiene creando un [Incoming Webhook](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook). La API de Teams tiene muchos más ajustes que te permiten crear tus propias tarjetas de mensaje. Para más detalles consulta la [documentación de 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 asume conexiones [SSH](https://es.wikipedia.org/wiki/Secure_Shell) con los servidores remotos. Según tu entorno de ejecución, deberás preparar de antemano la configuración de la autenticación por clave y el control de acceso al servidor. Si necesitas una automatización de despliegue más avanzada, valora la [guía de despliegue](/es/deployment) o la combinación con [GitHub Actions](/es/advanced/github-actions-pinning).
</Warning>