このリポジトリはPHP Webアプリフレームワークである、LaravelのLTSバージョンである5.5の公式英文ドキュメントを日本語へ翻訳しています。
This project is maintained by okinaka
Laravel Envoy（使節）はリモートサーバ間で共通のタスクを実行するために、美しく最小限の記法を提供します。デプロイやArtisanコマンドなどのタスクをBlade記法により簡単に準備できます。EnvoyはMacとLinuxのオペレーションシステムのみサポートしています。
最初にEnvoyをComposerのglobal requireコマンドでインストールします。
composer global require laravel/envoy
グローバルComposerライブラリは、時々パッケージバージョンのコンフリクトを起こすため、composer global requireコマンドの代替として、cgrの使用を考慮してください。cgrライブラリのインストール方法は、GitHubで見つけられます。
{note}
envoyコマンドを端末で実行するときにenvoyの実行ファイルが見つかるように、~/.composer/vendor/binディレクトリに実行パスを通しておくのを忘れないでください。
インストールしたEnvoyをアップデートするためにも、Composerを使用します。composer global updateコマンドの実行により、インストール済みのグローバルComposerパッケージがすべてアップデートされます。
composer global update
Envoyの全タスクはプロジェクトルートのEnvoy.blade.phpファイルの中で定義します。最初に例を見てください。
@servers(['web' => ['user@192.168.1.1']])
@task('foo', ['on' => 'web'])
ls -la
@endtask
見ての通り、@serversの配列をファイルの最初で定義し、タスク定義のonオプションでそれらのサーバを参照できるようにしています。@task定義の中には、タスクが実行されるときにサーバで実行するBASHコードを記述します。
サーバのIPアドレスを127.0.0.1にすることで、強制的にスクリプトをローカルで実行できます。
@servers(['localhost' => '127.0.0.1'])
タスクを実行する前に、PHPコードを評価する必要がある場合もあります。変数を宣言するために@setupディレクティブを使用し、他のタスクが実行される前に通常のPHPを動作させます。
@setup
$now = new DateTime();
$environment = isset($env) ? $env : "testing";
@endsetup
タスク実行前に他のPHPライブラリを読み込む必要がある場合は、Envoy.blade.phpファイルの先頭で、@includeディレティブを使用してください。
@include('vendor/autoload.php')
@task('foo')
# ...
@endtask
必要であれば、コマンドラインを使い、Envoyタスクへオプション値を渡すことができます。
envoy run deploy --branch=master
オプションはBladeの”echo”記法により、タスク中からアクセスできます。もちろん、if文も使用できますし、タスク内で繰り返しも可能です。例としてgit pullコマンドを実行する前に、$branchの存在を確認してみましょう。
@servers(['web' => '192.168.1.1'])
@task('deploy', ['on' => 'web'])
cd site
@if ($branch)
git pull origin
@endif
php artisan migrate
@endtask
ストーリーにより、選択した小さなタスクを大きなタスクにまとめることができます。名前を付け、一連のタスクを一つにまとめます。一例としてタスク名をリストすることにより、deployストーリーを定義し、gitとcomposerタスクを実行してみます。
@servers(['web' => '192.168.1.1'])
@story('deploy')
git
composer
@endstory
@task('git')
git pull origin master
@endtask
@task('composer')
composer install
@endtask
ストーリーを書き上げたら、通常のタスクと同じように実行します。
envoy run deploy
Envoyでは、複数のサーバに渡りタスクを実行するのも簡単です。最初に追加のサーバを@serversディレクティブで指定してください。各サーバには一意な名前を割り当ててください。追加サーバを定義したら、タスクのon配列にサーバをリストするだけです。
@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])
@task('deploy', ['on' => ['web-1', 'web-2']])
cd site
git pull origin
php artisan migrate
@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 site
git pull origin
php artisan migrate
@endtask
Envoy.blade.phpファイルのタスクやストーリーを実行するには、実行したいタスクかストーリーの名前を指定し、Envoyのrunコマンドを実行します。Envoyはタスクを実行し、タスク実行中にサーバからの出力を表示します。
envoy run task
サーバ上の特定タスク実行前に、確認のプロンプトを出したい場合は、タスク宣言でconfirmディレクティブを追加してください。このオプションは、破壊的な操作を行う場合に特に便利です。
@task('deploy', ['on' => 'web', 'confirm' => true])
cd site
git pull origin
php artisan migrate
@endtask
Envoyは各タスク実行後の、Slackへの通知もサポートしています。@slackディレクティブは、SlackフックURLとチャンネル名を引数に取ります。WebフックURLは、Slackコントロールパネルで”Incoming WebHooks”統合を作成することにより、作成されます。WebフックURL全体を@slackディレクティブへ渡してください。
@finished
@slack('webhook-url', '#bots')
@endfinished
チャンネル引数には以下のどちらかを指定します。
#channel@user