Utilities

The following utilities are available to assist with PHP Command Line programming

PHPUnit Color Display

PHPUnit Color Display provides static methods to flag warning, cautionary and OK status strings in PHPUnit test cases.

The Display class generates strings that create colored output that will work on virtually any terminal. It utilizes the escape coding that goes back to the days of the DEC VT-100. It can be used anywhere, but is geared toward displaying informative messages within PHPUnit test results.

It is a standalone static class with no dependencies and three simple static methods. Each method returns the generated string, making it easy to use it in two ways with PHPUnit:

Examples

The following code will create the output below:


    // echo out the escaped strings to create different levels of warnings
    echo Display::warning("Warning!");
    echo Display::caution("Caution...");
    echo Display::OK("OK to go!");

    // place the escaped string in the $message field to light up your output
    $this->assertSame("one","two",Display::caution("This assertion has intentionally failed"));
    

Installation

To install via Composer:

composer require --dev 1happyplace/phpunit-colors

Or if you are not using composer, you can download it on the GitHub Repository: 1HappyPlace/phpunit-colors.

PHPUnitColors Class

The Display class is a static class providing the capability to easily display warning, caution and OK status strings within PHPUnit Test Cases.

warning, caution, OK


There are three static functions in the Display class. They each return the incoming $text wrapped with the appropriate ANSI escape coding and an optional newline character.

static function warning($text, $newline = true)
static function caution($text, $newline = true)
static function OK($text, $newline = true)

Parameters
$text string The text to be wrapped with escape coding to display the text in red, yellow or green.
$newline boolean Whether to append a newline character which causes a carriage return

Color Test

ColorTest.php is a command line based PHP script which tests the color capabilities of a terminal emulator. It will send out three different escape sequence sets, pausing in between each one. You can then determine which standards are supported by whether the proper color spectrum is displayed.

Download the script and run it on the command line. It is standalone code with no dependencies.

php ColorTest.php

ANSI Escape Sequences

The oldest color terminal capability, which flashes back to the old VT terminals from Digital Equipment Corporation, are shown in the first two rows of colors.

The numbers shown in the boxes are the escape codes that will generate each background color. To generate that same color as a foreground color, subtract 10, e.g. bright cyan as a foreground would be 96.

These colors were selected primarily to get as much as possible out of the hardware capabilities of those wonderful old terminals. But it is not necessarily a good set for a cohesive user interface. But if it is all you have available, at least it is something.

ANSI colors are achieved by the following escape sequence:

echo "\e[Xm"

Xterm Sequences

Xterm colors are heavily used, and likely supported by most terminal emulators. There are 256 codes to choose from, which are shown in a grid of colors, each showing the code that generates it. Notice at the end, you also have a full spectrum of grays.

This color set has very little to do with color theory or an organized spectrum coverage. If you are looking for a specific color, the Clio software selects the closest Xterm color for each W3C color name.

Xterm colors are achieved by the following escape sequence. Foreground or background selection is dictated by the first number, shown below as 38. It is 38 for foreground and 48 for background.

echo "\e[38;5;Xm"

RGB Sequences

Lastly, and the one you want if you can get it, the full RGB. The terminal window of PHPStorm, for example, allows this escape sequencing giving you full control over your colors.

ColorTest.php shows a small portion of the RGB color spectrum. You will either see nothing or a gray square with no change in color if your terminal does not support this mode. If it does support RGB, you will see a subtle shift from green to red.

The escape sequence includes the Red, Green and Blue values (0-255). Foreground or background selection is dictated by the first number, shown below as 38. It is 38 for foreground and 48 for background.

echo "\e[38;2;R;G;Bm"