b-hayes/cli

运行任何PHP类作为命令行应用程序

维护者

详细信息

github.com/b-hayes/CLI

源代码

问题

安装: 81

依赖者: 0

建议者: 0

安全: 0

星级: 3

关注者: 1

分支: 0

开放问题: 5

v0.0.9 2022-06-07 17:33 UTC

Requires

Requires (Dev)

MIT 8240a6f8402e07986923706c2cadb0b04d46f953

  • b-hayes <bradozman.woop@gmail.com>

This package is auto-updated.

Last update: 2024-09-14 15:29:06 UTC

README

用零努力快速构建交互式PHP命令行应用程序。

安装

composer require b-hayes/cli

用法。

只需定义一个PHP类并将其注入到CLI包装器中 😎。

(new \BHayes\CLI\CLI( $yourClass ))->run();

现在您可以构建类方法，而无需管理输入、退出代码或打印使用提示！ 😲

https://i.imgur.com/uu8gQBr.gif

行为。

当CLI运行您的类对象时，会发生以下情况

  • 公共方法作为可执行命令公开。 👍
  • 自动强制执行所需输入和数据类型。 🙂
  • 自动提供使用提示以引导用户。 😊
  • 打印返回的任何内容。（如果是一个对象，则只打印公共属性）。 😃
  • 使用Shell退出代码管理错误消息！ 😲
  • 将公共属性映射到选项/标志。 🤯
  • 轻松打印或返回彩色字符串，并提示输入/确认。 😍

参数。

参数直接映射到函数定义。

  • 参数类型被严格强制（例如，布尔值必须是'true'或'false'，而整数不能有小数位数）。
  • 防止用户传递过多参数，除非它是 ...可变参数。 (PHP允许这样做，但我没有)

单函数脚本。

如果您实现__invoke()方法或传递一个代替类的匿名函数，则您的应用程序将立即执行，无需用户输入。

选项/标志

基于POSIX标准，从公共类属性自动创建短选项-o和长选项--longOption。

public $cats;
if($this->cats) { echo "Cat mode enabled!"; }

https://i.imgur.com/mGr1PIj.gif

CLI目前尚不支持带有参数的选项。

我计划使用类型提示在php7.4及以上版本中支持此功能，但在为7.2用户完善功能之前不会这样做。

保留选项。

CLI保留了一些选项

  • --help。仅打印相关文档块并退出，而不会运行您的类。（可能在未来变得更漂亮）。
  • --debug。调试模式，如果启用，将打印所有异常/错误及其堆栈跟踪。
  • -i目前不执行任何操作。（我有一些关于交互式模式的想法）。

https://i.imgur.com/EXuX9Jx.gif

退出代码和错误。

CLI在失败时将自动返回非零退出代码。错误输出被抑制，除非您使用--debug模式或抛出[Response异常](#Response Exceptions)。

依赖关系

CLI没有依赖项，并且不会强制您依赖它，如果您将类用于其他目的。

入门示例。

对于不熟悉shell脚本的人来说...

创建一个带有shebang行（#!）的文件，告诉您的shell使用PHP运行此文件。

#!/usr/bin/env php
<?php //        👆 important 👇
require_once __DIR__ . '/../vendor/autoload.php';
//Just using anonymous class as a quick single file example.
$yourClass = new Class() {
    function hello(int $number = 0) {
        if ($number > 10) throw new \BHayes\CLI\UserErrorResponse("$number is too big for me!");
        if ($number) return "You gave me the number $number";
        return 'Hi ' . \BHayes\CLI\CLI::prompt('Enter your name', `git config user.name`);
    }
};

(new \BHayes\CLI\CLI( $yourClass ))->run();

接下来，使文件可执行： chmod +x myAwesomeNewCliApp

现在您可以将其作为终端应用程序运行了！

./myAwesomeNewCliApp

CLI将指导终端用户如何运行您的类的可用方法。

Windows用户

对于那些想使用powershell && cmd的人来说。创建一个包含以下内容的批处理文件

php %~dp0/myAwesomeNewCliApp -- %*

💡 开始一个集合。

我建议将您的CLI应用程序保留在个人项目中，并将它的/bin文件夹添加到您的系统路径中，以便所有CLI应用程序都可以全局访问。

我这样做并使用git同步我的个人开发工具跨计算机。 😉

错误处理。

CLI默认捕获所有错误并显示一个通用的程序崩溃信息。如果需要，可以使用--debug来查看堆栈跟踪。

响应异常

由输入或外部因素引起的错误，你需要在返回用户响应的同时返回/记住使用一个非零退出代码，以便父shell进程知道命令已失败。

只需在任何地方抛出UserResponseException，CLI就会处理它。

为了方便，我提供了几个，包括成功响应，这样你就不必一路返回两个值。

throw new \BHayes\CLI\UserResponse('This has an exit code of 1 and no coloured output');
throw new \BHayes\CLI\UserErrorResponse('Exit code 1 and text is printed in RED');
throw new \BHayes\CLI\UserWarningResponse('Exit code 1 and text is printed in YELLOW');
//IMPORTANT: all responses have an exit code of 1 by default except this one 👇
throw new \BHayes\CLI\UserSuccessResponse('Exit code 0 and text is printed in GREEN');

你也可以指定颜色、表情符号以及更具体的错误代码。

throw new \BHayes\CLI\UserResponse('Printer failed!',\BHayes\CLI\Colour::BG_LIGHT_MAGENTA, '🖨🔥', 221);

单独的图标字符串用于在全球范围内禁用没有UTF-8支持的终端上的表情符号输出（未来）。

错误代码放在最后，因为通常只有0或非零才重要，以指示成功/失败。（除了php 8允许我们现在绕过参数顺序）

自定义响应异常。

你可能想指定自己的异常，以便将其作为CLI响应处理，而不是使用提供的异常。只需在构造函数中传递一个类名列表。

$cli = new CLI($class, [
    MyCustomException::class,
    SomeSpecificThirdPartyException::class,
]);

警告：请记住，默认情况下，所有PHP和第三方异常的代码都是0，并报告成功响应，因为没有人认为它们会被用于CLI退出代码。你必须警惕并手动考虑这一点。

强制调试模式。

在开发过程中，你可能希望始终以调试模式运行，而无需每次都输入--debug。只需在构造函数的第三个参数中传递true。

$cli = new CLI($class, [], true);

或者，你可以通过传递false来完全删除调试选项。

$cli = new CLI($class, [], true);

副作用：如果用户现在输入--debug，则应用程序不会运行，因为现在它是一个无效的选项。

为了避免这种情况，你可以模拟有人输入它

global $argv; //this is a built-in var where php puts command line inputs
$argv[] = '--debug'; //manually add the --debug input as if the user typed it
$cli->run();

你还可以在将调试选项作为属性传递的同时完全防止调试选项。

$argv[] = '--debug'; //this will get passed to your application but have no effect on CLI
$cli->run(false);//because debug has been explicitly disabled at run time.

（这里支持极端边缘用例，这可能会改变。）

CLI作为全局工具。

CLI包含一个供应商bin来运行自身，在终端中公开其提示和颜色打印方法

./vendor/bin/cli prompt Name? `git config user.name`

你可以全局安装该包

composer global require b-hayes/cli

然后可以从任何地方运行它，无需指定路径

cli prompt Name? `git config user.name`

按名称运行任何类。

这对于在项目中对随机类对象进行ad hoc测试非常有用。它还可以自动为你添加项目的顶级命名空间。

cli MyClass
# Instead of
cli MyVendor\\MyProject\\MyClass

它是通过读取当前目录中的composer.json文件来做到这一点的。

如果类有一个带参数的构造函数，则会失败（我可能会在未来添加一种加载依赖关系的方式）。

运行其他shell命令。

这是passthru的包装，但，在失败时抛出异常。

CLI::passThru('sudo apt install php');

这提供了一种停止检查退出代码的简单方法。如果你想要处理它，可以捕获异常。

运行一系列shell命令。

运行多个passthru命令并返回true。如果其中任何一个失败，则会抛出异常。

CLI::batchPassThru(['sudo apt install php', 'sudo apt install composer']);

支持。

目前主要是支持我自己的使用，在业余时间更新这个项目。

在某个时候将需要更高的PHP版本，但我确实打算尝试在移至php8.1之后一段时间内单独支持php7.2和7.4。例如，如果我为7.2添加了一个新功能，我会在旧版本中添加一个较小的版本更新，仍然允许使用php7.2。（但无保证）

欢迎反馈和贡献。

我使用的是MIT许可，所以请随意做你想做的事，但我确实要求你在做出改进或修复任何错误时提交PR。

如果这个项目给你带来了1up🍄，你只想表达一些感激之情，那么：

请给我买杯咖啡。 ☕😃 捐赠