Laravel 9.x Laravel Envoy

イントロダクション

Laravel Envoyは、リモートサーバ上で実行する一般的なタスクを実行するためのツールです。bladeスタイルの構文を使用し、デプロイやArtisanコマンドなどのタスクを簡単に設定できます。現在、EnvoyはMacおよびLinuxオペレーティングシステムのみをサポートしています。ただし、WindowsサポートはWSL2を使用して実現できます。

インストール

まず、Composerパッケージマネージャを使用してEnvoyをプロジェクトにインストールします。

composer require laravel/envoy --dev

Envoyがインストールされると、Envoyバイナリはアプリケーションのvendor/binディレクトリで利用できるようになります。

php vendor/bin/envoy

タスクの記述

タスク定義

タスクはEnvoyの基本的な設定要素です。タスクには、呼び出されたときにリモートサーバで実行する必要があるシェルコマンドを定義します。たとえば、アプリケーションのすべてのキューワーカーサーバで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宣言は常に1行に配置する必要があります。@task宣言内に、タスクが呼び出されたときにサーバ上で実行する必要のあるシェルコマンドを配置する必要があります。

ローカルタスク

サーバの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

準備

Envoyタスクを実行する前に、任意のPHPコードを実行する必要がある場合があります。@setupディレクティブを使用して、タスクの前に実行する必要があるPHPコードブロックを定義できます。

@setup
    $now = new DateTime;
@endsetup

タスクを実行する前に他のPHPファイルをリクエストする必要がある場合は、Envoy.blade.phpファイルの先頭にある@includeディレクティブを使用できます。

@include('vendor/autoload.php')

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

変数

必要に応じて、Envoyを呼び出すときにコマンドラインで引数を指定することにより、Envoyタスクに引数を渡すことができます。

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

Bladeの「エコー（echo）」構文を使用して、タスク内のオプションにアクセスできます。タスク内でBladeのifステートメントとループを定義することもできます。例としてgit pullコマンドを実行する前に、$branch変数の存在を確認してみましょう。

@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

各タスクの実行前に、Envoyスクリプトで登録されているすべての@beforeフックが実行されます。@beforeフックは、実行しているタスクの名前を受け取ります。

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

@after

各タスクの実行の後、Envoyスクリプト中で登録したすべての@afterフックが実行されます。@afterフックは、実行したタスクの名前を受け取ります。

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

@error

すべてのタスクが失敗した（ステータスコードが0より大きかった）場合、Envoyスクリプトに登録されているすべての@errorフックが実行されます。@errorフックは実行したタスクの名前を受け取ります。

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

@success

すべてのタスクがエラーなしで実行された場合は、Envoyスクリプトで登録したすべての@successフックが実行されます。

@success
    // ...
@endsuccess

@finished

すべてのタスクが実行された後(終了ステータスに関係なく)、すべての@finishedフックが実行されます。@finishedフックはnullか0以上のintegerを終了したタスクのステータスコードとして受け取ります。

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

タスク実行

アプリケーションのEnvoy.blade.phpファイルで定義されているタスクまたはストーリーを実行するには、Envoyのrunコマンドを実行し、実行するタスクまたはストーリーの名前を渡します。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ディレクティブは、SlackフックURLとチャネル/ユーザー名を受け入れます。Slackのコントロールパネルで"Incoming WebHooks"統合を作成し、WebフックURLを取得してください。

@slackディレクティブに指定する最初の引数に、WebフックURL全体を渡す必要があります。@slackディレクティブの２番目の引数は、チャネル名(#channel)またはユーザー名(@user)です。

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

デフォルトでEnvoy の通知は、実行したタスクを説明するメッセージを通知チャネルに送信します。しかし、@slack ディレクティブに第三引数を渡すことで、このメッセージを自分のカスタムメッセージで上書きすることができます。

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

Discord

Envoyは、各タスクの実行後のDiscordへの通知送信もサポートしています。@discordディレクティブは、DiscordフックのURLとメッセージを受け入れます。サーバ設定で"Webhook"を作成し、Webフックが投稿するチャンネルを選択することで、WebフックURLを取得できます。WebフックURL全体を@discordディレクティブに渡す必要があります。

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

Telegram

Envoyは、各タスクの実行後のTelegramへの通知送信もサポートしています。@telegramディレクティブは、TelegramボットIDとチャットIDを受け入れます。BotFatherを使用して新しいボットを作成することにより、ボットIDを取得できます。@username_to_id_botを使用して有効なチャットIDを取得できます。ボットIDとチャットID全体を@telegramディレクティブに渡す必要があります。

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

Microsoft Teams

Envoyは各タスクを実行した後の、Microsoft Teamsへの通知送信もサポートしています。@microsoftTeams ディレクティブは、TeamsのWebフック（必須）、メッセージ、テーマカラー （success、info、warning、error）、およびオプションの配列を引数に取ります。新しい受信Webフック を作成すれば、Teams Webookを取得できます。Teams API には、タイトルやサマリー、セクションなど、メッセージボックスをカスタマイズするためのさまざまな属性が用意されています。詳細は、Microsoft Teamsのドキュメントを確認してください。WebフックのURL全体を@microsoftTeamsディレクティブに渡す必要があります。

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

ドキュメント章別ページ

はじめに
リリースノート アップグレードガイド 貢献ガイド
利用開始
インストール 設定 ディレクトリ構造 フロントエンド スターターキット デプロイ
構成概念
ライフサイクル サービスコンテナ サービスプロバイダ ファサード
基礎
ルーティング ミドルウェア CSRF保護 コントローラ リクエスト レスポンス ビュー Bladeテンプレート アセットの構築 URL生成 セッション バリデーション エラー処理 ログ
より深く知る
Artisanコンソール ブロードキャスト キャッシュ コレクション 契約 イベント ファイルストレージ ヘルパ HTTPクライアント 多言語化 メール 通知 パッケージ開発 キュー レート制限 タスクスケジュール
安全
認証 認可 メール確認 暗号化 ハッシュ パスワードリセット
データベース
準備 クエリビルダ ペジネーション マイグレーション シーディング Redis
Eloquent ORM
Eloquentの準備 リレーション コレクション ミューテタ／キャスタ APIリソース シリアライズ ファクトリ
テスト
テストの準備 HTTPテスト コンソールテスト ブラウザテスト データベーステスト モック
パッケージ
Breeze Cashier (Stripe) Cashier (Paddle) Dusk Envoy Fortify Homestead Horizon Jetstream Mix Octane Passport Pint Sail Sanctum Scout Socialite Telescope Valet
API
APIドキュメント
言語 ファイル
auth.php pagination.php passwords.php validation.php

ヘッダー項目移動

注目：アイコン：ページ内リンク設置（リンクがないヘッダーへの移動では、リンクがある以前のヘッダーのハッシュをURLへ付加します。

移動

クリックで即時移動します。

リンク
サイトホーム ページ上部へ
言語
バージョン
10.x 9.x 8.x 7.x 6.x LTS 5.8 5.7 5.6 5.5 LTS 5.4 5.3 5.2 5.1 LTS 5.0 5.dev 4.2

設定

適用ボタンクリック後に、全項目まとめて適用されます。

カラーテーマ
和文指定 Pagination
和文指定 Scaffold
Largeスクリーン表示幅
インデント
本文フォント
コードフォント
フォント適用確認

フォントの指定フィールドから、フォーカスが外れると、当ブロックの内容に反映されます。EnglishのDisplayもPreviewしてください。

フォント設定時、表示に不具合が出た場合、当サイトのクッキーを削除してください。

バックスラッシュを含むインライン\Code\Blockの例です。

以下はコードブロックの例です。

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * ユーザに関連する電話レコードを取得
     */
    public function phone()
    {
        return $this->hasOne('App\Phone');
    }
}

設定を保存する前に、表示が乱れないか必ず確認してください。CSSによるフォントファミリー指定の知識がない場合は、フォントを変更しないほうが良いでしょう。

キーボード・ショートカット

オープン操作

P／D／C

ページ（章）移動の左オフキャンバスオープン

H／A

ヘッダー移動モーダルオープン

M／S

移動／設定の右オフキャンバスオープン

ヘッダー移動

T

最初のヘッダーへ移動

E

最後のヘッダーへ移動

N／J

次ヘッダー(H2〜H4)へ移動

B／K

前ヘッダー(H2〜H4)へ移動

その他

?

このヘルプページ表示
閉じる