Services.md

サービス

タスクやストラタジー、バイナリなどを作成する際、Rocketeerは作業を簡単にしたりアクセスするための様々なサービスを提供しています。それらの全ては公開APIとして記載されていますが、そのうちのいくつかは特に重要です。ここでは、Rocketeerが何を提供しているか見て、内部でどのように動作しているか理解していきたいと思います。

提供される全ての例は、カスタムタスクを想定しています。ただ、これはクロージャタスクでも同じように適用されます。つまり、もしタスククラスの中で$this->foo->bar()のようにできるとしたら、クロージャの中であれば次のようになります。

Rocketeer::before('deploy', function (AbstractTask $task) {
  $task->foo->bar();
});

それぞれのサービスの隣の括弧内の文字列は、それを通じてアクセス可能なハンドルです。

タスクビルダー [builder]

タスクビルダーはRocketeerの最も重要なサービスのひとつです。タスクから、簡単にバイナリー、タスク、ストラテジなどのインスタンスを得るための強力な手段です。許されているどんなタスクでもビルドすることができます: ワンライナー、クロージャ、インスタンス、クラス名など。

// Build a task
$this->builder->buildTask('ls');

$this->builder->buildTask('Acme\MyCustomTask');

$this->builder->buildTask(function ($task) {
  return $task->run('ls');
}, 'My task', 'Lists the folders');

// Build multiple tasks
$this->builder->buildTasks(array(
  'ls',
  'Acme\MyCustomTask',
));

// Build the configured implementation of a strategy
$this->builder->buildStrategy('Deploy');

// Build a particular implementation of a strategy
$this->builder->buildStrategy('Deploy', 'Clone');

// Build the Command instance related to a Task
$this->builder->buildCommand('Deploy'); // DeployCommand

タスクキュー [queue]

タスクキューは、Rocketeerのもう一つの主だったクラスです。タスクの配列を受け取って、それから実行可能なパイプラインを構築します。同じ種類のタスクタイプ(クロージャ、文字列、クラス名など)を渡せるよう、全てはTasksBuilderを通して渡されます。

// Run an array of tasks
$this->queue->run(['cd /foo/bar', 'ls']);

// Run an array of tasks and return the last line
// You can specify the connection as second argument
$files = $this->queue->execute(['cd /foo/bar', 'ls'], 'production');

// Same as above but with reversed arguments
$files = $this->queue->on('production', ['cd /foo/bar', 'ls']);

runメソッドはRocketeer\Services\Tasks\Pipelineのインスタンスを返します。PipelineはIlluminate\Support\Collectionを拡張したクラスで、Rocketeer\Services\Tasks\Jobのインスタンスを保持します。

Rocketeerでは、ジョブとは実行に必要な情報を持つひとまとまりのキューです: キューがどんな接続を必要とするのか、どのステージか、どのサーバか、etc. あなたが、二つの接続、production と stagingを持っていると想像してください。次のようなパイプラインを得るでしょう:

$pipeline = $this->queue->run(['cd /foo/bar', 'ls']);

$firstJob = $pipeline->first(); // Job instance
$firstJob->connection; // production
$firstJob->queue; // [ClosureTask(cd /foo/Bar), ClosureTask(ls)]

$secondJob = $pipeline->get(1); // Job instance
$firstJob->connection; // staging
$firstJob->queue; // [ClosureTask(cd /foo/Bar), ClosureTask(ls)]

一度パイプラインが構築されると、--pretendフラグが渡されるか次第で、同期的か非同期的に実行されます。

タスクハンドラ [tasks]

タスクハンドラは関連するタスクやプラグイン、イベントを登録します。それがRocketeerのファサードの後ろの主なタスクなので、そのメソッド(before, after, listenTo, task)のほとんどに精通している必要があります:

// Register tasks and events
$this->tasks->task('list-files', 'ls', 'Lists files in a folder');

$this->tasks->before('Deploy', 'list-files');

// Get bound events
$events = $this->tasks->getTasksListeners('deploy', 'before');

ステップビルダー [steps()]

ステップビルダーはタスクに一連の内部的なコマンドや呼び出しを実行させ、最初の失敗で停止できるようにするものです。インターフェースの使いやすさはそのままに。次のような、架空のタスクの中の一連のコマンドを見てみましょう:

$this->executeTask('Migrate');
$this->symlink('foo', 'bar');

ここで、Migrateタスクが失敗した場合は、symlinkを実行したくないとしたら、steps()を単純に前につけます:

$this->steps()->executeTask('Migrate');
$this->steps()->symlink('foo', 'bar');

これで、これらの「ステップ」はタスクのstepsプロパティに保持されます。一度完了すれば、安全に順番を追ってそれらを実行することができます。ステップが失敗しない限りは。

$this->steps()->executeTask('Migrate');
$this->steps()->symlink('foo', 'bar');

// Run the steps until one fails
if (!$this->runSteps()) {
	return $this->halt();
}

キューの説明 [explainer]

キューの「説明(explainer)」は、RocketeerのCLI出力をコントロールするものです。ユーザに何が起きているかを説明し、どのタスクがどのタスクやイベントによって引き起こされ、何が進行しているか、その結果、そして実行にどのくらいの時間がかかるのか、など。

デフォルトでは、タスクの実行時、「説明」はあなたがセットしたnameとdescriptionプロパティから、自動的に情報を表示します。ですが、タスクのフローの中で「説明」に追加の詳細を提供することも可能です:

$this->explainer->line('Doing some stuff');
if (!$this->somethingThatMayFail()) {
  $this->explainer->error('Something crashed here');
}

$this->explainer->success('All went well!');

「説明」はCommandインスタンスのlineメソッドに、それを渡しています。つまり、Symfonyドキュメントに記述された前景色と背景色を追加することも可能です。

$this->explainer->line('<info>Something</info> tried and <bg=red>failed</bg=red>');

たぶんお気付きのように、「説明」はあなたのタスクの「ツリー」を実行時に構築します。もしタスクやイベントの内部で呼び出されるなら、タスクはネストされます:

|-- Running: Deploy (Deploys the website) [~14.25s]
|---- Running: Primer (Run local checks to ensure deploy can proceed)
|---- Running: CreateRelease (Creates a new release on the server) [~5.98s]
|------ Running strategy for Deploy: Sync

これは、コマンドをクロージャの中にラッピングすることで可能です。

$this->explainer->displayBelow(function() {
  // Whatever is done here will be displayed one level below in the tree
});