README

一个库，用于使用amphp/byte-stream将丰富输出打印到终端！

• 支持默认的前景色和背景色
  • 黑色
  • 蓝色
  • 青色
  • 绿色
  • 品红色
  • 红色
  • 白色
  • 黄色
• 支持默认的格式化选项
  • 粗体
  • 下划线
  • 反色
  • 隐藏
• 其他辅助方法，旨在使终端输出易于创建
• 用于创建具有特定样式的OutputStream的不可变流畅API

安装

Composer是安装Styled ByteStream的唯一支持方式Composer

composer require cspray/labrador-styled-byte-stream

文档

Styled ByteStream提供了一个单一的Amp\ByteStream\OutputStream装饰器；即Cspray\Labrador\StyledByteStream\TerminalOutputStream。此对象提供创建丰富终端输出的API。这包括输出带有换行符的内容、更改文本颜色和/或添加格式化选项。所有这些方法都可以链接在一起，为您的Amp CLI应用程序提供恰好合适的内容样式。

以下所有示例都假设在以下样板代码中运行

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Amp\Loop;
use Cspray\Labrador\StyledByteStream\TerminalOutputStream;
use function Amp\ByteStream\getStdout;

$stream = new TerminalOutputStream(getStdout());

// The example code is expected to be executed here

写入带换行符

writeln(string $text)方法将一些文本写入装饰的OutputStream并在末尾附加一个PHP_EOL。

$stream->writeln('This is content on a new line');

添加多个换行符

br(int $count = 1)方法将在装饰的OutputStream中写入$count个PHP_EOL。

$stream->br(3); // adds 3 new lines to the terminal output

背景颜色

对于每个支持的颜色，都有一个相应的背景方法。例如，backgroundBlack()，backgroundBlue()等。这些方法输出具有适当背景的文本。

$stream->backgroundBlue('This has a blue background');
$stream->backgroundYellow('This has a yellow background');

前景颜色

每个支持的颜色也是允许设置前景颜色的方法。例如，black()，blue()等。这些方法输出具有适当文本颜色的文本。

$stream->magenta('This is magenta text');
$stream->cyan('This is cyan text');

格式化选项

每个支持格式化选项也是允许更改输出文本显示方式的方法。例如，bold()，underline()等。这些方法输出具有适当格式的文本。

$stream->bold('This is bolded text');
$stream->underline('This text has an underline');

链式样式

所有颜色和格式化选项都可以链接在一起以创建所需的样式。

$stream->backgroundWhite()->red('This has a white background and red text');
$stream->bold()->yellow()->underline()->backgroundRed('The order of the chaining does not matter');

链式样式和换行符

默认情况下，颜色和格式化选项将在传递给它们的任何文本末尾附加换行符。通过链式调用inline()方法绕过此默认行为。由于inline()方法只能链式调用，因此不能向此方法传递文本。

$stream->inline()->bold()->red('This is inline bold red text');
$stream->bold()->red('... This is text with a new line at the end');

或者，通过链式调用到write方法来跳过自动附加的行。

$stream->bold()->red()->write('I am bold red inline text too!');

即使使用write方法，也可以强制换行...即使使用write方法。通过将int传递给forceNewline()方法来控制换行符的数量。forceNewline方法只能链式调用，不能向此方法传递文本。

$stream->bold()->red()->forceNewline(2)->write('I am bold red text with 2 new lines at the end');

使用不可变性

链式调用方法是一个输出丰富文本的直接方法。重要的是要认识到，TerminalOutputStream是一个不可变对象；对颜色或格式化选项的每个调用都将创建一个新的具有定义格式的实例。可以利用这种设计快速组合可重用的“样式”，并使依赖项仅了解底层的Amp\ByteStream\OutputStream接口。

假设提供了以下类似的实现。我们的虚构应用程序将运行一系列报告，这些报告可以是成功、失败或禁用的状态。运行报告的CLI应用程序应该打印出已处理的报告摘要，并根据其状态以不同的方式格式化报告。

以下代码示例是独立的，不打算在示例模板中运行。

<?php

use Amp\ByteStream\OutputStream;
use Amp\Promise;use function Amp\call;

class ReportSummaryPrinter {

    public function __construct(private OutputStream $output) {}

    public function writeReportResults(array $report) : Promise {
        return call(function() use($report) {
            $this->output->write($report['name'] . ' received');
        });    
    }

}

使用TerminalOutputStream创建装饰性的OutputStream，这样ReportSummaryPrinter就不会被样式逻辑或对TerminalOutputStream的了解所复杂化。稍后如果需要不同的OutputStream，例如将摘要写入文件，只需交换实现即可。

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Cspray\Labrador\StyledByteStream\TerminalOutputStream;
use function Amp\ByteStream\getStdout;

$stream = new TerminalOutputStream(getStdout());

$successfulReportOutput = $stream->forceNewline()->green();
$failedReportOutput = $stream->forceNewline()->backgroundRed()->white()->bold();
$disabledReportOutput = $stream->forceNewline()->yellow()->underline();

$successfulReportPrinter = new ReportSummaryPrinter($successfulReportOutput);
$failedReportPrinter = new ReportSummaryPrinter($failedReportOutput);
$disabledReportPrinter = new ReportSummaryPrinter($disabledReportOutput);

$successfulReportPrinter->writeReportResults(['name' => 'Foo Bar Report']);
$failedReportPrinter->writeReportResults(['name' => 'A failed report!']);
$disabledReportPrinter->writeReportResults(['name' => 'We never ran this report...']);

这是一个有效示例！如果您克隆存储库并运行php examples/report-summary-printer.php，您将在终端看到预期的输出！

治理

所有Labrador包都遵循在Labrador Governance存储库中规定的规则。