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::RGB - This is less common, but gives you the full RGB color spectrum, currently the PHPStorm console window does support RGB
- Clio::XTERM - This is the most common capability, giving you 256 colors
- Clio::VT100 - This is supported everywhere, but giving you only 16 somewhat randomly selected colors (that worked well with 1980's hardware)
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 | ||
---|---|---|
Name | Type | Description |
$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 | ||
---|---|---|
Name | Type | Description |
$text | String | The text to display on the terminal. |
line
Display the text and hit a carriage return.
line($text)
Parameters | ||
---|---|---|
Name | Type | Description |
$text | string | The text to display. |
newLine, nl, out
Hit the carriage return $count times.
newLine($count = 1)
Parameters | ||
---|---|---|
Name | Type | Description |
$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 | ||
---|---|---|
Name | Type | Description |
$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 | ||
---|---|---|
Name | Type | Description |
$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 | ||
---|---|---|
Name | Type | Description |
$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 | ||
---|---|---|
Name | Type | Description |
$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 | ||
---|---|---|
Name | Type | Description |
$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 | ||
---|---|---|
Name | Type | Description |
$on | boolean | Start or stop bolding text. |
setUnderscore, u
Either start or stop underscoring text.
u($on = true)
Parameters | ||
---|---|---|
Name | Type | Description |
$on | boolean | Start or stop underscoring text. |
textColor, setTextColor
Start drawing text in a particular color.
textColor($color = null)
Parameters | ||
---|---|---|
Name | Type | Description |
$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 | ||
---|---|---|
Name | Type | Description |
$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 | ||
---|---|---|
Name | Type | Description |
$textColor | Any valid Color constructor initial value | The color to use. |
$fillColor | Any valid Color constructor initial value | The color to use. |