Идёт обновление сайта. Несколько дней возможны сбои в оформлении и переводах. Документация работает — если страница выглядит сломанной, обновите её позже.

Документация
L Laravel ✓ L intervention/image ✓
10.x ✓
🇷🇺 Русский ✓🇪🇸 Español ✓🇯🇵 日本語 ✓
Войти
Главная Laravel 10.x Laravel Envoy

Laravel Envoy

10.x 7 мар 2026 г.

#Введение

Laravel Envoy — это инструмент для выполнения часто используемых задач на удалённых серверах. Используя синтаксис в стиле Blade, вы можете легко настроить задачи для деплоя, команд Artisan и других операций. В настоящее время Envoy поддерживает только операционные системы Mac и Linux. Однако поддержку Windows можно обеспечить с помощью WSL2.

#Установка

Сначала установите Envoy в ваш проект с помощью менеджера пакетов Composer:

composer require laravel/envoy --dev

После установки Envoy бинарный файл Envoy будет доступен в директории vendor/bin вашего приложения:

php vendor/bin/envoy

#Написание задач

#Определение задач

Задачи — это базовые строительные блоки Envoy. Задачи определяют shell-команды, которые должны выполняться на ваших удалённых серверах при вызове задачи. Например, вы можете определить задачу, которая выполняет команду php artisan queue:restart на всех серверах обработчиков очередей вашего приложения.

Все ваши задачи Envoy должны быть определены в файле Envoy.blade.php в корне вашего приложения. Вот пример для начала работы:

@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

Как видите, в начале файла определён массив @servers, который позволяет ссылаться на эти серверы через опцию on в объявлениях задач. Объявление @servers всегда должно быть на одной строке. Внутри объявлений @task следует размещать shell-команды, которые должны выполняться на серверах при вызове задачи.

#Локальные задачи

Вы можете заставить скрипт выполняться на вашем локальном компьютере, указав IP-адрес сервера как 127.0.0.1:

@servers(['localhost' => '127.0.0.1'])

#Импорт задач Envoy

С помощью директивы @import вы можете импортировать другие файлы Envoy, чтобы их истории и задачи добавлялись к вашим. После импорта файлов вы можете выполнять содержащиеся в них задачи так, как если бы они были определены в вашем собственном файле Envoy:

@import('vendor/package/Envoy.blade.php')

#Несколько серверов

Envoy позволяет легко запускать задачу на нескольких серверах. Сначала добавьте дополнительные серверы в объявление @servers. Каждому серверу должно быть присвоено уникальное имя. После определения дополнительных серверов вы можете перечислить их в массиве on задачи:

@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

#Параллельное выполнение

По умолчанию задачи выполняются на каждом сервере последовательно. Другими словами, задача завершится на первом сервере, прежде чем начнётся выполнение на втором. Если вы хотите запускать задачу на нескольких серверах параллельно, добавьте опцию parallel в объявление задачи:

@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

#Настройка

Иногда может потребоваться выполнить произвольный PHP-код перед запуском задач Envoy. Вы можете использовать директиву @setup для определения блока PHP-кода, который будет выполнен перед задачами:

@setup
    $now = new DateTime;
@endsetup

Если необходимо подключить другие PHP-файлы перед выполнением задачи, используйте директиву @include в начале файла Envoy.blade.php:

@include('vendor/autoload.php')

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

#Переменные

При необходимости вы можете передавать аргументы в задачи Envoy, указывая их в командной строке при вызове Envoy:

php vendor/bin/envoy run deploy --branch=master

Вы можете обращаться к опциям внутри задач, используя синтаксис "echo" Blade. Также можно определять условные операторы if и циклы Blade внутри задач. Например, проверим наличие переменной $branch перед выполнением команды git pull:

@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

#Истории

Истории группируют набор задач под одним удобным именем. Например, история deploy может запускать задачи update-code и install-dependencies, перечисляя их имена в своём определении:

@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

После написания истории вы можете вызвать её так же, как и задачу:

php vendor/bin/envoy run deploy

#Хуки

При выполнении задач и историй запускается ряд хуков. Типы хуков, поддерживаемые Envoy: @before, @after, @error, @success и @finished. Весь код в этих хуках интерпретируется как PHP и выполняется локально, а не на удалённых серверах, с которыми взаимодействуют ваши задачи.

Вы можете определить любое количество хуков каждого типа. Они будут выполняться в порядке появления в вашем скрипте Envoy.

#@before

Перед выполнением каждой задачи будут выполнены все хуки @before, зарегистрированные в вашем скрипте Envoy. Хуки @before получают имя задачи, которая будет выполнена:

@before
    if ($task === 'deploy') {
        // ...
    }
@endbefore

#@after

После выполнения каждой задачи будут выполнены все хуки @after, зарегистрированные в вашем скрипте Envoy. Хуки @after получают имя выполненной задачи:

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

#@error

После каждой неудачи задачи (выход с кодом состояния больше 0) будут выполнены все хуки @error, зарегистрированные в вашем скрипте Envoy. Хуки @error получают имя выполненной задачи:

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

#@success

Если все задачи выполнились без ошибок, будут выполнены все хуки @success, зарегистрированные в вашем скрипте Envoy:

@success
    // ...
@endsuccess

#@finished

После выполнения всех задач (независимо от кода завершения) будут выполнены все @finished-хуки. @finished-хуки получают код завершения выполненной задачи, который может быть null или integer, больше либо равен 0:

@finished
    if ($exitCode > 0) {
        // В одной из задач произошли ошибки...
    }
@endfinished

#Запуск задач

Чтобы запустить задачу или историю, определённую в файле Envoy.blade.php вашего приложения, выполните команду run Envoy, передав имя задачи или истории, которую хотите выполнить. Envoy выполнит задачу и покажет вывод с ваших удалённых серверов во время выполнения:

php vendor/bin/envoy run deploy

#Подтверждение выполнения задачи

Если вы хотите, чтобы перед запуском задачи на серверах появлялся запрос подтверждения, добавьте директиву confirm в объявление задачи. Эта опция особенно полезна для операций, которые могут повредить данные:

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

#Уведомления

#Slack

Envoy поддерживает отправку уведомлений в Slack после выполнения каждой задачи. Директива @slack принимает URL вебхука Slack и имя канала или пользователя. Вы можете получить URL вебхука, создав интеграцию "Incoming WebHooks" в панели управления Slack.

Передайте полный webhook URL в качестве первого аргумента директивы @slack. Вторым аргументом директивы @slack должно быть имя канала (#channel) или имя пользователя (@user):

@finished
    @slack('webhook-url', '#bots')
@endfinished

По умолчанию уведомления Envoy отправляют сообщение в указанный канал с описанием выполненной задачи. Однако вы можете переопределить это сообщение, передав третий аргумент в директиву @slack:

@finished
    @slack('webhook-url', '#bots', 'Hello, Slack.')
@endfinished

#Discord

Envoy также поддерживает отправку уведомлений в Discord после выполнения каждой задачи. Директива @discord принимает URL вебхука Discord и сообщение. Вы можете получить URL вебхука, создав "Webhook" в настройках сервера и выбрав канал для публикации. Полный URL вебхука следует передать в директиву @discord:

@finished
    @discord('discord-webhook-url')
@endfinished

#Telegram

Envoy также поддерживает отправку уведомлений в Telegram после выполнения каждой задачи. Директива @telegram принимает ID бота Telegram и ID чата. Вы можете получить ID бота, создав нового бота через BotFather. Для получения валидного ID чата используйте @username_to_id_bot. Полные ID бота и чата следует передать в директиву @telegram:

@finished
    @telegram('bot-id','chat-id')
@endfinished

#Microsoft Teams

Envoy также поддерживает отправку уведомлений в Microsoft Teams после выполнения каждой задачи. Директива @microsoftTeams принимает Teams Webhook (обязательный), сообщение, цвет темы (success, info, warning, error) и массив опций. Вы можете получить Teams Webhook, создав новый входящий вебхук. API Teams поддерживает множество других атрибутов для настройки сообщения, таких как заголовок, краткое описание и секции. Подробнее можно узнать в документации Microsoft Teams. Полный URL вебхука следует передать в директиву @microsoftTeams:

@finished
    @microsoftTeams('webhook-url')
@endfinished
← Предыдущая
Laravel Dusk