README

PHP 命令行界面 (CLI) 打印消息的库。可选支持 Monolog\Logger。

在开发或测试环境中，您可以通过定义名为 DISABLE_CONSOLE_PRINTING 的常量来禁用控制台消息输出。

需求
安装
可用类
- CliPrinter 类
- 颜色类
用法
测试
待办事项
变更日志
贡献
赞助
许可

需求

操作系统：Linux。
PHP 版本：8.1 | 8.2。

安装

安装此扩展的首选方式是通过 Composer。

要安装 PHP CliPrinter 库，只需

composer require josantonius/cli-printer

前面的命令只会安装必要的文件，如果您更喜欢 下载整个源代码，您可以使用

composer require josantonius/cli-printer --prefer-source

您还可以使用 Git 克隆整个仓库

git clone https://github.com/josantonius/php-cli-printer.git

可用类

CliPrinter 类

Josantonius\CliPrinter\CliPrinter

创建新实例

/**
 * @param array $messages The messages to be printed, in the format ['id' => 'message'].
 */
public function __construct(protected array $messages = []);

在控制台上显示一条消息

/**
 * Formatter: The $message and $params work in a similar way as the sprintf method:
 *            display('tag', 'The %s %d', ['message', 8]).
 *
 * Messages:  If $messages was provided, the message can be replaced by the ID:
 *            display('tag', 'user.error').
 *
 * Logger:    If used and the tag name of the message matches a level,
 *            it shall be used when adding the record. Otherwise use the debug level.
 *
 * @param string $tagName Message tag name.
 * @param string $message The message or message ID.
 * @param array  $params  Additional context for format $message or/and passing it to the log.
 */
public function display(string $tagName, string $message, array $params = []): self;

使用消息标签作为方法名动态显示一条消息

/**
 * @param string $tagName   Message tag name.
 * @param string $arguments The first value is the message and the second the parameters.
 */
public function __call(string $tagName, array $arguments): self;

添加 Monolog\Logger 的实例以为显示的每条消息添加日志

/**
 * @param Logger $logger Instance of the Logger class.
 */
public function useLogger(Logger $logger): self;

在控制台上打印新行

/**
 * @param int $times Number of new lines to print.
 */
public function newLine(int $times = 1): self;

设置消息前后换行的数量

/**
 * @param int $before Number of line breaks before a message.
 * @param int $after  Number of line breaks after a message.
 */
public function setLineBreaks(int $before, int $after): self;

设置消息标签的默认颜色

/**
 * @param Color $color Default message tag color.
 */
public function setDefaultTagColor(Color $color): self;

设置消息标签的颜色

/**
 * @param string $tagName  Message tag name.
 * @param Color  $tagColor Message tag color.
 */
public function setTagColor(string $tagName, Color $tagColor): self;

颜色类

Josantonius\CliPrinter\Color

可用颜色

enum Color: int
{
    case BLACK  = 40;
    case RED    = 41;
    case GREEN  = 42;
    case YELLOW = 43;
    case BLUE   = 44;
    case PURPLE = 45;
    case CYAN   = 46;
    case WHITE  = 47;
}

用法

此库的使用示例

显示消息

use Josantonius\CliPrinter\CliPrinter;

$printer = new CliPrinter();

$printer->display('alert', 'An alert message.');
$printer->display('error', 'An error message.');

显示不带标签的消息

use Josantonius\CliPrinter\CliPrinter;

$printer = new CliPrinter();

$printer->display('', 'A message without a tag.');

通过其键显示预置消息

use Josantonius\CliPrinter\CliPrinter;

$printer = new CliPrinter([
    'user.created' => 'User created.',
    'user.changed' => 'User changed.',
]);

$printer->display('create', 'user.created');
$printer->display('change', 'user.changed');

显示格式化消息

use Josantonius\CliPrinter\CliPrinter;

$printer = new CliPrinter([
    'msg.notice' => 'A %s message.',
]);

$printer->display('notice', 'msg.notice', ['notice']);

$printer->display('detail', 'A %s message.', ['detail']);

更改每条消息前后的换行数

use Josantonius\CliPrinter\CliPrinter;

$printer = new CliPrinter();

$printer->setLineBreaks(before: 1, after: 0);

$printer->display('alert', 'Alert message.');
$printer->display('error', 'Error message.');

use Josantonius\CliPrinter\CliPrinter;

$printer = new CliPrinter();

$printer->setLineBreaks(before: 2, after: 1);

$printer->display('alert', 'Alert message.');
$printer->display('error', 'Error message.');

添加额外的换行

use Josantonius\CliPrinter\CliPrinter;

$printer = new CliPrinter();

$printer->display('request', 'Message.');

$printer->newLine();
$printer->display('response', 'Message.');
$printer->newLine(times: 3);

$printer->display('warning', 'Message.');

更改标签的默认颜色

use Josantonius\CliPrinter\Color;
use Josantonius\CliPrinter\CliPrinter;

$printer = new CliPrinter();

$printer->setDefaultTagColor(Color::PURPLE);

$printer->display('alert', 'An alert message.');
$printer->display('error', 'An error message.');

为每个标签设置自定义颜色

use Josantonius\CliPrinter\Color;
use Josantonius\CliPrinter\CliPrinter;

$printer = new CliPrinter();

$printer->setTagColor('info',      Color::BLUE)
        ->setTagColor('alert',     Color::BLACK)
        ->setTagColor('error',     Color::RED)
        ->setTagColor('debug',     Color::GREEN)
        ->setTagColor('notice',    Color::CYAN)
        ->setTagColor('warning',   Color::YELLOW)
        ->setTagColor('critical',  Color::PURPLE)
        ->setTagColor('emergency', Color::WHITE);

$printer->display('info',      'A message.');
$printer->display('alert',     'A message.');
$printer->display('error',     'A message.');
$printer->display('debug',     'A message.');
$printer->display('notice',    'A message.');
$printer->display('warning',   'A message.');
$printer->display('critical',  'A message.');
$printer->display('emergency', 'A message.');

使用动态方法显示消息

use Josantonius\CliPrinter\CliPrinter;

$printer = new CliPrinter();

$printer->request('A request message.');

$printer->response('A %s message.', ['response']);

使用 Monolog\Logger

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Josantonius\CliPrinter\CliPrinter;

$logger  = new Logger('LOG');
$logger->pushHandler(new StreamHandler(__DIR__ . '/log.txt'));

$printer = new CliPrinter();
$printer->useLogger($logger);

/**
 * It will create a "notice" log.
 * 
 * [2023-01-13T19:50:47.954791+00:00] LOG.NOTICE: A notice message. {"foo":"bar"} []
 */
$printer->display('notice', 'A notice message.', ['foo' => 'bar']);

/**
 * It will create a "debug" log as there is no "create" level.
 * 
 * [2023-01-13T19:50:47.954319+00:00] LOG.DEBUG: A create message. ["create"] []
 */
$printer->display('create', 'A %s message.', ['create']);

测试

要运行测试，您只需要 composer 并执行以下操作

git clone https://github.com/josantonius/php-cli-printer.git

cd php-cli-printer

composer install

使用 PHPUnit 运行单元测试

composer phpunit

使用 PHPCS 运行代码标准测试

composer phpcs

运行 PHP Mess Detector 测试以检测代码风格的冲突

composer phpmd

运行所有之前的测试

composer tests

待办事项

添加新功能
改进测试
改进文档
改进 README 文件中的英文翻译
重构代码以禁用禁用代码风格规则（请参阅 phpmd.xml 和 phpcs.xml）

变更日志

每个版本的详细更改记录在发行说明中。

贡献

请在提交拉取请求、开始讨论或报告问题之前，确保阅读贡献指南。

感谢所有贡献者！❤️

赞助

如果这个项目帮助您减少了开发时间，您可以赞助我来支持我的开源工作 😊

许可

本仓库遵循MIT许可证。

josantonius / cli-printer

维护者

详细信息