Laravel 11.x Laravel Envoy

イントロダクションIntroduction

Laravel Envoy（アンボイ：特使）は、一般的なタスクをリモートサーバ上で実行するためのツールです。bladeスタイルの構文を使用し、デプロイやArtisanコマンドなどのタスクを簡単に設定できます。現在、EnvoyはMacおよびLinuxオペレーティングシステムのみをサポートしています。ただし、WindowsサポートはWSL2を使用して実現できます。Laravel Envoy[https://github.com/laravel/envoy] is a tool for executing common tasks you run on your remote servers. Using Blade[/docs/{{version}}/blade] style syntax, you can easily setup tasks for deployment, Artisan commands, and more. Currently, Envoy only supports the Mac and Linux operating systems. However, Windows support is achievable using WSL2[https://docs.microsoft.com/en-us/windows/wsl/install-win10].

インストールInstallation

まず、Composerパッケージマネージャを使用してEnvoyをプロジェクトにインストールします。First, install Envoy into your project using the Composer package manager:

composer require laravel/envoy --dev

Envoyがインストールされると、Envoyバイナリはアプリケーションのvendor/binディレクトリで利用できるようになります。Once Envoy has been installed, the Envoy binary will be available in your application's vendor/bin directory:

php vendor/bin/envoy

タスクの記述Writing Tasks

タスク定義Defining Tasks

タスクはEnvoyの基本的な設定要素です。タスクには、呼び出されたときにリモートサーバで実行する必要があるシェルコマンドを定義します。たとえば、アプリケーションのすべてのキューワーカーサーバでphp artisan queue:restartコマンドを実行するタスクを定義できます。Tasks are the basic building block of Envoy. Tasks define the shell commands that should execute on your remote servers when the task is invoked. For example, you might define a task that executes the php artisan queue:restart command on all of your application's queue worker servers.

すべてのEnvoyタスクは、アプリケーションのルートにあるEnvoy.blade.phpファイルで定義する必要があります。開始時に使えるサンプルを以下に示します。All of your Envoy tasks should be defined in an Envoy.blade.php file at the root of your application. Here's an example to get you started:

@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宣言は常に1行に配置する必要があります。@task宣言内に、タスクが呼び出されたときにサーバ上で実行する必要のあるシェルコマンドを配置する必要があります。As you can see, an array of @servers is defined at the top of the file, allowing you to reference these servers via the on option of your task declarations. The @servers declaration should always be placed on a single line. Within your @task declarations, you should place the shell commands that should execute on your servers when the task is invoked.

ローカルタスクLocal Tasks

サーバのIPアドレスを127.0.0.1として指定することにより、ローカルコンピューターでスクリプトを強制的に実行できます。You can force a script to run on your local computer by specifying the server's IP address as 127.0.0.1:

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

EnvoyタスクのインポートImporting Envoy Tasks

@importディレクティブを使用すると、他のEnvoyファイルをインポートして、それらのストーリーとタスクを自身へ追加できます。ファイルをインポートすると、そのファイルに含まれるタスクを、自身のEnvoyファイルで定義されているかのように実行できます。Using the @import directive, you may import other Envoy files so their stories and tasks are added to yours. After the files have been imported, you may execute the tasks they contain as if they were defined in your own Envoy file:

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

複数サーバMultiple Servers

Envoyを使用すると、複数のサーバ間でタスクを簡単に実行できます。まず、@servers宣言にサーバを追加します。各サーバには一意の名前を割り当てる必要があります。追加のサーバを定義したら、タスクのon配列へ各サーバをリストします。Envoy allows you to easily run a task across multiple servers. First, add additional servers to your @servers declaration. Each server should be assigned a unique name. Once you have defined your additional servers you may list each of the servers in the task's on array:

@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 Execution

デフォルトでは、タスクは各サーバで順次実行されます。つまり、タスクは、２番目のサーバでの実行に進む前に、最初のサーバでの実行を終了します。複数のサーバ間でタスクを並行して実行する場合は、タスク宣言にparallelオプションを追加します。By default, tasks will be executed on each server serially. In other words, a task will finish running on the first server before proceeding to execute on the second server. If you would like to run a task across multiple servers in parallel, add the parallel option to your task declaration:

@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

Envoyタスクを実行する前に、任意のPHPコードを実行する必要がある場合があります。@setupディレクティブを使用して、タスクの前に実行する必要があるPHPコードブロックを定義できます。Sometimes, you may need to execute arbitrary PHP code before running your Envoy tasks. You may use the @setup directive to define a block of PHP code that should execute before your tasks:

@setup
    $now = new DateTime;
@endsetup

タスクを実行する前に他のPHPファイルをリクエストする必要がある場合は、Envoy.blade.phpファイルの先頭にある@includeディレクティブを使用できます。If you need to require other PHP files before your task is executed, you may use the @include directive at the top of your Envoy.blade.php file:

@include('vendor/autoload.php')

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

変数Variables

必要に応じて、Envoyを呼び出すときにコマンドラインで引数を指定することにより、Envoyタスクに引数を渡すことができます。If needed, you may pass arguments to Envoy tasks by specifying them on the command line when invoking Envoy:

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

Bladeの「エコー（echo）」構文を使用して、タスク内のオプションにアクセスできます。タスク内でBladeのifステートメントとループを定義することもできます。例としてgit pullコマンドを実行する前に、$branch変数の存在を確認してみましょう。You may access the options within your tasks using Blade's "echo" syntax. You may also define Blade if statements and loops within your tasks. For example, let's verify the presence of the $branch variable before executing the git pull command:

@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

ストーリーは、一連のタスクを１つの便利な名前でグループ化します。たとえば、deployストーリーは、その定義内にタスク名をリストすることにより、update-codeおよびinstall-dependenciesタスクを実行できます。Stories group a set of tasks under a single, convenient name. For instance, a deploy story may run the update-code and install-dependencies tasks by listing the task names within its definition:

@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

ストーリーを作成したら、タスクの呼び出しと同じ方法でストーリーを呼び出せます。Once the story has been written, you may invoke it in the same way you would invoke a task:

php vendor/bin/envoy run deploy

フックHooks

タスクとストーリーが実行されると、いくつかのフックが実行されます。Envoyがサポートしているフックタイプは@before、@after、@error、@success、@finishedです。これらのフック内のすべてのコードはPHPとして解釈され、ローカルで実行されます。タスクが操作するリモートサーバ上では実行されません。When tasks and stories run, a number of hooks are executed. The hook types supported by Envoy are @before, @after, @error, @success, and @finished. All of the code in these hooks is interpreted as PHP and executed locally, not on the remote servers that your tasks interact with.

好きなようにこれらのフックを好きなだけ定義できます。それらはEnvoyスクリプトに現れる順序で実行されます。You may define as many of each of these hooks as you like. They will be executed in the order that they appear in your Envoy script.

@before@before

各タスクの実行前に、Envoyスクリプトで登録されているすべての@beforeフックが実行されます。@beforeフックは、実行しているタスクの名前を受け取ります。Before each task execution, all of the @before hooks registered in your Envoy script will execute. The @before hooks receive the name of the task that will be executed:

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

@after@after

各タスクの実行の後、Envoyスクリプト中で登録したすべての@afterフックが実行されます。@afterフックは、実行したタスクの名前を受け取ります。After each task execution, all of the @after hooks registered in your Envoy script will execute. The @after hooks receive the name of the task that was executed:

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

@error@error

すべてのタスクが失敗した（ステータスコードが0より大きかった）場合、Envoyスクリプトに登録されているすべての@errorフックが実行されます。@errorフックは実行したタスクの名前を受け取ります。After every task failure (exits with a status code greater than 0), all of the @error hooks registered in your Envoy script will execute. The @error hooks receive the name of the task that was executed:

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

@success@success

すべてのタスクがエラーなしで実行された場合は、Envoyスクリプトで登録したすべての@successフックが実行されます。If all tasks have executed without errors, all of the @success hooks registered in your Envoy script will execute:

@success
    // ...
@endsuccess

@finished@finished

すべてのタスクが実行された後(終了ステータスに関係なく)、すべての@finishedフックが実行されます。@finishedフックはnullか0以上のintegerを終了したタスクのステータスコードとして受け取ります。After all tasks have been executed (regardless of exit status), all of the @finished hooks will be executed. The @finished hooks receive the status code of the completed task, which may be null or an integer greater than or equal to 0:

@finished
    if ($exitCode > 0) {
        // １つのタスクにエラーがあった
    }
@endfinished

タスク実行Running Tasks

アプリケーションのEnvoy.blade.phpファイルで定義されているタスクまたはストーリーを実行するには、Envoyのrunコマンドを実行し、実行するタスクまたはストーリーの名前を渡します。Envoyはタスクを実行し、タスクの実行中にリモートサーバからの出力を表示します。To run a task or story that is defined in your application's Envoy.blade.php file, execute Envoy's run command, passing the name of the task or story you would like to execute. Envoy will execute the task and display the output from your remote servers as the task is running:

php vendor/bin/envoy run deploy

タスク実行の確認Confirming Task Execution

サーバで特定のタスクを実行する前に確認を求めるプロンプトを表示する場合は、タスク宣言にconfirmディレクティブを追加します。このオプションは、破壊的な操作で特に役立ちます。If you would like to be prompted for confirmation before running a given task on your servers, you should add the confirm directive to your task declaration. This option is particularly useful for destructive operations:

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

通知Notifications

SlackSlack

Envoyは、各タスクの実行後にSlackへの通知送信をサポートしています。@slackディレクティブは、SlackフックURLとチャネル/ユーザー名を受け入れます。Slackのコントロールパネルで"Incoming WebHooks"統合を作成し、WebフックURLを取得してください。Envoy supports sending notifications to Slack[https://slack.com] after each task is executed. The @slack directive accepts a Slack hook URL and a channel / user name. You may retrieve your webhook URL by creating an "Incoming WebHooks" integration in your Slack control panel.

@slackディレクティブに指定する最初の引数に、WebフックURL全体を渡す必要があります。@slackディレクティブの２番目の引数は、チャネル名(#channel)またはユーザー名(@user)です。You should pass the entire webhook URL as the first argument given to the @slack directive. The second argument given to the @slack directive should be a channel name (#channel) or a user name (@user):

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

デフォルトでEnvoy の通知は、実行したタスクを説明するメッセージを通知チャネルに送信します。しかし、@slack ディレクティブに第三引数を渡すことで、このメッセージを自分のカスタムメッセージで上書きすることができます。By default, Envoy notifications will send a message to the notification channel describing the task that was executed. However, you may overwrite this message with your own custom message by passing a third argument to the @slack directive:

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

DiscordDiscord

Envoyは、各タスクの実行後のDiscordへの通知送信もサポートしています。@discordディレクティブは、DiscordフックのURLとメッセージを受け入れます。サーバ設定で"Webhook"を作成し、Webフックが投稿するチャンネルを選択することで、WebフックURLを取得できます。WebフックURL全体を@discordディレクティブに渡す必要があります。Envoy also supports sending notifications to Discord[https://discord.com] after each task is executed. The @discord directive accepts a Discord hook URL and a message. You may retrieve your webhook URL by creating a "Webhook" in your Server Settings and choosing which channel the webhook should post to. You should pass the entire Webhook URL into the @discord directive:

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

TelegramTelegram

Envoyは、各タスクの実行後のTelegramへの通知送信もサポートしています。@telegramディレクティブは、TelegramボットIDとチャットIDを受け入れます。BotFatherを使用して新しいボットを作成することにより、ボットIDを取得できます。@username_to_id_botを使用して有効なチャットIDを取得できます。ボットIDとチャットID全体を@telegramディレクティブに渡す必要があります。Envoy also supports sending notifications to Telegram[https://telegram.org] after each task is executed. The @telegram directive accepts a Telegram Bot ID and a Chat ID. You may retrieve your Bot ID by creating a new bot using BotFather[https://t.me/botfather]. You can retrieve a valid Chat ID using @username_to_id_bot[https://t.me/username_to_id_bot]. You should pass the entire Bot ID and Chat ID into the @telegram directive:

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

Microsoft TeamsMicrosoft Teams

Envoyは各タスクを実行した後の、Microsoft Teamsへの通知送信もサポートしています。@microsoftTeams ディレクティブは、TeamsのWebフック（必須）、メッセージ、テーマカラー （success、info、warning、error）、およびオプションの配列を引数に取ります。新しい受信Webフック を作成すれば、Teams Webookを取得できます。Teams API には、タイトルやサマリー、セクションなど、メッセージボックスをカスタマイズするためのさまざまな属性が用意されています。詳細は、Microsoft Teamsのドキュメントを確認してください。WebフックのURL全体を@microsoftTeamsディレクティブに渡す必要があります。Envoy also supports sending notifications to Microsoft Teams[https://www.microsoft.com/en-us/microsoft-teams] after each task is executed. The @microsoftTeams directive accepts a Teams Webhook (required), a message, theme color (success, info, warning, error), and an array of options. You may retrieve your Teams Webhook by creating a new incoming webhook[https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook]. The Teams API has many other attributes to customize your message box like title, summary, and sections. You can find more information on the Microsoft Teams documentation[https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/connectors-using?tabs=cURL#example-of-connector-message]. You should pass the entire Webhook URL into the @microsoftTeams directive:

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