文档/控制台命令

控制台命令

框架 HLEB2 包含内置的控制台命令，以及开发人员使用框架创建自己命令的功能。

控制台命令从终端或任务调度程序执行，它们的入口点是位于项目根目录下的 'console' 文件，这是一个常规的 PHP 文件。

#标准命令

可通过运行控制台命令获取框架命令列表：

$php console --help

--version or -v                                 (显示框架的当前版本)
--info or -i [name]                             (显示 common 中的当前设置)
--help or -h                                    (显示默认命令列表)
--ping                                          (服务检查，返回预定义值)
--logs or -lg                                   (输出日志文件的最后几行)
--list or -l                                    (显示已添加命令列表)
--routes or -r                                  (格式化的路由列表)
--find-route (or -fr) <url> [method] [domain]   (通过 URL 搜索路由)
--route-info (or -ri) <url> [method] [domain]   (通过 URL 获取路由信息)
--clear-routes-cache or -cr                     (清除路由缓存)
--update-routes-cache or --routes-upd or -u     (更新路由缓存)
--clear-cache or -cc                            (清除框架缓存)
--add <task|controller|middleware|model> <name> [desc] (创建类)
--create module <name>                          (创建模块文件)
--clear-cache--twig or -cc-twig                 (清除 Twig 模板引擎的缓存)

<command> --help                                (显示命令帮助信息)

#创建自定义控制台命令

通过在 /app/Commands/Demo/ 文件夹中创建相应的类来添加自定义控制台命令的示例：

<?php

namespace App\Commands\Demo;

use Hleb\Base\Task;

class ExampleTask extends Task
{
    /**
     * Short description of the action.
     */
    protected function run(?string $arg = null): int
    {
        // Your code here.

        return self::SUCCESS_CODE;
    }
}

或通过内置的控制台命令：

$php console --add task demo/example-task "task description"

将创建一个文件 /app/Commands/Demo/ExampleTask.php。如果需要，可以修改默认模板来生成任务。

在框架中，命令名称由位于 /app/Commands/ 文件夹中的类名称（相对路径）组成。因此，建议最初给命令赋予有意义的名称，以反映其动作的本质。

现在你可以从控制台运行新命令，它也会出现在命令列表中。
但是由于它尚未输出结果，添加 --help 参数以获取命令信息。

$php console demo/example-task --help

#通过命令传递参数

修改命令类，使 run() 方法能够接受参数。

<?php

namespace App\Commands\Demo;

use Hleb\Base\Task;

class ExampleTask extends Task
{
    /**
     * Connecting two values using `and`.
     */
    protected function run(string $argA, string $argB): int
    {
        echo $argA . ' and ' . $argB . PHP_EOL;

        return self::SUCCESS_CODE;
    }
}

命令类中的返回值 self::SUCCESS_CODE 表示命令成功执行。如果控制台或任务调度器中的命令通过 && 链接，则在返回 self::ERROR_CODE 时执行将停止。这在 CI/CD 等复杂场景中也很有用。

接下来，使用两个参数执行命令以获取输出 'speed and quality'：

$php console demo/example-task speed quality

对于特殊情况，框架允许为命令创建命名参数。

#从代码执行命令

可以从应用程序代码或其他控制台命令中执行创建的命令。

use App\Commands\Demo\ExampleTask;
use Hleb\Static\Command;

Command::execute(new ExampleTask(), ['speed ', 'quality']);

但是，在这种情况下命令的输出将不会显示，因为其用途已改变。
若要获取命令的结果，需要在类中使用 $this->setResult() 方法来设置数据，然后通过 getResult() 方法从外部访问这些数据。

use App\Commands\Demo\ExampleTask;
use Hleb\Static\Command;

$task = new ExampleTask();
Command::execute($task, ['speed', 'quality']);
echo $task->getResult();

#在终端中指定文本颜色

要在终端中输出部分或全部文本为基本颜色之一，需要在命令中使用专门的 color() 方法。
例如：

<?php

namespace App\Commands\Demo;

use Hleb\Base\Task;

class ColoredTask extends Task
{
    protected function run(): int
    {
        $greenText = $this->color()->green('this text is green');
        $yellowText = $this->color()->yellow('this text is yellow');

        echo $greenText . " and " . $yellowText . PHP_EOL;

        return self::SUCCESS_CODE;
    }
}

#使用属性设置命令限制

可以使用 PHP 属性来控制创建命令的类型和用途。

属性 #[Purpose] 用于定义命令的可见性范围。

<?php

namespace App\Commands\Demo;

use Hleb\Base\Task;
use Hleb\Constructor\Attributes\Task\Purpose;

#[Purpose(status:Purpose::CONSOLE)]
class ExampleTask extends Task {
// ... //
}

此属性有一个 status 参数，您可以在其中指定选项：
Purpose::FULL - 无限制，默认值。
Purpose::CONSOLE - 只能用作控制台命令。
Purpose::EXTERNAL - 仅用于代码中，不列在命令列表中。

命令类的 #[Disabled] 属性禁用该命令。

命令类的 #[Hidden] 属性将其从控制台命令列表中隐藏。

← 模板引擎 TWIG 容器 →

页面翻译：chatgpt 4-o

PHP Framework HLEB2