命令行界面

• Introduction
• Autocompletion
• 可用命令列表
• 构建命令
  • 定义输入期望
  • 检索输入
  • 处理过程信号
  • 处理记录
  • 写输出
• 注册命令
• 调用其他命令

#Introduction

Winter 包括几个命令行界面 (CLI) 命令和实用程序，允许安装和管理 Winter 及其插件和主题，执行站点维护并加快开发过程。控制台命令通过 Laravel 的执行Artisan 命令行工具。

通过使用终端或 shell 并在项目的根文件夹中运行以下命令来执行命令：

php artisan [command]

您可以通过不向 Artisan 工具提供任何命令来获取可用命令的列表：

php artisan

如果您需要帮助或每个命令的可用参数和选项列表，只需在命令后加上--help 旗帜：

php artisan [command] --help

#自动完成/建议的输入值

随着升级到 Laravel 9 / Symfony 6，添加了支持 命令能够向 shell 提供制表符自动完成结果，以改善用户体验。大多数 Winter 命令都提供开箱即用的输入值自动完成支持，并且很容易在您自己的自定义命令中添加支持 当延长Winter\Storm\Console\Command 基类。

此功能要求您在 shell 中运行一次命令，以便为所有 Laravel / Winter 控制台命令启用它：

php artisan completion --help

刚跑artisan completion 将生成需要导入到您的 shell 中的 shell 脚本，以便启用对 Winter / Laravel 命令的自动完成支持；通过--help flag 将提供有关如何安装生成的脚本的详细说明。

#可用命令列表

以下命令可用于每个Winter安装。单击命令名称可查看有关该命令用法的更多信息。

#构建命令

插件还可以提供额外的命令来增强 Winter 的额外功能。

如果你想创建一个名为myauthor:mycommand，你可以运行php artisan create:command MyAuthor.MyPlugin MyCommand 脚手架命令 这将在名为的文件中为该命令创建关联的类plugins/myauthor/myplugin/console/MyCommand.php 内容如下：

<?php namespace MyAuthor\MyPlugin\Console;

use Winter\Storm\Console\Command;

class MyCommand extends Command
{
    /**
     * @var string|null The default command name for lazy loading.
     */
    protected static $defaultName = 'myauthor:mycommand';

    /**
     * @var string The name and signature of this command.
     */
    protected $signature = 'myauthor:mycommand
        {myArgument : Command argument avaible through $this->argument("myArgument")}
        {--myOptionFlag : Defines a custom path to the "npm" binary}';

    /**
     * @var string The console command description.
     */
    protected $description = 'Install Node.js dependencies required for mixed assets';

    /**
     * Execute the console command.
     * @return int
     */
    public function handle(): int
    {
        $this->output->writeln('Hello world!');

        return 0; // return 1 if an error occurs
    }
}

创建班级后，您应该填写defaultName,signature， 和description 类的属性，将在命令上显示命令时使用list 屏幕。

这handle 执行命令时将调用方法。您可以在此方法中放置任何命令逻辑。

#定义输入期望

见Laravel 文档 有关如何定义命令具有的输入期望（参数和选项）的信息。

定义输入的选项：

• 输入说明
• Arguments
• Options
• 带值的选项
• 选项快捷方式
• 输入数组
• 选项数组
• 输入自动完成/建议值
• 插件名称作为参数

提供建议值

这Winter\Storm\Console\Traits\ProvidesAutocompletion trait 提供了一个默认的实现complete() 与 Symfony 提供的 shell 输入自动完成功能交互所需的方法。这使用类似于 Eloquent 中访问器的接口简化了自定义命令所需的实现工作。

NOTE: 这个特性默认在Winter\Storm\Console\Command 基类。

为了为给定的参数或选项提供输入建议，您所要做的就是将一个方法添加到您的命令类中，该方法以以下格式命名：suggest{$inputName}[Values|Options](string $currentValue, array $currentInput): array.

为参数提供值的方法应该以Values 为选项提供值的方法应该以Options.请参阅下面的几个示例实现：

// ...

    /**
     * Example implementation of a suggestion method for the "myArgument" argument
     */
    public function suggestMyArgumentValues(string $value = null, array $allInput): array
    {
        if ($allInput['arguments']['dependent'] === 'matches') {
            return ['some', 'suggested', 'values'];
        }
        return ['all', 'values'];
    }

    /**
     * Example implementation of a suggestion method for the "package" option
     */
    public function suggestPackageOptions(string $value = null, array $allInput): array
    {
        return Package::all()->pluck('name')->all();
    }

// ...

见Symfony 文档 了解更多信息。

插件名称作为参数

如果您的命令需要一个插件标识符作为其参数之一，以便确定对该特定插件采取的操作的范围，那么您可以使用System\Console\Traits\HasPluginArgument trait 以提供对所提供输入的自动验证和规范化以及对输入自动补全 特征。

只需将特征包含在您的班级中并定义plugin 作为命令签名中的参数：

use Winter\Storm\Console\Command;
use System\Console\Traits\HasPluginArgument;

class MyCommand extends Command
{
    use HasPluginArgument;

    // ...

    /**
     * @var string The name and signature of this command.
     */
    protected $signature = 'myauthor:mycommand
        {plugin : The plugin to interact with. <info>(eg: Winter.Blog)</info>}';

    // ...

    /**
     * @var string What type of plugins to suggest in the CLI autocompletion. Valid values: "enabled", "disabled", "all"
     */
    protected $hasPluginsFilter = 'enabled';

    public function handle()
    {
        // helper method that validates and normalizes the user provided input
        $pluginName = $this->getPluginIdentifier();

        // Do things with $pluginName
    }
}

#检索输入

见Laravel 文档 如何检索输入。

可用的输入法：

• 检索输入（参数和选项）
• 提示输入
• 要求确认（是/否）
• 要求确认（需要输入字符串）
• 自动完成/建议的答案
• 多项选择题
• 处理过程信号

#### Confirmation via input

除了Laravel 提供的额外输入选项， 这confirmsWithInput($message, $requiredInput) 方法可用于显示警告消息和提示，要求用户输入指定的字符串以确认潜在的破坏性操作。

此功能要求您的命令包括\Winter\Storm\Console\Traits\ConfirmsWithInput 特征。

use Winter\Storm\Console\Command;
use Winter\Storm\Console\Traits\ConfirmsWithInput;

class MyCommand extends Command
{
    use ConfirmsWithInput;

    public function handle()
    {
        $pluginName = $this->argument('plugin');

        if (!$this->confirmWithInput(
            "This will remove the database tables and files for the \"$pluginName\" plugin.",
            $pluginName
        )) {
            return 1;
        }

        // Do dangerous things with $pluginName
    }
}

这将显示以下内容：

如果您的命令定义了一个--force 签名中的选项，则该选项可用于绕过确认步骤和生产警报。

#处理过程信号

这Winter\Storm\Console\Traits\HandlesCleanup trait 提供了一个默认的实现getSubscribedSignals() &handleSignal() 与 Symfony 转发的进程信号交互所需的方法。这简化了自定义命令所需的实现工作，以满足在用户以跨平台友好的方式终止命令时执行清理任务的常见要求。

NOTE:这个特性默认在Winter\Storm\Console\Command 基类。如果你想将它添加到一个不扩展这个基类的类中，你还需要实现Symfony\Component\Console\Command\SignalableCommandInterface 你班级的界面。

要利用此特性，要么扩展基础Winter\Storm\Console\Command 类或添加Winter\Storm\Console\Traits\HandlesCleanup 特征到你的班级，然后实施handleCleanup() 方法如下图：

use Winter\Storm\Console\Command as BaseCommand;

class MyCommand extends BaseCommand // implements \Symfony\Component\Console\Command\SignalableCommandInterface
{
    // Uncomment if not extending the BaseCommand class
    // use \Winter\Storm\Console\Traits\HandlesCleanup;
    
    // ...

    /**
     * Handle the cleanup of this command if a termination signal is received
     */
    public function handleCleanup(): void
    {
        $this->newLine();
        $workingPath = storage_path('tmp/my-working-file.json');
        $this->info('Cleaning up: ' . $workingPath);
        unlink($workingPath);
    }
}

见Symfony 文档 了解更多信息。

#处理记录

Winter提供Winter\Storm\Console\ProcessesQuery 用于必须处理来自数据库查询的大量记录的控制台命令的特征。下面提供了该特征的示例使用：

<?php namespace MyAuthor\MyPlugin\Console;

use Winter\Storm\Console\Command;
use MyAuthor\MyPlugin\Models\MyModel;

class ProcessRecords extends Command
{
    use \Winter\Storm\Console\Traits\ProcessesQuery;
    use \Winter\Storm\Console\Traits\ConfirmsWithInput;

    /**
     * @var string The console command name.
     */
    protected static $defaultName = 'myplugin:processrecords';

    /**
     * @var string The name and signature of this command.
     */
    protected $signature = 'myplugin:processrecords
        {--limit=0 : The maximum number of records to process. Defaults to all.}
        {--chunk=100 : The number of records to process at once.}
        {--f|force : Force the operation to run and ignore production warnings and confirmation questions.}
    ';

    /**
     * @var string The console command description.
     */
    protected $description = 'Processes the selected records';

    /**
     * Execute the console command.
     */
    public function handle(): int
    {
        // Build the query that will retrieve all the records to be processed
        $query = MyModel::query()->withTrashed();

        // Get the total number of records to be processed for the alert message
        $totalRecords = $query->count();

        // Ask the user to confirm the processing action by entering the number
        // of records to be affected
        if (!$this->confirmWithInput(
            sprintf(
                'This will process all selected records, a total of %s.',
                number_format($totalRecords)
            ),
            $totalRecords
        )) {
            return 1;
        }

        // Process the records
        $this->processQuery(
            $query,
            function ($record) {
                $record->myCustomAction();
            },
            $this->option('chunk'),
            $this->option('limit')
        );

        return 0;
    }
}

#写输出

见Laravel 文档 了解如何将输出发送到控制台。

可用的输出方式：

• 信息消息（绿色文本）
• 错误信息（红色文本）
• 纯文本
• 新线
• Tables
• 进度条
• Alerts

Alerts

这alert($message) 方法可以很容易地用提供的消息呈现一个“警告框”，以引起对重要通知的更多关注。

此方法也由 Laravel 提供（目前未记录），但是 Winter 的实现还包括支持自动将警告框大小包装为标准的 80 个字符宽度，以防止长消息破坏警告框的格式。

$this->alert('This will remove the database tables and files for the "Winter.Builder" plugin.');

会输出

*************************************************************
*  This will remove the database tables and files for the   *
*                 "Winter.Builder" plugin.                  *
*************************************************************

#注册命令

注册控制台命令

命令类完成后，您需要注册它以便可以使用。这通常是在register 一个方法插件注册文件 使用registerConsoleCommand 辅助方法。

class MyPlugin extends PluginBase
{
    public function register()
    {
        $this->registerConsoleCommand('myauthor.mycommand', \MyAuthor\MyPlugin\Console\MyCommand::class);
    }
}

或者，插件可以提供一个名为init.php 在可用于放置命令注册逻辑的插件目录中。在此文件中，您可以使用Artisan::add 注册命令的方法：

Artisan::add(new MyAuthor\MyPlugin\Console\MyCommand);

在应用程序容器中注册命令

如果您的命令在应用容器, 你可以使用Artisan::resolve 使 Artisan 可用的方法：

Artisan::resolve('myauthor.mycommand');

在服务提供者中注册命令

如果您需要从一个服务提供者，你应该调用commands 提供者的方法boot 方法，通过container 绑定命令：

public function boot()
{
    $this->app->singleton('myauthor.mycommand', function() {
        return new \MyAuthor\MyCommand\Console\MyCommand;
    });

    $this->commands('myauthor.mycommand');
}

#调用其他命令

见Laravel 文档 了解如何以编程方式调用命令。