README

文档

英文版本
俄文版本

英文

用于快速开发PHP命令行应用程序的简单易用库。

PHP版本 > = 7.1

安装

composer require --prefer-dist alexp007/cli

快速开始

请记住包括composer自动加载器，例如这样

require __DIR__ . "/../vendor/autoload.php"; // path to autoload.php

然后

use Cli\Basic\Cli;

Cli::initialize([
    'script_file_name' => 'cli.php' // название файла
]);

Cli::handle('sayHi', function ($name) { // callable 
    return "hi " . $name; 
});

Cli::run();

现在可以通过命令行使用命令

php cli.php sayHi pete

执行结果将是

hi pete

创建命令

您可以使用以下方式创建任意数量的命令：

Cli::handle($commandName, $callable)

$commandName - (string) 命令名称
$callable - (callable) 任何有效的PHP回调，如果您需要传递静态类方法，则使用 ['Class', 'MethodName']

扩展语法如下所示

Cli::handle(string $command, callable $callback, array $flags = array(), array $env = array())

$flags - (array) 与命令一起使用的允许标志，例如 ['-r', '--name']
$env - (array) 环境变量：任何应在回调内部可用的数据（用于避免全局依赖）。全局变量将被覆盖

扩展命令声明示例

use Cli\Basic\Cli;
use Cli\Basic\Flags;
use Cli\Basic\Environment;

Cli::handle('sayHi', function ($name, Flags $flags, Environment $env) { // callable
    if ($flags->getFlag('--send')) {
        return "mail sent to administrator" . $env->getEnv('email');  
    }
    return "hi " . $name;
}, ['--send'], ['email' => 'name@mail.ru']);

如果您想使用标志和环境，那么在参数中指定数据类型是强制性的。

此库严格遵循命令的参数，这意味着期望单个参数的命令必须提供该参数才能调用。然而，如果参数是可选的，那么在创建函数时，您应该指定参数的默认值为null，例如

Cli::handle('sayHi', function ($name = null) {
    return 'hi';
});

如果您期望可变数量的参数，那么请使用Params对象

use Cli\Basic\Cli;
use Cli\Basic\Params;

Cli::handle('bit', function(Params $params){
    $allParams = $params->getArray();
    return join(',', $allParams);
});

当使用特殊对象（Params、Flags、Environment）作为参数时，它们的顺序无关紧要

use Cli\Basic\Cli;
use Cli\Basic\Flags;
use Cli\Basic\Params;
use Cli\Basic\Environment;

Cli::handle('sayHi', function (Flags $flags, Environment $env, Params $params) { // callable
   return $params;
}, ['--send'], ['email' => 'name@mail.ru']);

其他参数应先于特殊参数指定。

基本规则

从命令行调用命令时，标志必须先于参数传递，例如

php cli.php sayHi -f pete
您可以使用前缀"-"或"--"的标志
您可以通过"="将标志的值传递给它们

php cli.php sayHi --mail=pete@mail.ru pete
如果标志没有使用值，则它将设置为Flags对象中的默认值true

php cli.php sayHi -f pete

-f 将为true
此库不允许使用在创建命令时未指定的标志，例如，对于以下命令，将无法使用"-r"标志

Cli::handle('sayHi', function ($name) { return "hi " . $name; }, [-f]);
此外，此库严格遵循命令的参数数量（请参阅上面“创建命令”部分）
此外，在系统中不能有两个具有相同名称的命令。此库对此非常重视）

特殊对象

Params

Params::getParam(int $n) - where $n is position
Params::getArray(): array // all params

Flags

Flags::getFlag(string $flag)
Flags::getArray(): array // all flags

Environment

Environment::getEnv(string $key)
Environment::getArray(): array // all environment vars

配置

在初始化应用程序时，您可以设置配置设置，以下是一个示例

Cli::initialize([
    'script_file_name'            => 'cli.php',
    'enable_list'                 => 'on',
    'enable_exceptions'           => 'on',
    'enable_errors'               => 'on',
    'enable_find_command_package' => 'on',
]);

script_file_name - 连接到库的文件名称 - 必需
enable_list - 允许使用列表（显示所有可用命令的内置命令）
enable_exceptions - 包含库的异常和说明（始终推荐）
enable_errors - 启用错误（建议仅在调试时启用）
enable_find_command_package - 启用内置搜索命令的包

您可以通过将它们作为第二个参数传递来设置全局变量。它们将在命令的特殊对象Environment内部可用

别名

在传递环境变量时，您可以使用@特殊字符来使用别名。别名将被插入到字符串中，例如

Cli::initialize([
        'script_file_name' => 'cli.php',
    ], [
        'object' => 'ufo',
        'article_name' => '@object is flying in the sky'
    ]);

article_name的值将是："ufo is flying in th sky"

内置命令

list（如果 'enable_list' => 'on'）允许您使用内置的list命令，该命令列出系统中注册的所有团队及其简要信息

php cli.php list

将返回

+-------------+---------------+------------------+
| Command     | Params        | Flags            |
+-------------+---------------+------------------+
| bit         |               |                  |
| find:file   | path, pattern | -r               |
| find:inFile | path, pattern | -r, --extensions |
| list        |               |                  |
| sayHi       |               | --send           |
| table       |               |                  |
+-------------+---------------+------------------+

find:file [搜索目录的路径] [模式 - 正则表达式] -> 在系统中搜索文件。

您可以使用"-r"标志递归地搜索子目录

php cli.php find:file ./ "php"

将找到具有php扩展名的文件

+--------------+----------------+
| Filename     | Filepath       |
+--------------+----------------+
| autoload.php | ./autoload.php |
| cli.php      | ./cli.php      |
+--------------+----------------+

find:inFile [搜索目录的路径] [模式 - 正则表达式] -> 在文件中搜索匹配项。

您可以使用-r标志递归地搜索子目录，并且“--extensions”标志表示确切的扩展名，用逗号分隔（只搜索这些文件）

php cli.php find:inFile --extensions=php ./ "include"

将返回

+--------------------------------+------+----------+-----------+
| Match                          | Line | Filename | Filepath  |
+--------------------------------+------+----------+-----------+
| include_once "src/$class.php"; | 12   | cli.php  | ./cli.php |
+--------------------------------+------+----------+-----------+

要使用find包命令，您需要在配置中设置'enable_find_command_package' => 'on'。

格式化器

一个简化输出结果工作的类

use Cli\Basic\Formatter;

输出红色颜色

Formatter::red() : $this

输出蓝色颜色

Formatter::blue() : $this

输出红色颜色

Formatter::yellow() : $this

表格视图

Formatter::asTable(): $this

换行

Formatter::line() : $this

打印到输出流

Formatter::printOut()

创建一个新的Formatter（您可以传递一个数组或一个字符串）

new Formatter(array or string $data)

特殊对象（Params、Flags、Environment）可以不进行额外适配地传递

use Cli\Basic\Cli;
use Cli\Basic\Formatter;
        
Cli::handle('bit', function(Params $params){
    $fmt = new Formatter($params);
    return $fmt->blue();
});

示例表格输出

use Cli\Basic\Cli;
use Cli\Basic\Formatter;

Cli::handle('table', function() {
    $data = [
        ['command_1', 'params', 'flags'],
        ['command_2', '[1,34,56,]', '[-f -r -d]'],
        ['special_command', '[1,string,56,]', '[-f -r -d]'],
    ];

    $fmt = new Formatter($data);
    return $fmt->asTable()->red();

});

祝您成功开发！

有任何问题或建议，请通过alex.p.panteleev@gmail.com联系我，以及创建问题。

欢迎贡献者！

俄语

这是一个简单易用的PHP命令行应用程序快速开发的库。

版本php >= 7.1

安装

composer require --prefer-dist alexp007/cli

快速启动

请确保连接自动加载器composer，例如

require __DIR__ . "/../vendor/autoload.php"; // путь до автозагрузчика

然后

use Cli\Basic\Cli;

Cli::initialize([
    'script_file_name' => 'cli.php' // название файла
]);

Cli::handle('sayHi', function ($name) { // callable 
    return "hi " . $name; 
});

Cli::run();

然后可以在命令行中使用

php cli.php sayHi pete

执行结果将是

hi pete

创建命令

您可以使用以下方式创建任意数量的命令

Cli::handle($commandName, $callable)

$commandName - (string) 命令名称
$callable - (callable) 任何有效的PHP回调，如果需要传递类的静态方法则 ['Class', 'MethodName']

扩展语法如下

Cli::handle(string $command, callable $callback, array $flags = array(), array $env = array())

$flags - (array) 与命令一起使用的允许的标志，例如 ['-r', '--name']
$env - (array) 环境变量：任何在$callback内部可用的数据（用于避免全局依赖）。全局环境变量将被重写

扩展创建命令可能如下所示

use Cli\Basic\Cli;
use Cli\Basic\Flags;
use Cli\Basic\Environment;

Cli::handle('sayHi', function ($name, Flags $flags, Environment $env) { // callable
    if ($flags->getFlag('--send')) {
        return "mail sent to administrator" . $env->getEnv('email');  
    }
    return "hi " . $name;
}, ['--send'], ['email' => 'name@mail.ru']);

如果您想使用Flags和Environment，则在参数中指定数据类型是必须的。

该库对命令参数严格要求，这意味着不能在没有参数的情况下调用期望一个参数的命令。然而，如果参数不是必需的，则在创建函数时应指定参数的null默认值，例如

Cli::handle('sayHi', function ($name = null) {
    return 'hi';
});

如果您期望可变数量的参数，则建议使用Params对象

use Cli\Basic\Cli;
use Cli\Basic\Params;

Cli::handle('bit', function(Params $params){
    $allParams = $params->getArray();
    return join(',', $allParams);
});

在使用作为参数的特殊对象（Params、Flags、Environment）时，它们的顺序没有意义

use Cli\Basic\Cli;
use Cli\Basic\Flags;
use Cli\Basic\Params;
use Cli\Basic\Environment;

Cli::handle('sayHi', function (Flags $flags, Environment $env, Params $params) { // callable
   return $params;
}, ['--send'], ['email' => 'name@mail.ru']);

任何普通参数应先于特殊参数指定。

主要规则

在从命令行调用命令时，标志应先于参数传递，例如

php cli.php sayHi -f pete
您可以使用带有前缀"-"或"--"的标志
您还可以通过"="将值与标志一起传递

php cli.php sayHi --mail=pete@mail.ru pete
如果没有值使用标志，则其值在Flags对象中设置为默认值true

php cli.php sayHi -f pete

-f等于true
库不会允许使用在创建命令时未指定的标志，例如对于下一个命令，不能使用标志"-r"。

Cli::handle('sayHi', function ($name) { return "hi " . $name; }, [-f]);
同样，库对命令的参数数量有严格的要求（参见上文中“创建命令”一节）
在系统中，不允许存在两个同名命令。库会密切关注这一点 =)

特殊对象

Params

Params::getParam(int $n) - where $n is position
Params::getArray(): array // all params

Flags

Flags::getFlag(string $flag)
Flags::getArray(): array // all flags

Environment

Environment::getEnv(string $key)
Environment::getArray(): array // all environment vars

配置

在初始化应用程序时，可以传递配置参数的设置，以下是一个使用所有设置的示例

Cli::initialize([
    'script_file_name'            => 'cli.php',
    'enable_list'                 => 'on',
    'enable_exceptions'           => 'on',
    'enable_errors'               => 'on',
    'enable_find_command_package' => 'on',
]);

script_file_name - 连接库的文件名 - 必须设置
enable_list - 允许使用列表（内置命令，显示所有可用命令的列表）
enable_exceptions - 启用库的异常和解释（建议始终启用）
enable_errors - 启用错误（建议仅在进行调试时启用）
enable_find_command_package - 连接内置命令搜索包

同样，支持将全局变量作为第二个参数传递，这些变量将在命令内的特殊对象 Environment 中可用

   Cli::initialize([
           'script_file_name' => 'cli.php',
        ], [
           'custom_var' => 'value' // любые типы данных
        ]
   );

别名

在传递环境变量时，您可以使用特殊符号 @ 来使用别名。别名将在字符串内部进行插值，例如

Cli::initialize([
    'script_file_name' => 'cli.php',
], [
    'object' => 'ufo',
    'article_name' => '@object is flying in the sky'
]);

article_name 的值将是: "ufo is flying in the sky"

内置命令

list（如果 'enable_list' => 'on'）允许使用内置命令 list，该命令将显示系统中注册的所有命令及其简要信息

php cli.php list

+-------------+---------------+------------------+
| Command     | Params        | Flags            |
+-------------+---------------+------------------+
| bit         |               |                  |
| find:file   | path, pattern | -r               |
| find:inFile | path, pattern | -r, --extensions |
| list        |               |                  |
| sayHi       |               | --send           |
| table       |               |                  |
+-------------+---------------+------------------+

find:file [搜索目录的路径] [模式 - 正则表达式] -> 在系统中搜索文件。

可以使用 "-r" 标志进行递归搜索子目录

php cli.php find:file ./ "php"

将找到具有 php 扩展名的文件

+--------------+----------------+
| Filename     | Filepath       |
+--------------+----------------+
| autoload.php | ./autoload.php |
| cli.php      | ./cli.php      |
+--------------+----------------+

find:inFile [搜索目录的路径] [模式 - 正则表达式] -> 在文件内进行搜索。

可以使用 "-r" 标志进行递归搜索子目录和 "--extensions" 标志来指定特定的扩展名（仅对这些文件进行搜索）

php cli.php find:inFile --extensions=php ./ "include"

+--------------------------------+------+----------+-----------+
| Match                          | Line | Filename | Filepath  |
+--------------------------------+------+----------+-----------+
| include_once "src/$class.php"; | 12   | cli.php  | ./cli.php |
+--------------------------------+------+----------+-----------+

要使用 find 命令包，需要在配置中设置 'enable_find_command_package' => 'on'。

格式化器

简化输出结果的类

use Cli\Basic\Formatter;

输出颜色为红色

Formatter::red() : $this

输出颜色为蓝色

Formatter::blue() : $this

输出颜色为红色

Formatter::yellow() : $this

表格表示

Formatter::asTable(): $this

换行

Formatter::line() : $this

打印到输出流

Formatter::printOut()

创建新的 Formatter（可以传递数组或字符串）

new Formatter(array or string $data)

可以不经过处理传递特殊对象（Params，Flags，Environment）

use Cli\Basic\Cli;
use Cli\Basic\Formatter;
        
Cli::handle('bit', function(Params $params){
    $fmt = new Formatter($params);
    return $fmt->blue();
});

表格输出示例

    use Cli\Basic\Cli;
    use Cli\Basic\Formatter;
    
    Cli::handle('table', function() {
        $data = [
            ['command_1', 'params', 'flags'],
            ['command_2', '[1,34,56,]', '[-f -r -d]'],
            ['special_command', '[1,string,56,]', '[-f -r -d]'],
        ];
    
        $fmt = new Formatter($data);
        return $fmt->asTable()->red();
    
    });

祝您开发顺利！

如有任何问题或建议，请发送至 alex.p.panteleev@gmail.com，并创建 issues。

欢迎所有愿意贡献的人！

alexp007 / cli

维护者

详细信息

README

英文

安装

快速开始

创建命令

基本规则

特殊对象

Params

Flags

Environment

配置

别名

内置命令

格式化器

祝您成功开发！

俄语

安装

快速启动

创建命令

主要规则

特殊对象

Params

Flags

Environment

配置

别名

内置命令

格式化器

祝您开发顺利！