Clio

Clio is an easy to use PHP class for styling PHP CLI programs. In general, you will want to create one Clio instance to represent the terminal in which it is controlling.

Clio will send out the appropriate escape sequencing (depending on the mode) to achieve the text display you are requiring. If you are specifying RGB colors, but have to deal with a terminal capability of less colors, Clio utilizes the Color object to get as close as possible to that color.

Modes

One of the important selections you must make is the terminal mode. This dictates the kind of escape programming that will be used behind the scenes, as well as the number of colors that are available. If you are working on a specific terminal, you can run the Color Test GitHub project to see the capability of your terminal. It is the only accurate way to determine the color mode of your terminal, as terminal modes and what they mean are notoriously inconsistent. They best way to know whether you can generate RGB colors is to try it on the emulator directly.

There are three Clio modes:

Clio::XTERM is the default mode.

Software Documentation

Clio inherits the methods of the Terminal Class located in the ANSI Terminal GitHub project in which it depends. Clio inherits the Terminal Class directly, so some of these methods come from that class.

Since there is a fair number of methods, they have been grouped as follows:

Layout Methods

Constructor


Construct a clio object, set the mode to match the capabilities of your terminal. Set the default text and fill for the colors that should be the basic foreground and background, generally black text with white background, or cyan or green text with a black background, but can be whatever you want. Use the default of null if you want the terminal's default colors to stay as is.

The Clio class is a child of the Terminal Class.

__construct($mode = self::XTERM, $defaultTextColor = null, $defaultFillColor = null)

Parameters
NameTypeDescription
$mode Mode::VT100
Mode::XTERM
Mode::RGB, or string equivalent "xterm", "VT100", etc
Sets the escape sequencing method, VT100 provides 16 colors, XTERM provides 255 and RGB provides them all.
$defaultTextColor Any valid Color constructor initial value The base text color
$defaultFillColor Any valid Color constructor initial value The base fill color

display


Display the text in whatever styling has been set.

display($text)

Parameters
NameTypeDescription
$text String The text to display on the terminal.

line


Display the text and hit a carriage return.

line($text)

Parameters
NameTypeDescription
$text string The text to display.

newLine, nl, out


Hit the carriage return $count times.

newLine($count = 1)

Parameters
NameTypeDescription
$count integer The number of lines to jump down.

clearScreen


Clear the screen and move cursor to the top.

clearScreen()

Prompt Methods

prompt


Prompt the user. If a default is supplied, it will return null if the default was selected, either by hitting the carriage return or typing the default as an answer.

[string] prompt($text, $default = null)

Parameters
NameTypeDescription
$text string The beginning of the prompt
$default string | null The default answer.

pause


Shortcut function to pause execution until the user hits return

pause()

promptForYes


Runs the prompt method, appending (y/n) to the prompt. It is looking for an answer of "y", "ye" or "yes" (any capitalization) for confirmation.

[string] promptForYes($text)

Parameters
NameTypeDescription
$text string The beginning of the prompt

promptSelect


Runs the prompt method. It then provides the choices in a comma delimited list. It will highlight the characters needed for uniqueness. If the default is given and answered, null is returned.

[string] promptSelect($intro, $choices, $default = null)

Parameters
NameTypeDescription
$text string The beginning of the prompt
$choices string[] The list of available choices (one must be entered)
$default string | null The default answer.

Styling Methods

setStyle, style


Set the bold, underscore, text and fill colors based on a Style object.

setStyle(StyleInterface $style)

Parameters
NameTypeDescription
$style StyleInterface The style to use.

clear


Clear out the current styling. The text and fill will be set to the default colors set it in the constructor (or cleared out if no default is defined).

Clio doesn't actually send out the escape coding for styling until text is output, but if you need for the clear to go out right away (such as the end of a command line program), then set the $rightAway parameter to true. If not, it will be done during the next output (and combined with any subsequent styling you specify).

clear($rightAway = false)

Parameters
NameTypeDescription
$rightAway boolean Send out the clear sequence right away \e[0m

Typography Methods

setBold, b


Either start or stop bolding text.

b($on = true)

Parameters
NameTypeDescription
$on boolean Start or stop bolding text.

setUnderscore, u


Either start or stop underscoring text.

u($on = true)

Parameters
NameTypeDescription
$on boolean Start or stop underscoring text.

textColor, setTextColor


Start drawing text in a particular color.

textColor($color = null)

Parameters
NameTypeDescription
$color Any valid Color constructor initial value The color to use.

clearTextColor


Rest back to default text color (if one is specified).

clearTextColor()

fillColor, setFillColor


Start drawing fill (background) in a particular color.

fillColor($color = null)

Parameters
NameTypeDescription
$color Any valid Color constructor initial value The color to use.

clearFillColor


Reset back to default fill color (if one is specified).

clearTextColor()

colors


Start drawing text and fill in specified colors.

colors($textColor = null, $fillColor = null)

Parameters
NameTypeDescription
$textColor Any valid Color constructor initial value The color to use.
$fillColor Any valid Color constructor initial value The color to use.