Artisan 控制台

• 简介
  • Tinker (REPL)
• 编写命令
  • 生成命令
  • 命令结构
  • 闭包命令
  • 可隔离命令
• 定义输入期望
  • 参数
  • 选项
  • 输入数组
  • 输入描述
  • 提示缺少的输入
• 命令 I/O
  • 检索输入
  • 提示输入
  • 写入输出
• 注册命令
• 以编程方式执行命令
  • 从其他命令调用命令
• 信号处理
• 存根自定义
• 事件

简介

Artisan 是 Laravel 附带的命令行界面。Artisan 位于应用程序的根目录下，作为 artisan 脚本，并提供许多有用的命令，可以帮助你在构建应用程序时提供帮助。要查看所有可用的 Artisan 命令列表，可以使用 list 命令

php artisan list

每个命令还包含一个“帮助”屏幕，该屏幕显示并描述命令可用的参数和选项。要查看帮助屏幕，请在命令名称前加上 help

php artisan help migrate

Laravel Sail

如果你使用 Laravel Sail 作为你的本地开发环境，请记住使用 sail 命令行来调用 Artisan 命令。Sail 将在应用程序的 Docker 容器内执行你的 Artisan 命令

./vendor/bin/sail artisan list

Tinker (REPL)

Laravel Tinker 是 Laravel 框架的一个强大的 REPL，由 PsySH 包提供支持。

安装

所有 Laravel 应用程序默认都包含 Tinker。但是，如果你之前已从应用程序中删除了 Tinker，可以使用 Composer 安装它

composer require laravel/tinker

用法

Tinker 允许你在命令行上与整个 Laravel 应用程序交互，包括你的 Eloquent 模型、作业、事件等等。要进入 Tinker 环境，请运行 tinker Artisan 命令

php artisan tinker

你可以使用 vendor:publish 命令发布 Tinker 的配置文件

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

命令允许列表

Tinker 使用“允许”列表来确定哪些 Artisan 命令可以在其 shell 中运行。默认情况下，你可以运行 clear-compiled、down、env、inspire、migrate、migrate:install、up 和 optimize 命令。如果你想允许更多命令，可以将它们添加到 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
{
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'mail:send {user}';
 
    /**
     * The console command description.
     *
     * @var string
     */
    protected $description = 'Send a marketing email to a user';
 
    /**
     * Execute the console command.
     */
    public function handle(DripEmailer $drip): void
    {
        $drip->send(User::find($this->argument('user')));
    }
}

退出代码

如果 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;
 
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');

可隔离命令

有时你可能希望确保一次只能运行一个命令实例。要实现此目的，可以在你的命令类上实现 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 方法来自定义此键，从而允许您将命令的参数或选项集成到键中。

/**
 * Get the isolatable ID for the command.
 */
public function isolatableId(): string
{
    return $this->argument('user');
}

锁过期时间

默认情况下，隔离锁在命令完成后过期。或者，如果命令中断且无法完成，则锁将在一个小时后过期。但是，您可以通过在命令上定义 isolationLockExpiresAt 方法来调整锁的过期时间。

use DateTimeInterface;
use DateInterval;
 
/**
 * Determine when an isolation lock expires for the command.
 */
public function isolationLockExpiresAt(): DateTimeInterface|DateInterval
{
    return now()->addMinutes(5);
}

定义输入期望

在编写控制台命令时，通常需要通过参数或选项从用户那里收集输入。Laravel 使您能够使用命令上的 signature 属性非常方便地定义您期望从用户那里获取的输入。signature 属性允许您以单一、表达性、类似路由的语法定义命令的名称、参数和选项。

参数

所有用户提供的参数和选项都用花括号括起来。在以下示例中，命令定义了一个必需的参数：user

/**
 * The name and signature of the console command.
 *
 * @var string
 */
protected $signature = 'mail:send {user}';

您还可以使参数可选或为参数定义默认值。

// Optional argument...
'mail:send {user?}'
 
// Optional argument with default value...
'mail:send {user=foo}'

选项

选项，就像参数一样，是另一种形式的用户输入。选项在通过命令行提供时以两个连字符 (--) 为前缀。选项有两种类型：接收值的选项和不接收值的选项。不接收值的选项充当布尔“开关”。让我们来看一个此类选项的示例。

/**
 * The name and signature of the console command.
 *
 * @var string
 */
protected $signature = 'mail:send {user} {--queue}';

在此示例中，在调用 Artisan 命令时可以指定 --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}'

在终端上调用命令时，选项快捷方式应以单个连字符为前缀，并且在为选项指定值时不应包含 = 字符。

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

输入描述

您可以通过使用冒号将参数名称与描述分隔开，为输入参数和选项分配描述。如果您需要更多空间来定义命令，请随时将定义分散到多行。

/**
 * 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::where('name', 'like', "%{$value}%")->pluck('name', 'id')->all()
            : []
    ),
];

如果您希望提示用户选择或输入 选项，则可以在命令的 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')
    ));
}

命令 I/O

检索输入

在命令执行期间，您可能需要访问命令接受的参数和选项的值。为此，您可以使用 argument 和 option 方法。如果参数或选项不存在，则将返回 null。

/**
 * Execute the console command.
 */
public function handle(): void
{
    $userId = $this->argument('user');
}

如果您需要将所有参数作为 array 检索，请调用 arguments 方法。

$arguments = $this->arguments();

可以使用 option 方法像检索参数一样轻松地检索选项。要将所有选项作为数组检索，请调用 options 方法。

// Retrieve a specific option...
$queueName = $this->option('queue');
 
// Retrieve all options as an array...
$options = $this->options();

提示输入

除了显示输出外，您还可以要求用户在命令执行期间提供输入。ask 方法将使用给定的问题提示用户，接受他们的输入，然后将用户的输入返回给您的命令。

/**
 * Execute the console command.
 */
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 方法。每次用户键入输入字符时，都会调用闭包。闭包应接受一个字符串参数，其中包含迄今为止用户的输入，并返回一个用于自动完成的选项数组。

$name = $this->anticipate('What is your address?', function (string $input) {
    // Return auto-completion options...
});

多项选择题

如果您需要在询问问题时为用户提供一组预定义的选择，可以使用 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、info、comment、question、warn 和 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 方法显示空行。

// Write a single blank line...
$this->newLine();
 
// Write three blank lines...
$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();

注册命令

默认情况下，Laravel 会自动注册 app/Console/Commands 目录中的所有命令。但是，您可以指示 Laravel 使用应用程序的 bootstrap/app.php 文件中的 withCommands 方法扫描其他目录以查找 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;
 
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;
 
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 (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` 方法接受命令名称和命令参数/选项的数组。

/**
 * Execute the console command.
 */
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` 方法。

/**
 * Execute the console command.
 */
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
});

存根自定义

Artisan 控制台的 `make` 命令用于创建各种类，例如控制器、作业、迁移和测试。这些类是使用“存根”文件生成的，这些文件根据你的输入填充值。但是，你可能希望对 Artisan 生成的文件进行一些小的更改。为此，可以使用 `stub:publish` 命令将最常用的存根发布到你的应用程序中，以便你可以自定义它们。

php artisan stub:publish

已发布的存根将位于应用程序根目录下的 `stubs` 目录中。对这些存根所做的任何更改都将在你使用 Artisan 的 `make` 命令生成其对应的类时反映出来。

事件

Artisan 在运行命令时会分派三个事件：`Illuminate\Console\Events\ArtisanStarting`、`Illuminate\Console\Events\CommandStarting` 和 `Illuminate\Console\Events\CommandFinished`。`ArtisanStarting` 事件在 Artisan 开始运行时立即分派。接下来，`CommandStarting` 事件在命令运行之前立即分派。最后，`CommandFinished` 事件在命令执行完成后分派。