cspray / labrador-styled-byte-stream
Create colorized and formatted terminal text with Amp's OutputStream!
Requires
- php: ^8.0
- amphp/byte-stream: ^v2.0
Requires (Dev)
- phpunit/phpunit: ^9.6
- roave/security-advisories: dev-latest
This package is auto-updated.
Last update: 2024-10-25 16:28:45 UTC
README
A library for printing rich output to a terminal using amphp/byte-stream!
- Supports default foreground and background colors
- black
- blue
- cyan
- green
- magenta
- red
- white
- yellow
- Supports default formatting options
- bold
- underline
- reverse
- conceal
- Other helper methods designed to make terminal output easy to create
- An immutable fluent API for creating OutputStream with a specific style
Installation
Composer is the only supported way to install Styled ByteStream
composer require cspray/labrador-styled-byte-stream
Documentation
Styled ByteStream provides a single Amp\ByteStream\OutputStream
decorator; the Cspray\Labrador\StyledByteStream\TerminalOutputStream
.
This object provides an API for creating rich terminal output. This includes outputting content with new lines, changing
the color of the text, and/or adding formatting options. All of these methods can be chained together to come up with
exactly the right style of content for your Amp powered CLI app.
All examples below assume to be running in the following boilerplate:
<?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
Write with new line
The writeln(string $text)
method writes some text to the decorated OutputStream
and appends a PHP_EOL
on the end.
$stream->writeln('This is content on a new line');
Add multiple line breaks
The br(int $count = 1)
method will write $count
number of PHP_EOL
to the decorated OutputStream
.
$stream->br(3); // adds 3 new lines to the terminal output
Background Colors
For every supported color there is a corresponding background method. For example, backgroundBlack()
, blackgroundBlue()
, etc.
These methods output text with the appropriate background.
$stream->backgroundBlue('This has a blue background'); $stream->backgroundYellow('This has a yellow background');
Foreground Colors
Every supported color is also a method that allows setting the foreground color. For example, black()
, blue
, etc.
These methods output text with the appropriate text color.
$stream->magenta('This is magenta text'); $stream->cyan('This is cyan text');
Formatting Options
Every supported formatting option is also a method that allows changing the way the output text is displayed. For example,
bold()
, underline()
, etc. These methods output text with the appropriate formatting.
$stream->bold('This is bolded text'); $stream->underline('This text has an underline');
Chaining styles
All color and formatting options can be chained together to compose exactly the style you need.
$stream->backgroundWhite()->red('This has a white background and red text'); $stream->bold()->yellow()->underline()->backgroundRed('The order of the chaining does not matter');
Chaining styles and new lines
By default, the color and formatting options will append a new line to the end of any text passed to them. Bypass this
default behavior by chaining the inline()
method. The inline()
method can only be chained, text cannot be passed to
this method.
$stream->inline()->bold()->red('This is inline bold red text'); $stream->bold()->red('... This is text with a new line at the end');
Alternatively, skip over automatically appended lines by chaining to the write
method.
$stream->bold()->red()->write('I am bold red inline text too!');
It is possible to force new lines... even if the write
method is being used. Control the number of new lines by
passing an int
to the forceNewline()
method. The forceNewline
method can only be chained, text cannot be passed to
this method.
$stream->bold()->red()->forceNewline(2)->write('I am bold red text with 2 new lines at the end');
Using Immutability
Chaining method calls is a straightforward approach for outputting rich text. It is important to realize that the
TerminalOutputStream
is an immutable object; each call to a color or formatting option will create a new instance with
the defined formatting. This design can be taken advantage of to quickly compose reusable "styles" and have dependencies
only be aware of the underlying Amp\ByteStream\OutputStream
interface.
Let's assume that an implementation similar to the following is provided. Our fictional application will run a series of reports that can be of a state successful, failed, or disabled. The CLI application running the reports should print out a summary of which reports were processed and style the reports differently based on its state.
The below code examples are standalone and not intended to run in the example boilerplate
<?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'); }); } }
Use TerminalOutputStream
to create decorated OutputStream
so the ReportSummaryPrinter
is not complicated with
styling logic or knowledge of the TerminalOutputStream
. Later on if a different OutputStream
is required, for example
to write the summary to a file, it will only be necessary to swap out the implementations.
<?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...']);
This is a working example! If you clone the repo and run
php examples/report-summary-printer.php
you'll see the expected output in your terminal!
Governance
All Labrador packages adhere to the rules laid out in the Labrador Governance repo