Artisan 控制台
简介
Artisan 是 Laravel 附带的命令行界面。Artisan 存在于应用程序根目录的 artisan 脚本中,提供了许多有用的命令,可以在您构建应用程序时提供帮助。要查看所有可用 Artisan 命令的列表,您可以使用 list 命令:
php artisan list每个命令还包含一个"帮助"屏幕,显示并描述命令可用的参数和选项。要查看帮助屏幕,请在命令名称前加上 help:
php artisan help migrateLaravel Sail
如果您使用 Laravel Sail 作为本地开发环境,请记住使用 sail 命令行来调用 Artisan 命令。Sail 将在应用程序的 Docker 容器中执行您的 Artisan 命令:
./vendor/bin/sail artisan listTinker (REPL)
Laravel Tinker 是 Laravel 框架的强大 REPL,由 PsySH 包提供支持。
安装
所有 Laravel 应用程序默认都包含 Tinker。但是,如果您之前已从应用程序中删除它,可以使用 Composer 安装 Tinker:
composer require laravel/tinkerNOTE
在与 Laravel 应用程序交互时,想要热重载、多行代码编辑和自动完成功能?请查看 Tinkerwell!
使用
Tinker 允许您在命令行上与整个 Laravel 应用程序交互,包括 Eloquent 模型、作业、事件等。要进入 Tinker 环境,运行 tinker Artisan 命令:
php artisan tinker您可以使用 vendor:publish 命令发布 Tinker 的配置文件:
php artisan vendor:publish --provider="Laravel\Tinker\TinkerServiceProvider"WARNING
dispatch 辅助函数和 Dispatchable 类上的 dispatch 方法依赖垃圾回收将作业放入队列。因此,使用 Tinker 时,您应该使用 Bus::dispatch 或 Queue::push 来分发作业。
命令允许列表
Tinker 使用"允许"列表来确定哪些 Artisan 命令可以在其 shell 中运行。默认情况下,您可以运行 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 扫描其他目录查找 Artisan 命令,您可以自由选择自己的存储位置。
生成命令
要创建新命令,您可以使用 make:command Artisan 命令。此命令将在 app/Console/Commands 目录中创建一个新的命令类。如果此目录在您的应用程序中不存在,不必担心——它将在您第一次运行 make:command Artisan 命令时创建:
php artisan make:command SendEmails命令结构
生成命令后,您应该使用 Signature 和 Description 属性定义命令的签名和描述。Signature 属性还允许您定义命令的输入期望。handle 方法将在命令执行时被调用。您可以在此方法中放置命令逻辑。
让我们看一个示例命令。请注意,我们可以通过命令的 handle 方法请求我们需要的任何依赖项。Laravel 服务容器 将自动注入此方法签名中类型提示的所有依赖项:
<?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
{
/**
* 执行控制台命令。
*/
public function handle(DripEmailer $drip): void
{
$drip->send(User::find($this->argument('user')));
}
}NOTE
为了更好的代码重用,保持控制台命令轻量并让它们委托给应用程序服务来完成其任务是良好的实践。在上面的示例中,请注意我们注入一个服务类来完成发送电子邮件的"繁重工作"。
退出码
如果 handle 方法没有返回任何内容且命令执行成功,命令将以 0 退出码退出,表示成功。但是,handle 方法可以选择返回一个整数来手动指定命令的退出码:
$this->error('Something went wrong.');
return 1;如果您想从命令内的任何方法"失败"命令,可以使用 fail 方法。fail 方法将立即终止命令的执行并返回退出码 1:
$this->fail('Something went wrong.');闭包命令
基于闭包的命令提供了一种将控制台命令定义为类的替代方法。就像路由闭包是控制器的替代方案一样,将命令闭包视为命令类的替代方案。
尽管 routes/console.php 文件不定义 HTTP 路由,但它定义了应用程序的基于控制台的入口点(路由)。在此文件中,您可以使用 Artisan::command 方法定义所有基于闭包的控制台命令。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');可隔离命令
WARNING
要使用此功能,您的应用程序必须使用 memcached、redis、dynamodb、database、file 或 array 缓存驱动程序作为应用程序的默认缓存驱动程序。此外,所有服务器必须与同一个中央缓存服务器通信。
有时您可能希望确保命令一次只能运行一个实例。为此,您可以在命令类上实现 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 时,Laravel 会自动为命令提供 --isolated 选项,而无需在命令选项中显式定义它。当使用该选项调用命令时,Laravel 将确保该命令没有其他实例正在运行。Laravel 通过尝试使用应用程序的默认缓存驱动程序获取原子锁来实现这一点。如果命令的其他实例正在运行,则该命令将不会执行;但是,该命令仍将以成功的退出状态码退出:
php artisan mail:send 1 --isolated如果您想指定命令无法执行时应返回的退出状态码,可以通过 isolated 选项提供所需的状态码:
php artisan mail:send 1 --isolated=12锁 ID
默认情况下,Laravel 将使用命令名称生成用于在应用程序缓存中获取原子锁的字符串键。但是,您可以通过在 Artisan 命令类上定义 isolatableId 方法来自定义此键,从而允许您将命令的参数或选项集成到键中:
/**
* 获取命令的可隔离 ID。
*/
public function isolatableId(): string
{
return $this->argument('user');
}锁过期时间
默认情况下,隔离锁在命令完成后过期。或者,如果命令被中断且无法完成,锁将在一小时后过期。但是,您可以通过在命令上定义 isolationLockExpiresAt 方法来调整锁过期时间:
use DateTimeInterface;
use DateInterval;
/**
* 确定命令的隔离锁何时过期。
*/
public function isolationLockExpiresAt(): DateTimeInterface|DateInterval
{
return now()->plus(minutes: 5);
}定义输入期望
编写控制台命令时,通常通过参数或选项从用户收集输入。Laravel 使用命令上的 signature 属性使定义您期望从用户获得的输入变得非常方便。signature 属性允许您使用单一、富有表现力、类似路由的语法定义命令的名称、参数和选项。
参数
所有用户提供的参数和选项都用花括号括起来。在以下示例中,命令定义了一个必需参数:user:
/**
* 控制台命令的名称和签名。
*
* @var string
*/
protected $signature = 'mail:send {user}';您还可以使参数可选或为参数定义默认值:
// 可选参数...
'mail:send {user?}'
// 带默认值的可选参数...
'mail:send {user=foo}'选项
选项与参数一样,是另一种形式的用户输入。选项通过命令行提供时以两个连字符(--)为前缀。有两种类型的选项:接收值的和不接收值的。不接收值的选项用作布尔"开关"。让我们看一个这种类型选项的示例:
/**
* 控制台命令的名称和签名。
*
* @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=}'在终端上调用命令时,选项快捷方式应以单个连字符为前缀,并且在为选项指定值时不应包含 = 字符:
php artisan mail:send 1 -Qdefault输入数组
如果您想定义参数或选项以期望多个输入值,可以使用 * 字符。首先,让我们看一个指定此类参数的示例:
'mail:send {user*}'运行此命令时,可以按顺序将 user 参数传递给命令行。例如,以下命令将 user 的值设置为包含 1 和 2 作为其值的数组:
php artisan mail:send 1 2此 * 字符可以与可选参数定义结合使用,以允许零个或多个参数实例:
'mail:send {user?*}'选项数组
定义期望多个输入值的选项时,传递给命令的每个选项值都应以选项名称为前缀:
'mail:send {--id=*}'可以通过传递多个 --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}';提示缺失输入
如果您的命令包含必需参数,当未提供这些参数时,用户将收到错误消息。或者,您可以通过实现 PromptsForMissingInput 接口来配置命令在缺少必需参数时自动提示用户:
<?php
namespace App\Console\Commands;
use Illuminate\Console\Command;
use Illuminate\Contracts\Console\PromptsForMissingInput;
class SendEmails extends Command implements PromptsForMissingInput
{
/**
* 控制台命令的名称和签名。
*
* @var string
*/
protected $signature = 'mail:send {user}';
// ...
}如果 Laravel 需要从用户收集必需参数,它将使用参数名称或描述智能地组织问题来自动询问用户。如果您想自定义用于收集必需参数的问题,可以实现 promptForMissingArgumentsUsing 方法,返回按参数名称键入的问题数组:
/**
* 使用返回的问题提示缺失的输入参数。
*
* @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()
: []
),
];NOTE
全面的 Laravel Prompts 文档包含有关可用提示及其使用的更多信息。
如果您想提示用户选择或输入选项,可以在命令的 handle 方法中包含提示。但是,如果您只想在用户也被自动提示缺失参数时提示用户,则可以实现 afterPromptingForMissingArguments 方法:
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use function Laravel\Prompts\confirm;
// ...
/**
* 在用户被提示缺失参数后执行操作。
*/
protected function afterPromptingForMissingArguments(InputInterface $input, OutputInterface $output): void
{
$input->setOption('queue', confirm(
label: 'Would you like to queue the mail?',
default: $this->option('queue')
));
}命令 I/O
检索输入
当命令执行时,您可能需要访问命令接受的参数和选项的值。为此,您可以使用 argument 和 option 方法。如果参数或选项不存在,将返回 null:
/**
* 执行控制台命令。
*/
public function handle(): void
{
$userId = $this->argument('user');
}如果您需要以 array 形式检索所有参数,调用 arguments 方法:
$arguments = $this->arguments();可以使用 option 方法像检索参数一样轻松检索选项。要以数组形式检索所有选项,调用 options 方法:
// 检索特定选项...
$queueName = $this->option('queue');
// 以数组形式检索所有选项...
$options = $this->options();提示输入
NOTE
Laravel Prompts 是一个 PHP 包,用于向命令行应用程序添加美观且用户友好的表单,具有浏览器般的功能,包括占位符文本和验证。
除了显示输出外,您还可以在命令执行期间要求用户提供输入。ask 方法将使用给定问题提示用户,接受其输入,然后将用户输入返回给您的命令:
/**
* 执行控制台命令。
*/
public function handle(): void
{
$name = $this->ask('What is your name?');
// ...
}ask 方法还接受可选的第二个参数,指定如果未提供用户输入时应返回的默认值:
$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?')) {
// ...
}如有必要,您可以通过将 true 作为第二个参数传递给 confirm 方法来指定确认提示默认返回 true:
if ($this->confirm('Do you wish to continue?', true)) {
// ...
}自动完成
anticipate 方法可用于为可能的选择提供自动完成。用户仍然可以提供任何答案,无论自动完成提示如何:
$name = $this->anticipate('What is your name?', ['Taylor', 'Dayle']);或者,您可以将闭包作为第二个参数传递给 anticipate 方法。每次用户输入字符时都会调用闭包。闭包应接受包含用户到目前为止输入的字符串参数,并返回用于自动完成的选项数组:
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 方法。如果未选择选项,您可以通过将索引作为第三个参数传递给方法来设置要返回的默认值的数组索引:
$name = $this->choice(
'What is your name?',
['Taylor', 'Dayle'],
$defaultIndex
);此外,choice 方法接受可选的第四和第五个参数,用于确定选择有效响应的最大尝试次数以及是否允许多选:
$name = $this->choice(
'What is your name?',
['Taylor', 'Dayle'],
$defaultIndex,
$maxAttempts = null,
$allowMultipleSelections = false
);编写输出
要将输出发送到控制台,您可以使用 line、newLine、info、comment、question、warn、alert 和 error 方法。这些方法中的每一个都将为其目的使用适当的 ANSI 颜色。例如,让我们向用户显示一些常规信息。通常,info 方法将在控制台中显示为绿色文本:
/**
* 执行控制台命令。
*/
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 方法显示空行:
// 写入单个空行...
$this->newLine();
// 写入三个空行...
$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 $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();NOTE
有关更多高级选项,请查看 Symfony Progress Bar 组件文档。
注册命令
默认情况下,Laravel 自动注册 app/Console/Commands 目录中的所有命令。但是,您可以在应用程序的 bootstrap/app.php 文件中使用 withCommands 方法指示 Laravel 扫描其他目录查找 Artisan 命令:
->withCommands([
__DIR__.'/../app/Domain/Orders/Commands',
])如有必要,您还可以通过向 withCommands 方法提供命令的类名来手动注册命令:
use App\Domain\Orders\Commands\SendEmails;
->withCommands([
SendEmails::class,
])当 Artisan 启动时,应用程序中的所有命令将由服务容器 解析并向 Artisan 注册。
编程式执行命令
有时您可能希望在 CLI 之外执行 Artisan 命令。例如,您可能希望从路由或控制器执行 Artisan 命令。您可以使用 Artisan 门面上的 call 方法来完成此操作。call 方法接受命令的签名名称或类名作为第一个参数,命令参数数组作为第二个参数。将返回退出码:
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'
]);
// ...
});或者,您可以将整个 Artisan 命令作为字符串传递给 call 方法:
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 命令
使用 Artisan 门面上的 queue 方法,您甚至可以将 Artisan 命令排队,以便由您的队列工作进程 在后台处理。在使用此方法之前,请确保您已配置队列并正在运行队列监听器:
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 命令应分发到的连接或队列:
Artisan::queue('mail:send', [
'user' => 1, '--queue' => 'default'
])->onConnection('redis')->onQueue('commands');从其他命令调用命令
有时您可能希望从现有 Artisan 命令调用其他命令。您可以使用 call 方法来完成此操作。此 call 方法接受命令名称和命令参数/选项数组:
/**
* 执行控制台命令。
*/
public function handle(): void
{
$this->call('mail:send', [
'user' => 1, '--queue' => 'default'
]);
// ...
}如果您想调用另一个控制台命令并抑制其所有输出,可以使用 callSilently 方法。callSilently 方法具有与 call 方法相同的签名:
$this->callSilently('mail:send', [
'user' => 1, '--queue' => 'default'
]);信号处理
如您所知,操作系统允许向运行中的进程发送信号。例如,SIGTERM 信号是操作系统要求程序终止的方式。如果您希望在 Artisan 控制台命令中监听信号并在它们发生时执行代码,可以使用 trap 方法:
/**
* 执行控制台命令。
*/
public function handle(): void
{
$this->trap(SIGTERM, fn () => $this->shouldKeepRunning = false);
while ($this->shouldKeepRunning) {
// ...
}
}要一次监听多个信号,可以向 trap 方法提供信号数组:
$this->trap([SIGTERM, SIGQUIT], function (int $signal) {
$this->shouldKeepRunning = false;
dump($signal); // SIGTERM / SIGQUIT
});Stub 自定义
Artisan 控制台的 make 命令用于创建各种类,如控制器、作业、迁移和测试。这些类使用"stub"文件生成,这些文件根据您的输入填充值。但是,您可能希望对 Artisan 生成的文件进行小的更改。为此,您可以使用 stub:publish 命令将最常见的 stub 发布到您的应用程序,以便您可以自定义它们:
php artisan stub:publish发布的 stub 将位于应用程序根目录的 stubs 目录中。您对这些 stub 所做的任何更改将在使用 Artisan 的 make 命令生成其相应类时反映出来。
事件
Artisan 在运行命令时触发三个事件:Illuminate\Console\Events\ArtisanStarting、Illuminate\Console\Events\CommandStarting 和 Illuminate\Console\Events\CommandFinished。ArtisanStarting 事件在 Artisan 开始运行时立即触发。接下来,CommandStarting 事件在命令运行之前立即触发。最后,CommandFinished 事件在命令完成执行后触发。