はじめに
Laravel Envoy は、リモートサーバー上でよく使うタスクを実行するためのツールです。Blade と同じ構文を使って、デプロイやArtisanコマンドの実行などのタスクを簡単に定義できます。Envoyは現在、macOSとLinuxのみをサポートしています。Windowsで使う場合はWSL2経由での利用が必要です。
インストール
Composerパッケージマネージャーを使って、プロジェクトにEnvoyをインストールします。vendor/binディレクトリにEnvoyの実行ファイルが利用可能になります。
タスクの作成
タスクの定義
タスクはEnvoyの基本的な構成要素です。タスクは、タスク実行時にリモートサーバー上で実行すべきシェルコマンドを定義します。たとえば、すべてのキューワーカーサーバーでphp artisan queue:restart コマンドを実行するタスクを定義できます。
Envoyタスクはすべて、アプリケーションのルートにある Envoy.blade.php ファイルに定義します。
@servers の配列を定義し、各タスク宣言の on オプションでこれらのサーバーを参照します。@servers 宣言は必ず1行で記述してください。@task 宣言の中には、タスク実行時にサーバー上で実行するシェルコマンドを記述します。
ローカルタスク
サーバーのIPアドレスを127.0.0.1 に指定することで、スクリプトをローカルコンピューター上で強制的に実行できます。
Envoyタスクのインポート
@import ディレクティブを使うと、他のEnvoyファイルをインポートして、そのストーリーやタスクを自分のファイルに追加できます。インポート後は、自身のEnvoyファイルで定義したのと同じようにタスクを実行できます。
複数サーバー
Envoyでは、1つのタスクを複数のサーバーで簡単に実行できます。まず@servers 宣言に追加のサーバーを登録し、各サーバーに一意の名前を割り当てます。サーバーを追加したら、タスクの on 配列に各サーバーを列挙します。
並列実行
デフォルトでは、タスクは各サーバーで直列に実行されます。つまり、あるタスクが1台目のサーバーで完了してから、2台目のサーバーでの実行に進みます。複数サーバーでタスクを並列実行したい場合は、タスク宣言にparallel オプションを追加します。
セットアップ
Envoyタスクを実行する前に、任意のPHPコードを実行する必要がある場合は@setup ディレクティブを使います。
Envoy.blade.php ファイルの先頭で @include ディレクティブを使います。
変数
Envoyタスクを呼び出す際に、コマンドラインで引数を指定してタスクに渡すことができます。if 文やループも定義可能です。たとえば git pull コマンドを実行する前に $branch 変数の存在を確認する場合は次のようにします。
ストーリー
ストーリーは、一連のタスクを1つの便利な名前でグループ化します。たとえばdeploy ストーリーで、update-code タスクと install-dependencies タスクをまとめて実行できます。
完了フック
タスクやストーリーの実行時には、複数のフックが実行されます。Envoyがサポートするフックの種類は@before、@after、@error、@success、@finished です。これらのフック内のコードはすべてPHPとして解釈され、タスクが操作するリモートサーバーではなく、ローカルで実行されます。
各フックはいくつでも定義でき、Envoyスクリプトに記述された順序で実行されます。
@finished フックは、実行が完了したタスクのステータスコードを受け取ります。ステータスコードは null または 0 以上の整数です。
タスクの実行
アプリケーションのEnvoy.blade.php ファイルに定義したタスクやストーリーを実行するには、Envoyの run コマンドを実行し、実行したいタスクまたはストーリーの名前を渡します。Envoyはタスクを実行し、実行中にリモートサーバーからの出力を表示します。
タスク実行の確認
サーバー上で特定のタスクを実行する前に確認を求めたい場合は、タスク宣言にconfirm ディレクティブを追加します。この機能は破壊的な操作を実行する場合に特に便利です。
通知
Slack
Envoyは、各タスク実行後にSlackへ通知を送信できます。@slack ディレクティブは、SlackのWebhook URLとチャンネル名（またはユーザー名）を受け取ります。Webhook URLは、Slackのコントロールパネルで「Incoming WebHooks」インテグレーションを作成することで取得できます。
@slack ディレクティブの第1引数にはWebhook URL全体を渡します。第2引数には、チャンネル名（#channel）またはユーザー名（@user）を指定します。
@slack ディレクティブに第3引数を渡すことで、独自のメッセージに上書きできます。
Discord
Envoyは、各タスク実行後にDiscordへ通知を送信することもサポートしています。@discord ディレクティブはDiscordのWebhook URLとメッセージを受け取ります。Webhook URLは、サーバー設定内で「Webhook」を作成し、投稿先チャンネルを選択することで取得できます。
Telegram
Envoyは、各タスク実行後にTelegramへ通知を送信することもサポートしています。@telegram ディレクティブは、Telegram Bot IDとChat IDを受け取ります。Bot IDはBotFatherで新しいボットを作成することで取得できます。Chat IDは@username_to_id_botを使って取得できます。
Microsoft Teams
Envoyは、各タスク実行後にMicrosoft Teamsへ通知を送信することもサポートしています。@teams ディレクティブは、Teamsのwebhook（必須）、メッセージ、テーマカラー（success, info, warning, error）、そしてオプションの設定配列を受け取ります。Teamsのwebhookは、Incoming Webhookを作成することで取得できます。Teams APIには他にも多くの設定項目があり、独自のメッセージカードを自由に作成できます。詳細はMicrosoft Teamsのドキュメントを参照してください。