Laravel 8.x Artisanコンソール

イントロダクション

ArtisanはLaravelが用意しているコマンドラインインターフェイスです。Artisanは、アプリケーションのルートにartisanスクリプトとして存在し、アプリケーションの構築に役立つコマンドを多数提供しています。使用可能なすべてのArtisanコマンドのリストを表示するには、listコマンドを使用してください。

php artisan list

すべてのコマンドには、コマンドで使用可能な引数とオプションを表示および説明する「ヘルプ」画面も含まれています。ヘルプ画面を表示するには、コマンド名の前に「help」を付けます。

php artisan help migrate

Laravel Sail

ローカル開発環境としてLaravel Sailを使用している場合は、必ずsailコマンドラインを使用してArtisanコマンドを呼び出してください。Sailは、アプリケーションのDockerコンテナ内でArtisanコマンドを実行します。

./sail artisan list

Tinker(REPL)

Laravel Tinkerは、PsySHパッケージを搭載したLaravelフレームワークの強力なREPLです。

インストール

すべてのLaravelアプリケーションにはデフォルトでTinkerが含まれています。ただし、以前にアプリケーションからTinkerを削除した場合は、Composerを使用してTinkerをインストールできます。

composer require laravel/tinker

Tip!! Laravelアプリケーションを操作するグラフィカルUIをお探しですか?Tinkerwellをチェックしてください!

使用法

Tinkerを使用すると、Eloquentモデル、ジョブ、イベントなどを含む、コマンドラインでLaravelアプリケーション全体を操作できます。Tinker環境に入るには、tinkerArtisanコマンドを実行します。

php artisan tinker

vendor:publishコマンドを使用してTinkerの設定ファイルをリソース公開できます。

php artisan vendor:publish --provider="Laravel\Tinker\TinkerServiceProvider"

Note: dispatchヘルパ関数とDispatchableクラスのdispatchメソッドは、ジョブをキューに投入するのにガベージコレクションへ依存しています。したがって、Tinkerを使う場合は、Bus::dispatchまたはQueue::pushを使用してジョブをディスパッチする必要があります。

コマンド許可リスト

Tinkerは「許可」リストを利用して、シェル内で実行できるArtisanコマンドを決定します。デフォルトでは、clear-compileddownenvinspiremigrateoptimizeupコマンドを実行できます。より多くのコマンドを許可したい場合は、それらをtinker.php設定ファイルのcommands配列に追加してください。

'commands' => [
    // App\Console\Commands\ExampleCommand::class,
],

エイリアスするべきではないクラス

通常、Tinkerでクラスを操作すると、Tinkerはクラスへ自動的にエイリアスを付けます。ただし、一部のクラスをエイリアスしないことをお勧めします。これは、tinker.php設定ファイルのdont_alias配列にクラスをリストすることで実現できます。

'dont_alias' => [
    App\Models\User::class,
],

コマンド記述

Artisanが提供するコマンドに加え、独自のカスタムコマンドを作成することもできます。コマンドは通常、app/Console/Commandsディレクトリに保存します。ただし、Composerでコマンドをロードできる限り、独自の保存場所を自由に選択できます。

コマンド生成

新しいコマンドを作成するには、make:command Artisanコマンドを使用します。このコマンドは、app/Console/Commandsディレクトリに新しいコマンドクラスを作成します。このディレクトリがアプリケーションに存在しなくても心配しないでください。make:command Artisanコマンドを初めて実行したとき、このディレクトリを作成します。

php artisan make:command SendEmails

コマンド構造

コマンドを生成した後に、クラスのsignatureプロパティとdescriptionプロパティに適切な値を定義する必要があります。これらのプロパティは、list画面にコマンドを表示するときに使用されます。signatureプロパティを使用すると、コマンドの入力期待値を定義することもできます。コマンドの実行時にhandleメソッドが呼び出されます。このメソッドにコマンドロジックを配置できます。

コマンドの例を見てみましょう。コマンドのhandleメソッドを介して必要な依存関係の注入を要求できることに注意してください。Laravelサービスコンテナは、このメソッドの引数でタイプヒントされているすべての依存関係を自動的に注入します。

<?php

namespace App\Console\Commands;

use App\Models\User;
use App\Support\DripEmailer;
use Illuminate\Console\Command;

class SendEmails extends Command
{
    /**
     * コンソールコマンドの名前と使い方
     *
     * @var string
     */
    protected $signature = 'mail:send {user}';

    /**
     * コンソールコマンドの説明
     *
     * @var string
     */
    protected $description = 'Send a marketing email to a user';

    /**
     * 新しいCommandインスタンスの生成
     *
     * @return void
     */
    public function __construct()
    {
        parent::__construct();
    }

    /**
     * consoleコマンドの実行
     *
     * @param  \App\Support\DripEmailer  $drip
     * @return mixed
     */
    public function handle(DripEmailer $drip)
    {
        $drip->send(User::find($this->argument('user')));
    }
}

Tip!! コードの再利用を増やすには、コンソールコマンドを軽くし、アプリケーションサービスに任せてタスクを実行することをお勧めします。上記の例では、電子メールを送信する「手間のかかる作業」を行うためにサービスクラスを挿入していることに注意してください。

クロージャコマンド

クロージャベースのコマンドは、コンソールコマンドをクラスとして定義する代替方法を提供します。ルートクロージャがコントローラの代替であるのと同じように、コマンドクロージャはコマンドクラスの代替と考えてください。app/Console/Kernel.phpファイルのcommandsメソッド内で、Laravelはroutes/console.phpファイルをロードします。

/**
 * アプリケーションのクロージャベースコマンドを登録
 *
 * @return void
 */
protected function commands()
{
    require base_path('routes/console.php');
}

このファイルはHTTPルートを定義していませんが、アプリケーションへのコンソールベースのエントリポイント(ルート)を定義しています。このファイル内で、Artisan::commandメソッドを使用してすべてのクロージャベースのコンソールコマンドを定義できます。commandメソッドはコマンドの使い方と、コマンド引数とオプションを受け取るクロージャの2引数を取ります。

Artisan::command('mail:send {user}', function ($user) {
    $this->info("Sending email to: {$user}!");
});

クロージャは基になるコマンドインスタンスにバインドされているため、通常は完全なコマンドクラスでアクセスできるすべてのヘルパメソッドに完全にアクセスできます。

タイプヒントの依存関係

コマンドの引数とオプションを受け取ることに加えて、コマンドクロージャは、サービスコンテナにより解決したい追加の依存関係をタイプヒントすることもできます。

use App\Models\User;
use App\Support\DripEmailer;

Artisan::command('mail:send {user}', function (DripEmailer $drip, $user) {
    $drip->send(User::find($user));
});

クロージャコマンドの説明

クロージャベースのコマンドを定義するときは、purposeメソッドを使用してコマンドに説明を追加できます。この説明は、php artisan listまたはphp artisan helpコマンドを実行すると表示されます。

Artisan::command('mail:send {user}', function ($user) {
    // ...
})->purpose('Send a marketing email to a user');

入力期待値の定義

コンソールコマンドを作成する場合、引数またはオプションを介してユーザーからの入力を収集するのが一般的です。Laravelを使用すると、コマンドのsignatureプロパティを使用して、ユーザーへ期待する入力を定義するのが非常に便利になります。signatureプロパティを使用すると、コマンドの名前、引数、およびオプションを表現力豊かなルートのように単一の構文で定義できます。

引数

ユーザーが指定できるすべての引数とオプションは、中括弧で囲います。次の例では、コマンドは1つの必須引数、userを定義します。

/**
 * コンソールコマンドの名前と使い方
 *
 * @var string
 */
protected $signature = 'mail:send {user}';

引数をオプションにしたり、引数のデフォルト値を定義したりもできます。

// オプションの引数
mail:send {user?}

// オプションの引数とデフォルト値
mail:send {user=foo}

オプション

引数のようにオプションは、ユーザー入力の別の形態です。オプションは、コマンドラインで指定する場合、接頭辞として2つのハイフン(--)を付けます。オプションには、値を受け取るオプションと受け取らないオプションの2種類があります。値を受け取らないオプションは、論理「スイッチ」として機能します。このタイプのオプションの例を見てみましょう。

/**
 * コンソールコマンドの名前と使い方
 *
 * @var string
 */
protected $signature = 'mail:send {user} {--queue}';

この例では、Artisanコマンドを呼び出すときに--queueスイッチを指定しています。--queueスイッチが渡されると、オプションの値はtrueになります。それ以外の場合、値はfalseになります。

php artisan mail:send 1 --queue

値を取るオプション

次に、値を期待するオプションを見てみましょう。ユーザーがオプションの値を指定する必要がある場合は、オプション名の末尾に「=」記号を付ける必要があります。

/**
 * コンソールコマンドの名前と使い方
 *
 * @var string
 */
protected $signature = 'mail:send {user} {--queue=}';

この例で、ユーザーはオプションとして値を渡すことができます。コマンドの起動時にオプションが指定されていない場合、その値は「null」になります。

php artisan mail:send 1 --queue=default

オプション名の後にデフォルト値を指定することにより、オプションにデフォルト値を割り当てられます。ユーザーからオプション値が指定されない場合は、デフォルト値を使用します。

mail:send {user} {--queue=default}

オプションのショートカット

オプションを定義するときにショートカットを割り当てるには、オプション名の前にショートカットを指定し、|文字を区切り文字として使用してショートカットと完全なオプション名を分けます。

mail:send {user} {--Q|queue}

ターミナルでそのコマンドを起動する場合、オプションのショートカットの前にハイフンを1つ付ける必要があります。

php artisan mail:send 1 -Q

入力配列

複数の入力値を期待する引数またはオプションを定義する場合は、*文字を使用できます。まず、そのような引数を指定する例を見てみましょう。

mail:send {user*}

このメソッドを呼び出すとき、コマンドラインに順番にuser引数を渡すことができます。たとえば、次のコマンドは、userの値をfoobarを値として持つ配列に設定します。

php artisan mail:send foo bar

この*文字をオプションの引数定義と組み合わせ、引数を0個以上許可することができます。

mail:send {user?*}

オプション配列

複数の入力値を期待するオプションを定義する場合、コマンドに渡たす各オプション値には、オプション名のプレフィックスを付ける必要があります。

mail:send {user} {--id=*}

php artisan mail:send --id=1 --id=2

入力の説明

コロンを使用して引数名と説明を区切ることにより、入力引数とオプションに説明を割り当てることができます。コマンドを定義するために少し余分なスペースが必要な場合は、定義を自由に複数の行に分けてください。

/**
 * コンソールコマンドの名前と使い方
 *
 * @var string
 */
protected $signature = 'mail:send
                        {user : The ID of the user}
                        {--queue : Whether the job should be queued}';

コマンドI/O

入力の取得

コマンドの実行中に、コマンドが受け入れた引数とオプションの値にアクセスする必要があるでしょう。これには、argumentメソッドとoptionメソッドを使用します。引数またはオプションが存在しない場合、nullが返されます。

/**
 * consoleコマンドの実行
 *
 * @return int
 */
public function handle()
{
    $userId = $this->argument('user');

    //
}

すべての引数をarrayとして取得する必要がある場合は、argumentsメソッドを呼び出します。

$arguments = $this->arguments();

オプションは、optionメソッドを使用して引数と同じように簡単に取得できます。すべてのオプションを配列として取得するには、optionsメソッドを呼び出します。

// 特定のオプションを取得
$queueName = $this->option('queue');

// すべてのオプションを配列として取得します
$options = $this->options();

入力のプロンプト

出力の表示に加えて、コマンドの実行中にユーザーへ入力を提供するように依頼することもできます。askメソッドはユーザーへ、指定した質問をプロンプ​​トとして表示し、入力を受け取り、ユーザー入力をコマンドに戻します。

/**
 * consoleコマンドの実行
 *
 * @return mixed
 */
public function handle()
{
    $name = $this->ask('What is your name?');
}

secretメソッドはaskに似ていますが、ユーザーがコンソールに入力するときに、ユーザーの入力は表示されません。この方法は、パスワードなどの機密情報をリクエストするときに役立ちます。

$password = $this->secret('What is the password?');

確認を求める

単純な「はい」か「いいえ」の確認をユーザーに求める必要がある場合は、「confirm」メソッドを使用します。デフォルトでは、このメソッドはfalseを返します。ただし、ユーザーがプロンプトに応答して「y」または「yes」を入力すると、メソッドは「true」を返します。

if ($this->confirm('Do you wish to continue?')) {
    //
}

必要に応じて、confirmメソッドの2番目の引数としてtrueを渡すことにより、確認プロンプトがデフォルトでtrueを返すように指定できます。

if ($this->confirm('Do you wish to continue?', true)) {
    //
}

オートコンプリート

anticipateメソッドを使用して、可能な選択肢のオートコンプリートを提供できます。オートコンプリートのヒントに関係なく、ユーザーは引き続き任意の回答ができます。

$name = $this->anticipate('What is your name?', ['Taylor', 'Dayle']);

もしくはanticipateメソッドの2番目の引数としてクロージャを渡すこともできます。クロージャは、ユーザーが入力文字を入力するたびに呼び出されます。クロージャは、これまでのユーザーの入力を含む文字列パラメーターを受け取り、オートコンプリートのオプションの配列を返す必要があります。

$name = $this->anticipate('What is your address?', function ($input) {
    // オートコンプリートオプションを返す…
});

複数の選択肢の質問

質問をするときにユーザーに事前定義された選択肢のセットを提供する必要がある場合は、choiceメソッドを使用します。メソッドに3番目の引数としてインデックスを渡すことにより、オプションが選択されていない場合に返されるデフォルト値の配列インデックスを設定できます。

$name = $this->choice(
    'What is your name?',
    ['Taylor', 'Dayle'],
    $defaultIndex
);

さらに、choiceメソッドは、有効な応答を選択するための最大試行回数と、複数の選択が許可されるかどうかを決定するために、オプションとして4番目と5番目の引数を取ります。

$name = $this->choice(
    'What is your name?',
    ['Taylor', 'Dayle'],
    $defaultIndex,
    $maxAttempts = null,
    $allowMultipleSelections = false
);

出力の書き込み

コンソールに出力を送信するには、lineinfocommentquestionwarnerrorメソッドを使用できます。これらの各メソッドは、目的に応じて適切なANSIカラーを使用します。たとえば、一般的な情報をユーザーに表示してみましょう。通常、infoメソッドはコンソールに緑色のテキストを表示します。

/**
 * consoleコマンドの実行
 *
 * @return mixed
 */
public function handle()
{
    // ...

    $this->info('The command was successful!');
}

エラーメッセージを表示するには、errorメソッドを使用します。エラーメッセージのテキストは通常​​、赤で表示します。

$this->error('Something went wrong!');

lineメソッドを使用して、色のないプレーンなテキストを表示できます。

$this->line('Display this on the screen');

newLineメソッドを使用して空白行を表示できます。

// 空白行を1行書く
$this->newLine();

// 空白行を3行書く
$this->newLine(3);

テーブル

tableメソッドを使用すると、データの複数の行/列を簡単に正しくフォーマットできます。 テーブルの列名とデータを入力するだけで、Laravelがテーブルの適切な幅と高さを自動的に計算します。

use App\Models\User;

$this->table(
    ['Name', 'Email'],
    User::all(['name', 'email'])->toArray()
);

プログレスバー

長時間実行されるタスクの場合、タスクの完了度をユーザーに通知する進行状況バーを表示すると便利です。withProgressBarメソッドを使用するとLaravelは、進行状況バーを表示し、指定した反復可能値を反復するごとにその進捗を進めます。

use App\Models\User;

$users = $this->withProgressBar(User::all(), function ($user) {
    $this->performTask($user);
});

場合によっては、プログレスバーの進め方を手動で制御する必要があります。最初に、プロセスが繰り返すステップの総数を定義します。次に、各アイテムを処理した後、プログレスバーを進めます。

$users = App\Models\User::all();

$bar = $this->output->createProgressBar(count($users));

$bar->start();

foreach ($users as $user) {
    $this->performTask($user);

    $bar->advance();
}

$bar->finish();

Tip!! より高度なオプションは、Symfonyプログレスバーコンポーネントのドキュメントで確認してください。

コマンド登録

すべてのコンソールコマンドは、アプリケーションの「コンソールカーネル」であるアプリケーションのApp\Console\Kernelクラスで登録します。このクラスのcommandsメソッド内で、カーネルのloadメソッドの呼び出しがあります。loadメソッドはapp/Console/Commandsディレクトリをスキャンしてそこに含まれる各コマンドをArtisanに自動的に登録します。loadメソッドを追加で呼び出して、他のディレクトリのArtisanコマンドをスキャンすることもできます。

/**
 * アプリケーションのコマンドを登録
 *
 * @return void
 */
protected function commands()
{
    $this->load(__DIR__.'/Commands');
    $this->load(__DIR__.'/../Domain/Orders/Commands');

    // ...
}

必要であれば、コマンドのクラス名をApp\Console\Kernelクラス内の$commandsプロパティへ追加し、コマンドを手動で登録できます。このプロパティがカーネルで未定義の場合は、自分で定義する必要があります。Artisanが起動すると、このプロパティに記載されている全てのコマンドは、サービスコンテナが依存解決し、Artisanへ登録します。

protected $commands = [
    Commands\SendEmails::class
];

プログラムからのコマンド実行

CLIの外部でArtisanコマンドを実行したい場合があります。たとえば、ルートまたはコントローラからArtisanコマンドを実行したい場合があります。これを実現するには、Artisanファサードのcallメソッドを使用します。callメソッドは、最初の引数としてコマンドの名前またはクラス名のいずれかを受け入れ、2番目の引数としてコマンドパラメータの配列を取ります。終了コードが返されます:

use Illuminate\Support\Facades\Artisan;

Route::post('/user/{user}/mail', function ($user) {
    $exitCode = Artisan::call('mail:send', [
        'user' => $user, '--queue' => 'default'
    ]);

    //
});

または、Artisanコマンド全体を文字列としてcallメソッドに渡すこともできます。

Artisan::call('mail:send 1 --queue=default');

配列値の受け渡し

コマンドで配列を受け入れるオプションを定義している場合は、値の配列をそのオプションに渡すことができます。

use Illuminate\Support\Facades\Artisan;

Route::post('/mail', function () {
    $exitCode = Artisan::call('mail:send', [
        '--id' => [5, 13]
    ]);
});

論理値値の受け渡し

migrate:refreshコマンドの--forceフラグなど、文字列値を受け入れないオプションの値を指定する必要がある場合は、そのオプションの値としてtrueまたはfalseを渡してください。

$exitCode = Artisan::call('migrate:refresh', [
    '--force' => true,
]);

Artisanコマンドのキュー投入

Artisanファサードでqueueメソッドを使用すると、Artisanコマンドをキューに投入し、キューワーカーによりバックグラウンド処理することもできます。この方法を使用する前に、確実にキューを設定し、キューリスナを実行してください。

use Illuminate\Support\Facades\Artisan;

Route::post('/user/{user}/mail', function ($user) {
    Artisan::queue('mail:send', [
        'user' => $user, '--queue' => 'default'
    ]);

    //
});

onConnectionおよびonQueueメソッドを使用して、Artisanコマンドをディスパッチする接続やキューを指定できます。

Artisan::queue('mail:send', [
    'user' => 1, '--queue' => 'default'
])->onConnection('redis')->onQueue('commands');

他コマンドからのコマンド呼び出し

Artisanコマンドから他のコマンドを呼び出したい場合があります。callメソッドを使用してこれを行うことができます。このcallメソッドは、コマンド名とコマンド引数/オプションの配列を受け入れます。

/**
 * consoleコマンドの実行
 *
 * @return mixed
 */
public function handle()
{
    $this->call('mail:send', [
        'user' => 1, '--queue' => 'default'
    ]);

    //
}

別のコンソールコマンドを呼び出してその出力をすべて抑制したい場合は、callSilentlyメソッドを使用できます。callSilentlyメソッドはcallメソッドと同じ使い方です。

$this->callSilently('mail:send', [
    'user' => 1, '--queue' => 'default'
]);

シグナルの処理

Artisanコンソールのベースとして動作しているSymfonyコンソールコンポーネントを使用すると、コマンドで処理したいプロセスのシグナルを指定できます。たとえば、コマンドがSIGINT信号とSIGTERM信号を処理することを指示するとします。

処理するには、ArtisanコマンドクラスのSymfony\Component\Console\Command\SignalableCommandInterfaceインタフェースを実装する必要があります。このインタフェースは、getSubscribedSignalshandleSignal、2つのメソッドを定義する必要があります。

<?php

use Symfony\Component\Console\Command\SignalableCommandInterface;

class StartServer extends Command implements SignalableCommandInterface
{
    // ...

    /**
     * コマンドにより処理するシグナルのリストを取得
     *
     * @return array
     */
    public function getSubscribedSignals(): array
    {
        return [SIGINT, SIGTERM];
    }

    /**
     * 受け取ったシグナルの処理
     *
     * @param  int  $signal
     * @return void
     */
    public function handleSignal(int $signal): void
    {
        if ($signal === SIGINT) {
            $this->stopServer();

            return;
        }
    }
}

ご期待のとおり、getSubscribedSignalsメソッドはコマンドが扱えるシグナルの配列を返し、handleSignalメソッドはシグナルを受け取り、それに応答できるようにします。

スタブのカスタマイズ

Artisanコンソールのmakeコマンドは、コントローラ、ジョブ、マイグレーション、テストなどのさまざまなクラスを作成するために使用されます。これらのクラスは、入力に基づいた値が挿入される「スタブ」ファイルを使用して生成されます。ただし、Artisanにより生成されるファイルへ小さな変更を加えることをおすすめします。このためには、stub:publishコマンドを使用して、最も一般的なスタブをアプリケーションにリソース公開し、カスタマイズできるようにします。

php artisan stub:publish

リソース公開するスタブは、アプリケーションのルートのstubsディレクトリ内へ設置します。これらのスタブに加えた変更は、Artisanのmakeコマンドを使用して対応するクラスを生成するときに反映されます。

イベント

Artisanは、コマンドの実行時に、Illuminate\Console\Events\ArtisanStartingIlluminate\Console\Events\CommandStarting、およびIlluminate\Console\Events\CommandFinishedの3つのイベントをディスパッチします。ArtisanStartingイベントは、Artisanが実行を開始するとすぐにディスパッチされます。次に、コマンドが実行される直前にCommandStartingイベントがディスパッチされます。最後に、コマンドの実行が終了すると、CommandFinishedイベントがディスパッチされます。

ドキュメント章別ページ

ヘッダー項目移動

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

移動

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

設定

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

カラーテーマ
和文指定 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によるフォントファミリー指定の知識がない場合は、フォントを変更しないほうが良いでしょう。

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

オープン操作

PDC

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

HA

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

MS

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

ヘッダー移動

T

最初のヘッダーへ移動

E

最後のヘッダーへ移動

NJ

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

BK

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

その他

?

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