Artisan コマンド
Laravel のコマンド「Artisan」の使い方と、Tinker、自分用のコマンドの作り方、引数やオプション、入力と出力、開発用の dev コマンドを説明します。
Artisan(アーティザン)は、Laravel に付いてくるコマンドの道具です。ターミナル(文字でパソコンに命令する画面)で php artisan ... と打つと、ファイルの雛形を作ったり、データベースを動かしたり、いろいろな仕事をしてくれます。アプリの一番上にある artisan というファイルが、その本体です。
使えるコマンドの一覧は list で見られます。
php artisan list
どのコマンドにも、使える引数(コマンドに渡す値)とオプション(-- で始まる追加の指定)を説明する「ヘルプ」があります。コマンドの名前の前に help を付けると見られます。
php artisan help migrate
Laravel Sail を使うとき#
手元の開発環境に Laravel Sail(Docker という入れ物の中で Laravel を動かす道具)を使っているときは、php artisan の代わりに sail を使います。Sail が、アプリの Docker の入れ物の中でコマンドを動かしてくれます。
./vendor/bin/sail artisan list
Tinker(コマンドでためしに動かす)#
Laravel Tinker は、Laravel のアプリを、ターミナルで1行ずつためしに動かせる道具です(REPL と呼ばれる、「1行入力すると、その場で結果が返る」しくみ)。中では PsySH というパッケージが動いています。
インストール#
Laravel のアプリには、はじめから Tinker が入っています。もし外してしまったときは、Composer(PHP のパッケージを入れる道具)で入れ直せます。
composer require laravel/tinker
補足
ホットリロード(保存するとすぐ反映)・複数行の編集・入力の補完がほしいときは、Tinkerwell という別のアプリがあります。
使い方#
Tinker を使うと、モデル・ジョブ・イベントなど、アプリのほとんどを、ターミナルから動かせます。tinker コマンドで始めます。
php artisan tinker
Tinker の設定ファイルは、vendor:publish コマンドでアプリに取り出せます。
php artisan vendor:publish --provider="Laravel\Tinker\TinkerServiceProvider"
注意
dispatch ヘルパー関数と、Dispatchable クラスの dispatch メソッドは、ガベージコレクション(使い終わったものの片づけ)を使ってジョブをキューに入れます。そのため、Tinker の中でジョブを出すときは、Bus::dispatch か Queue::push を使ってください。
動かしてよいコマンドの一覧#
Tinker の中で動かしてよい Artisan コマンドは、許可の一覧で決まっています。はじめは、clear-compiled・down・env・inspire・migrate・migrate:install・up・optimize が動かせます。ほかのコマンドも許したいときは、tinker.php 設定ファイルの commands 配列に足します。
'commands' => [
// App\Console\Commands\ExampleCommand::class,
],
別名(エイリアス)を付けないクラス#
Tinker は、使ったクラスに、自動で短い別名を付けます。別名を付けたくないクラスは、tinker.php の dont_alias 配列に書きます。
'dont_alias' => [
App\Models\User::class,
],
コマンドを作る#
Artisan にはじめから入っているコマンドに加えて、自分用のコマンドも作れます。コマンドは、ふつう app/Console/Commands フォルダに置きます。ほかの場所に置いてもかまいませんが、その場所を Laravel に教える必要があります(下の「コマンドを登録する」)。
コマンドを生成する#
新しいコマンドは make:command で作ります。app/Console/Commands フォルダが無くても、はじめて動かしたときに作られます。
php artisan make:command SendEmails
コマンドの形#
作ったコマンドには、Signature と Description という PHP の属性(クラスの前に書く印)で、名前と説明を書きます。Signature には、コマンドが受け取る入力(引数やオプション)も書けます。コマンドが動くと、handle メソッドが呼ばれます。やりたい仕事は、ここに書きます。
handle メソッドの引数に、必要な道具のクラスを書くと、サービスコンテナ(クラスを作って渡してくれる、道具箱のようなしくみ)が自動で渡してくれます。
<?php
namespace App\Console\Commands;
use App\Models\User;
use App\Support\DripEmailer;
use Illuminate\Console\Attributes\Description;
use Illuminate\Console\Attributes\Signature;
use Illuminate\Console\Command;
#[Signature('mail:send {user}')]
#[Description('Send a marketing email to a user')]
class SendEmails extends Command
{
/**
* Execute the console command.
*/
public function handle(DripEmailer $drip): void
{
$drip->send(User::find($this->argument('user')));
}
}
ヒント
コマンドは軽くしておき、重い仕事は、アプリの別のクラス(サービス)にまかせるのがよいやり方です。同じ仕事を、ほかの場所からも使いまわせるからです。上の例でも、メールを送る重い仕事は、注入したサービスのクラスがしています。
終了コード#
handle が何も返さずに成功すると、コマンドは 0(成功を表す番号)で終わります。整数を返すと、その番号を終了コードにできます。
$this->error('Something went wrong.');
return 1;
コマンドの中のどのメソッドからでも、コマンドを「失敗」で終わらせたいときは fail を呼びます。すぐに止まって、終了コード 1 を返します。
$this->fail('Something went wrong.');
クロージャのコマンド#
クラスの代わりに、クロージャ(名前のない関数)でコマンドを書くこともできます。ルートをコントローラーの代わりにクロージャで書けるのと同じ考え方です。
クロージャのコマンドは routes/console.php に書きます。このファイルには、HTTP のルートではなく、ターミナルからアプリに入る入口を書きます。Artisan::command に、コマンドの書き方(シグネチャ)と、引数やオプションを受け取るクロージャを渡します。
Artisan::command('mail:send {user}', function (string $user) {
$this->info("Sending email to: {$user}!");
});
クロージャは、コマンド本体のオブジェクトにつながっています。そのため、クラスで書いたコマンドと同じ補助メソッドが、すべて使えます。
必要な道具を引数で受け取る#
引数やオプションに加えて、サービスコンテナから渡してもらいたいクラスも、クロージャの引数に書けます。
use App\Models\User;
use App\Support\DripEmailer;
use Illuminate\Support\Facades\Artisan;
Artisan::command('mail:send {user}', function (DripEmailer $drip, string $user) {
$drip->send(User::find($user));
});
クロージャのコマンドに説明を付ける#
クロージャのコマンドの説明は、purpose メソッドで付けます。php artisan list や php artisan help で表示されます。
Artisan::command('mail:send {user}', function (string $user) {
// ...
})->purpose('Send a marketing email to a user');
1つずつしか動かせないコマンド(Isolatable)#
注意
この機能を使うには、アプリの標準のキャッシュの方式を、memcached・redis・dynamodb・database・file・array のどれかにする必要があります。また、すべてのサーバーが、同じ中心のキャッシュサーバーとつながっている必要があります。
コマンドが、同時に1つしか動かないようにしたいことがあります。そのときは、コマンドのクラスに Illuminate\Contracts\Console\Isolatable インターフェイス(守るべき約束ごと)を付けます。
<?php
namespace App\Console\Commands;
use Illuminate\Console\Command;
use Illuminate\Contracts\Console\Isolatable;
class SendEmails extends Command implements Isolatable
{
// ...
}
Isolatable を付けると、オプションに自分で書かなくても、--isolated が使えるようになります。このオプションを付けて動かすと、同じコマンドがすでに動いていないかを Laravel が確かめます。標準のキャッシュで「アトミックロック」(同時に1つだけが取れる鍵)を取ろうとして、確かめます。すでに動いていれば、コマンドは動きませんが、終了コードは成功で終わります。
php artisan mail:send 1 --isolated
動けなかったときに返す終了コードを決めたいときは、isolated オプションに番号を渡します。
php artisan mail:send 1 --isolated=12
ロックの名前#
ふつう、ロックの名前には、コマンドの名前が使われます。名前を変えたいときは、コマンドのクラスに isolatableId メソッドを書きます。引数やオプションを名前に入れることもできます。
/**
* Get the isolatable ID for the command.
*/
public function isolatableId(): string
{
return $this->argument('user');
}
ロックの期限#
ロックは、ふつう、コマンドが終わると消えます。コマンドが途中で止まって終われなかったときは、1時間たつと消えます。期限は、コマンドに isolationLockExpiresAt メソッドを書くと変えられます。
use DateTimeInterface;
use DateInterval;
/**
* Determine when an isolation lock expires for the command.
*/
public function isolationLockExpiresAt(): DateTimeInterface|DateInterval
{
return now()->plus(minutes: 5);
}
入力の決めかた#
コマンドは、ユーザーから引数やオプションで値をもらうことが多いです。コマンドの signature(書き方の取り決め)に、名前・引数・オプションを、ルートのような短い書き方で、まとめて書けます。
引数#
引数もオプションも、波かっこ { } で囲みます。次の例では、必ず必要な引数 user を1つ決めています。
/**
* The name and signature of the console command.
*
* @var string
*/
protected $signature = 'mail:send {user}';
引数は、あってもなくてもよい形や、初期値を持つ形にもできます。
// あってもなくてもよい引数
'mail:send {user?}'
// 初期値を持つ引数
'mail:send {user=foo}'
| 書き方 | 説明 |
|---|---|
{user} |
必ず必要な引数 |
{user?} |
あってもなくてもよい引数 |
{user=foo} |
初期値(ここでは foo)がある引数 |
オプション#
オプションは、引数と並ぶもう1つの入力で、コマンドでは --(ハイフン2つ)を前に付けて渡します。値を受け取るものと、受け取らないものがあります。値を受け取らないオプションは、「スイッチ」(付けるか付けないか)として働きます。
/**
* The name and signature of the console command.
*
* @var string
*/
protected $signature = 'mail:send {user} {--queue}';
この例では、--queue を付けて動かすと、オプションの値は true になります。付けないと false です。
php artisan mail:send 1 --queue
値を受け取るオプション#
オプションに値を渡してもらいたいときは、オプション名の後ろに = を付けます。
/**
* The name and signature of the console command.
*
* @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 -Qdefault
| 書き方 | 説明 |
|---|---|
{--queue} |
値を受け取らないスイッチ。付ければ true、付けなければ false |
{--queue=} |
値を受け取るオプション。付けなければ null |
{--queue=default} |
初期値がある、値を受け取るオプション |
{--Q|queue=} |
短縮形(-Q)のあるオプション |
複数の値を受け取る入力(配列)#
引数やオプションに、複数の値を受け取らせたいときは * を使います。まず、引数の例です。
'mail:send {user*}'
コマンドに、user の値を順に並べて渡せます。たとえば次のように渡すと、user は 1 と 2 が入った配列になります。
php artisan mail:send 1 2
* は、あってもなくてもよい引数と組み合わせられます。0個以上の値を受け取れます。
'mail:send {user?*}'
複数の値を受け取るオプション#
オプションが複数の値を受け取るときは、値ごとにオプション名を付けて渡します。
'mail:send {--id=*}'
次のように、--id を何度も付けて動かします。
php artisan mail:send --id=1 --id=2
| 書き方 | 説明 |
|---|---|
{user*} |
複数の値を、配列で受け取る |
{user?*} |
0個以上の引数を、配列で受け取る |
{--id=*} |
同じオプションを何度も付けて、配列で受け取る |
入力の説明#
引数やオプションの説明は、名前の後ろに : で区切って書きます。長くなるときは、複数の行に分けてもかまいません。
/**
* The name and signature of the console command.
*
* @var string
*/
protected $signature = 'mail:send
{user : The ID of the user}
{--queue : Whether the job should be queued}';
足りない入力を聞き返す#
必須の引数が無いと、ふつうはエラーが出ます。代わりに、足りないときにユーザーへ聞き返すようにもできます。コマンドに PromptsForMissingInput インターフェイスを付けます。
<?php
namespace App\Console\Commands;
use Illuminate\Console\Command;
use Illuminate\Contracts\Console\PromptsForMissingInput;
class SendEmails extends Command implements PromptsForMissingInput
{
/**
* The name and signature of the console command.
*
* @var string
*/
protected $signature = 'mail:send {user}';
// ...
}
必須の引数を聞き返すとき、Laravel は、引数の名前や説明をもとに、自然な質問を作ってくれます。質問を自分で決めたいときは、promptForMissingArgumentsUsing メソッドを書き、引数の名前をキーにした質問の配列を返します。
/**
* Prompt for missing input arguments using the returned questions.
*
* @return array<string, string>
*/
protected function promptForMissingArgumentsUsing(): array
{
return [
'user' => 'Which user ID should receive the mail?',
];
}
質問と、入力欄に薄く出す見本の文字(プレースホルダー)の組も渡せます。
return [
'user' => ['Which user ID should receive the mail?', 'E.g. 123'],
];
聞き方を完全に自分で決めたいときは、ユーザーに聞いて答えを返すクロージャを渡します。
use App\Models\User;
use function Laravel\Prompts\search;
// ...
return [
'user' => fn () => search(
label: 'Search for a user:',
placeholder: 'E.g. Taylor Otwell',
options: fn ($value) => strlen($value) > 0
? User::whereLike('name', "%{$value}%")->pluck('name', 'id')->all()
: []
),
];
補足
使えるプロンプトの種類や使い方は、Laravel Prompts(見た目のよい入力欄を作る部品)の公式ドキュメントにくわしく書かれています。
オプションを選ばせたり入力させたりしたいときは、handle メソッドの中にプロンプトを書けます。ただ、自動で引数を聞き返したときだけ、オプションも聞きたいなら、afterPromptingForMissingArguments メソッドを書きます。
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use function Laravel\Prompts\confirm;
// ...
/**
* Perform actions after the user was prompted for missing arguments.
*/
protected function afterPromptingForMissingArguments(InputInterface $input, OutputInterface $output): void
{
$input->setOption('queue', confirm(
label: 'Would you like to queue the mail?',
default: $this->option('queue')
));
}
コマンドの入力と出力#
入力を受け取る#
コマンドが動いているあいだ、受け取った引数やオプションの値を使いたくなります。argument と option を使います。無いものを指定すると null が返ります。
/**
* Execute the console command.
*/
public function handle(): void
{
$userId = $this->argument('user');
}
引数をまとめて array で受け取るには arguments を呼びます。
$arguments = $this->arguments();
オプションも、option で同じように受け取れます。まとめて配列で受け取るには options を呼びます。
// 決まったオプションを受け取る
$queueName = $this->option('queue');
// すべてのオプションを配列で受け取る
$options = $this->options();
input メソッドを使うと、引数とオプションを Illuminate\Console\CommandInput として受け取れます。HTTP のリクエストと同じように、型(日付・数など)を決めて受け取るメソッド(たとえば date)が使えます。
use App\Enums\ReportType;
/**
* Execute the console command.
*/
public function handle(): void
{
$input = $this->input()->date('from');
// ...
}
input には、引数かオプションの名前を渡して、1つの値だけを取り出すこともできます。
$queue = $this->input('queue', 'default');
| メソッド | 説明 |
|---|---|
argument |
引数を1つ受け取る。無ければ null |
arguments |
すべての引数を配列で受け取る |
option |
オプションを1つ受け取る。無ければ null |
options |
すべてのオプションを配列で受け取る |
input |
引数とオプションを CommandInput として受け取る。名前を渡せば、その値だけ取り出す |
ユーザーに聞く#
補足
Laravel Prompts は、ターミナルのアプリに、見た目のよい入力欄(見本の文字や入力チェックつき)を付けるための PHP のパッケージです。
コマンドの途中で、ユーザーに入力してもらうこともできます。ask は質問を出し、入力された答えを返します。
/**
* Execute the console command.
*/
public function handle(): void
{
$name = $this->ask('What is your name?');
// ...
}
ask の2つ目の引数には、何も入力されなかったときに返す初期値を渡せます。
$name = $this->ask('What is your name?', 'Taylor');
secret は ask と似ていますが、入力した文字が画面に見えません。パスワードのような秘密の情報を聞くときに使います。
$password = $this->secret('What is the password?');
「はい・いいえ」を聞く#
「はい」か「いいえ」の確認には confirm を使います。ふつうは false を返します。y か yes と答えると true を返します。
if ($this->confirm('Do you wish to continue?')) {
// ...
}
2つ目の引数に true を渡すと、初期値が true になります。
if ($this->confirm('Do you wish to continue?', true)) {
// ...
}
入力の補完#
anticipate は、答えの候補を補完(入力の途中で候補を出すこと)してくれます。ユーザーは、候補に無い答えも入力できます。
$name = $this->anticipate('What is your name?', ['Taylor', 'Dayle']);
2つ目の引数にクロージャを渡すと、1文字入力するたびに呼ばれます。そこまでの入力を文字列で受け取り、補完の候補の配列を返します。
use App\Models\Address;
$name = $this->anticipate('What is your address?', function (string $input) {
return Address::whereLike('name', "{$input}%")
->limit(5)
->pluck('name')
->all();
});
選択肢から選ばせる#
決まった選択肢の中から選ばせたいときは choice を使います。3つ目の引数に、何も選ばれなかったときの初期値の番号(配列の添え字)を渡せます。
$name = $this->choice(
'What is your name?',
['Taylor', 'Dayle'],
$defaultIndex
);
4つ目と5つ目の引数で、正しい答えを選ばせる最大の回数と、複数選んでよいかを決められます。
$name = $this->choice(
'What is your name?',
['Taylor', 'Dayle'],
$defaultIndex,
$maxAttempts = null,
$allowMultipleSelections = false
);
| メソッド | 説明 |
|---|---|
ask |
質問して、入力された答えを返す。初期値も渡せる |
secret |
入力が見えない形で質問する。パスワード向き |
confirm |
「はい・いいえ」を聞く。初期値は false |
anticipate |
候補を補完しながら質問する。候補に無い答えも入力できる |
choice |
選択肢から選ばせる |
画面に出す#
画面に文字を出すには、line・newLine・info・comment・question・warn・alert・error を使います。それぞれ、役目に合った色(ANSI カラー)が付きます。ふつう info は緑の文字で出ます。
/**
* Execute the console command.
*/
public function handle(): void
{
// ...
$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);
| メソッド | 説明 |
|---|---|
line |
色を付けないふつうの文字を出す |
newLine |
空の行を出す。数も渡せる |
info |
情報を出す。ふつう緑の文字 |
comment |
役目に合った色で出す |
question |
役目に合った色で出す |
warn |
役目に合った色で出す |
alert |
役目に合った色で出す |
error |
エラーを出す。ふつう赤い文字 |
表#
table を使うと、複数の行と列のデータを、きれいな表にして出せます。列の名前とデータを渡すだけで、幅も高さも自動で決まります。
use App\Models\User;
$this->table(
['Name', 'Email'],
User::all(['name', 'email'])->toArray()
);
進み具合を出すバー#
時間のかかる仕事では、どこまで進んだかを示すバー(プログレスバー)があると親切です。withProgressBar は、渡した値を1つずつ処理するたびに、バーを進めて出します。
use App\Models\User;
$users = $this->withProgressBar(User::all(), function (User $user) {
$this->performTask($user);
});
バーの進めかたを自分で決めたいこともあります。その場合は、最初に全部で何段階あるかを決め、1つ処理するたびにバーを進めます。
$users = App\Models\User::all();
$bar = $this->output->createProgressBar(count($users));
$bar->start();
foreach ($users as $user) {
$this->performTask($user);
$bar->advance();
}
$bar->finish();
補足
もっとくわしい使い方は、Symfony(Laravel が使っている部品の集まり)のプログレスバーの公式ドキュメントにあります。
コマンドを登録する#
ふつう、Laravel は app/Console/Commands フォルダの中のコマンドを、すべて自動で登録します。ほかのフォルダも探してほしいときは、bootstrap/app.php の withCommands にフォルダを書きます。
->withCommands([
__DIR__.'/../app/Domain/Orders/Commands',
])
必要なら、コマンドのクラス名を withCommands に渡して、1つずつ手で登録することもできます。
use App\Domain\Orders\Commands\SendEmails;
->withCommands([
SendEmails::class,
])
Artisan が起動すると、アプリのすべてのコマンドが、サービスコンテナによって作られ、Artisan に登録されます。
プログラムからコマンドを動かす#
Artisan のコマンドを、ターミナルの外から動かしたいことがあります。たとえば、ルートやコントローラーからです。Artisan ファサード(:: で呼べる窓口)の call を使います。1つ目の引数に、コマンドの名前かクラス名を、2つ目の引数に、コマンドに渡す値の配列を渡します。終了コードが返ります。
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\Route;
Route::post('/user/{user}/mail', function (string $user) {
$exitCode = Artisan::call('mail:send', [
'user' => $user, '--queue' => 'default'
]);
// ...
});
コマンドの全体を、1つの文字列で渡すこともできます。
Artisan::call('mail:send 1 --queue=default');
配列の値を渡す#
配列を受け取るオプションには、値の配列を渡せます。
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\Route;
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 の queue を使うと、コマンドをキュー(時間のかかる仕事の順番待ちの列)に入れて、裏でワーカー(列から仕事を取り出して動かすプログラム)に動かしてもらえます。使う前に、キューの設定と、キューを待ち受ける処理の起動を済ませておきます。
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\Route;
Route::post('/user/{user}/mail', function (string $user) {
Artisan::queue('mail:send', [
'user' => $user, '--queue' => 'default'
]);
// ...
});
onConnection と onQueue を使うと、どの接続のどのキューに入れるかを決められます。
Artisan::queue('mail:send', [
'user' => 1, '--queue' => 'default'
])->onConnection('redis')->onQueue('commands');
ほかのコマンドから呼ぶ#
あるコマンドの中から、ほかのコマンドを呼びたいこともあります。call を使います。コマンドの名前と、引数やオプションの配列を渡します。
/**
* Execute the console command.
*/
public function handle(): void
{
$this->call('mail:send', [
'user' => 1, '--queue' => 'default'
]);
// ...
}
呼んだコマンドの出力をすべて消したいときは callSilently を使います。使い方は call と同じです。
$this->callSilently('mail:send', [
'user' => 1, '--queue' => 'default'
]);
シグナルを受け取る#
OS(パソコンの基本のしくみ)は、動いているプログラムに「シグナル」(合図)を送れます。たとえば SIGTERM は、OS がプログラムに「きちんと終わってください」と頼む合図です。コマンドの中で合図を受け取って動きたいときは、trap を使います。
/**
* Execute the console command.
*/
public function handle(): void
{
$this->trap(SIGTERM, fn () => $this->shouldKeepRunning = false);
while ($this->shouldKeepRunning) {
// ...
}
}
複数の合図を同時に受け取るには、合図の配列を渡します。
$this->trap([SIGTERM, SIGQUIT], function (int $signal) {
$this->shouldKeepRunning = false;
dump($signal); // SIGTERM / SIGQUIT
});
開発用の dev コマンド#
dev コマンドは、手元で開発するときに必要な処理を、1つのターミナルでまとめて動かします。ふつうは、PHP の開発用サーバー・キューのワーカー・ログを見る Pail・Vite(CSS と JavaScript をまとめる道具)の処理を、同時に動かします。
php artisan dev
中では、@laravel/multiplex というパッケージが処理を管理しています。npm(JavaScript の部品を入れる道具)で入れるパッケージです。処理ごとに専用のタブが付き、出力を検索したりスクロールしたりできます。処理には名前と色が付くので、見分けやすくなっています。処理が止まったときは自動でやり直し、終わるときは、すべての出力がターミナルに書き戻されるので、何も失われません。
補足
dev コマンドには Node 22.13 以上が必要です。Windows では、concurrently という npm のパッケージで代わりに動き、タブの画面は使えません。
ふつうに動く処理は、次の4つです。
| 名前 | コマンド |
|---|---|
server |
php artisan serve |
queue |
php artisan queue:listen --tries=1 --timeout=0 |
logs |
php artisan pail --timeout=0 |
vite |
npm run dev |
補足
vite の処理は、使っている Node のパッケージ管理の道具(npm・pnpm・Yarn・Bun)を自動で見つけて、それに合った実行のコマンドを使います。
dev の処理を変える#
dev が動かす処理は、DevCommands クラスで変えられます。ふつうは、AppServiceProvider の boot メソッドに書きます。register は、コマンドの文字列と、あれば名前を受け取ります。
use Illuminate\Foundation\DevCommands;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
DevCommands::register('some-command --flag', 'my-process');
}
Artisan のコマンドを登録するときは、artisan を使うと、前に php artisan が自動で付きます。
DevCommands::artisan('horizon', 'horizon');
同じように、node は、見つけたパッケージ管理の道具の実行コマンド(たとえば npm run)を前に付けます。nodeExec は、その道具の exec のコマンド(パッケージに入っているコマンドを動かすコマンド。たとえば npx)を前に付けます。
DevCommands::node('storybook', 'storybook');
DevCommands::nodeExec('tailwindcss -i resources/css/app.css -o public/css/app.css --watch', 'tailwind');
ふつうの処理と同じ名前で登録すると、自分の処理が、ふつうの処理を置きかえます。たとえば、サーバーの処理を別のポート番号にできます。
DevCommands::artisan('serve --host=localhost --port=9000', 'server');
ターミナルに出る処理の名前の色も変えられます。使える色のメソッドは、blue・purple・pink・orange・green・yellow です。color に、#ff6347 のような 16 進数の色の番号を渡すこともできます。
DevCommands::register('my-command', 'my-process')->green();
DevCommands::register('my-command', 'my-process')->color('#ff6347');
登録されている処理を、動かさずに一覧で見るには dev:list を使います。
php artisan dev:list
| メソッド | 説明 |
|---|---|
register |
コマンドの文字列と名前で、処理を登録する |
artisan |
前に php artisan を付けて登録する |
node |
パッケージ管理の道具の実行コマンド(npm run など)を付けて登録する |
nodeExec |
パッケージ管理の道具の exec(npx など)を付けて登録する |
blue・purple・pink・orange・green・yellow |
処理の名前の色を決める |
color |
好きな 16 進数の色を決める |
止まった処理をやり直す#
処理が止まると、Laravel は少し待ってからやり直します。最大5回やり直しても動かなければ、失敗としてあきらめます。動き出して1秒以内に止まった処理は、そもそも起動できていないと考えて、やり直しません。手で r を押してやり直すと、数え直しになります。
1回だけやり直しを止めたいときは、--no-restart を付けます。
php artisan dev --no-restart
アプリ全体でやり直しを止めたいときは、disableAutoRestart を呼びます。
DevCommands::disableAutoRestart();
dev の処理を選ぶ#
only を使うと、dev が決まった処理だけを動かします。except を使うと、決まった処理を除いて動かします。
// server と vite の処理だけ動かす
DevCommands::only('server', 'vite');
// キューのワーカー以外を動かす
DevCommands::except('queue');
パッケージが登録した処理や、Laravel がはじめから持っている処理を除くには、withoutVendorCommands と withoutDefaultCommands を使います。
DevCommands::withoutVendorCommands();
DevCommands::withoutDefaultCommands();
| メソッド | 説明 |
|---|---|
only |
渡した名前の処理だけ動かす |
except |
渡した名前の処理を除いて動かす |
withoutVendorCommands |
パッケージが登録した処理を除く |
withoutDefaultCommands |
Laravel がはじめから持っている処理を除く |
disableAutoRestart |
止まった処理のやり直しを、アプリ全体で止める |
雛形(スタブ)を変える#
Artisan の make で始まるコマンドは、コントローラー・ジョブ・マイグレーション・テストなど、いろいろなクラスを作ります。このとき使う雛形のファイルを「スタブ」と呼びます。スタブに、入力した値を入れて、新しいファイルを作るしくみです。作られるファイルに少し手を入れたいときは、stub:publish を使います。よく使うスタブをアプリに取り出して、自分用に直せます。
php artisan stub:publish
取り出したスタブは、アプリの一番上の stubs フォルダに入ります。スタブを直すと、そのあと make コマンドで作るクラスに反映されます。
Artisan のイベント#
コマンドが動くとき、Artisan は3つのイベント(「〜が起きた」という知らせ)を出します。Illuminate\Console\Events\ArtisanStarting・Illuminate\Console\Events\CommandStarting・Illuminate\Console\Events\CommandFinished です。
| イベント | 説明 |
|---|---|
ArtisanStarting |
Artisan が動き出した、その瞬間に出る |
CommandStarting |
コマンドが動く直前に出る |
CommandFinished |
コマンドが動き終わったときに出る |
関連するページ#
公式ドキュメント(英語)
2026年10月5日時点の内容をもとに、日本語でまとめています。