BaseConsole

API reference › yii › helpers › BaseConsole

class	yii\helpers\BaseConsole
Since	2.0
Source	framework/helpers/BaseConsole.php

1 subclass

• Console

BaseConsole provides concrete implementation for Console.

Do not use BaseConsole. Use Console instead.

Methods

Method	Description	Defined by
ansiColorizedSubstr() static	Returns the portion with ANSI color codes of string specified by the start and length parameters.	BaseConsole
ansiFormat() static	Will return a string formatted with the given ANSI style.	BaseConsole
ansiFormatCode() static	Returns the ANSI format code.	BaseConsole
ansiStrlen() static	Returns the length of the string without ANSI color codes.	BaseConsole
ansiStrwidth() static	Returns the width of the string without ANSI color codes.	BaseConsole
ansiToHtml() static	Converts an ANSI formatted string to HTML.	BaseConsole
beginAnsiFormat() static	Echoes an ANSI format code that affects the formatting of any text that is printed afterwards.	BaseConsole
clearLine() static	Clears the line, the cursor is currently on by sending ANSI control code EL with argument 2 to the terminal.	BaseConsole
clearLineAfterCursor() static	Clears text from cursor position to the end of the line by sending ANSI control code EL with argument 0 to the terminal.	BaseConsole
clearLineBeforeCursor() static	Clears text from cursor position to the beginning of the line by sending ANSI control code EL with argument 1 to the terminal.	BaseConsole
clearScreen() static	Clears entire screen content by sending ANSI control code ED with argument 2 to the terminal.	BaseConsole
clearScreenAfterCursor() static	Clears text from cursor to the end of the screen by sending ANSI control code ED with argument 0 to the terminal.	BaseConsole
clearScreenBeforeCursor() static	Clears text from cursor to the beginning of the screen by sending ANSI control code ED with argument 1 to the terminal.	BaseConsole
confirm() static	Asks user to confirm by typing y or n.	BaseConsole
endAnsiFormat() static	Resets any ANSI format set by previous method beginAnsiFormat() Any output after this will have default text format.	BaseConsole
endProgress() static	Ends a progress bar that has been started by startProgress().	BaseConsole
error() static	Prints text to STDERR appended with a carriage return (PHP_EOL).	BaseConsole
errorSummary() static	Generates a summary of the validation errors.	BaseConsole
escape() static	Escapes % so they don’t get interpreted as color codes when the string is parsed by renderColoredString().	BaseConsole
getScreenSize() static	Returns terminal screen size.	BaseConsole
hideCursor() static	Hides the cursor by sending ANSI DECTCEM code ?25l to the terminal.	BaseConsole
input() static	Asks the user for input. Ends when the user types a carriage return (PHP_EOL). Optionally, It also provides a prompt.	BaseConsole
isRunningOnWindows() static	Returns true if the console is running on windows.	BaseConsole
markdownToAnsi() static	Converts Markdown to be better readable in console environments by applying some ANSI format.	BaseConsole
moveCursorBackward() static	Moves the terminal cursor backward by sending ANSI control code CUB to the terminal.	BaseConsole
moveCursorDown() static	Moves the terminal cursor down by sending ANSI control code CUD to the terminal.	BaseConsole
moveCursorForward() static	Moves the terminal cursor forward by sending ANSI control code CUF to the terminal.	BaseConsole
moveCursorNextLine() static	Moves the terminal cursor to the beginning of the next line by sending ANSI control code CNL to the terminal.	BaseConsole
moveCursorPrevLine() static	Moves the terminal cursor to the beginning of the previous line by sending ANSI control code CPL to the terminal.	BaseConsole
moveCursorTo() static	Moves the cursor to an absolute position given as column and row by sending ANSI control code CUP or CHA to the terminal.	BaseConsole
moveCursorUp() static	Moves the terminal cursor up by sending ANSI control code CUU to the terminal.	BaseConsole
output() static	Prints text to STDOUT appended with a carriage return (PHP_EOL).	BaseConsole
prompt() static	Prompts the user for input and validates it.	BaseConsole
renderColoredString() static	Converts a string to ansi formatted by replacing patterns like %y (for yellow) with ansi control codes.	BaseConsole
restoreCursorPosition() static	Restores the cursor position saved with saveCursorPosition() by sending ANSI control code RCP to the terminal.	BaseConsole
saveCursorPosition() static	Saves the current cursor position by sending ANSI control code SCP to the terminal.	BaseConsole
scrollDown() static	Scrolls whole page down by sending ANSI control code SD to the terminal.	BaseConsole
scrollUp() static	Scrolls whole page up by sending ANSI control code SU to the terminal.	BaseConsole
select() static	Gives the user an option to choose from. Giving ’?’ as an input will show a list of options to choose from and their explanations.	BaseConsole
showCursor() static	Will show a cursor again when it has been hidden by hideCursor() by sending ANSI DECTCEM code ?25h to the terminal.	BaseConsole
startProgress() static	Starts display of a progress bar on screen.	BaseConsole
stderr() static	Prints a string to STDERR.	BaseConsole
stdin() static	Gets input from STDIN and returns a string right-trimmed for EOLs.	BaseConsole
stdout() static	Prints a string to STDOUT.	BaseConsole
streamSupportsAnsiColors() static	Returns true if the stream supports colorization. ANSI colors are disabled if not supported by the stream.	BaseConsole
stripAnsiFormat() static	Strips ANSI control codes from a string.	BaseConsole
updateProgress() static	Updates a progress bar that has been started by startProgress().	BaseConsole
wrapText() static	Word wrap text with indentation to fit the screen size.	BaseConsole
xtermBgColor() static	Returns the ansi format code for xterm background color.	BaseConsole
xtermFgColor() static	Returns the ansi format code for xterm foreground color.	BaseConsole

Constants

Constant	Value	Description	Defined by
FG_BLACK	30		BaseConsole
FG_RED	31		BaseConsole
FG_GREEN	32		BaseConsole
FG_YELLOW	33		BaseConsole
FG_BLUE	34		BaseConsole
FG_PURPLE	35		BaseConsole
FG_CYAN	36		BaseConsole
FG_GREY	37		BaseConsole
BG_BLACK	40		BaseConsole
BG_RED	41		BaseConsole
BG_GREEN	42		BaseConsole
BG_YELLOW	43		BaseConsole
BG_BLUE	44		BaseConsole
BG_PURPLE	45		BaseConsole
BG_CYAN	46		BaseConsole
BG_GREY	47		BaseConsole
RESET	0		BaseConsole
NORMAL	0		BaseConsole
BOLD	1		BaseConsole
ITALIC	3		BaseConsole
UNDERLINE	4		BaseConsole
BLINK	5		BaseConsole
NEGATIVE	7		BaseConsole
CONCEALED	8		BaseConsole
CROSSED_OUT	9		BaseConsole
FRAMED	51		BaseConsole
ENCIRCLED	52		BaseConsole
OVERLINED	53		BaseConsole

Method details

ansiColorizedSubstr()

public static function ansiColorizedSubstr(string $string, int $start, int $length): string

Returns the portion with ANSI color codes of string specified by the start and length parameters.

If string has color codes, then will be return “TEXT_COLOR + TEXT_STRING + DEFAULT_COLOR”, else will be simple “TEXT_STRING”.

Parameters

Parameter	Type	Description
$string	string
$start	int
$length	int

Returns

string

ansiFormat()

public static function ansiFormat(string $string, array $format = []): string

Will return a string formatted with the given ANSI style.

Parameters

Parameter	Type	Description
$string	string	The string to be formatted
$format	array	An array containing formatting values. You can pass any of the FG_*, BG_* and TEXT_* constants and also xtermFgColor() and xtermBgColor() to specify a format.

Returns

string

ansiFormatCode()

public static function ansiFormatCode(array $format): string

Returns the ANSI format code.

Parameters

Parameter	Type	Description
$format	array	An array containing formatting values. You can pass any of the FG_*, BG_* and TEXT_* constants and also xtermFgColor() and xtermBgColor() to specify a format.

Returns

string: The ANSI format code according to the given formatting constants.

ansiStrlen()

public static function ansiStrlen(string $string): int

Returns the length of the string without ANSI color codes.

Parameters

Parameter	Type	Description
$string	string	The string to measure

Returns

int: The length of the string not counting ANSI format characters

ansiStrwidth()

public static function ansiStrwidth(string $string): int

Returns the width of the string without ANSI color codes.

Parameters

Parameter	Type	Description
$string	string	The string to measure

Returns

int: The width of the string not counting ANSI format characters

Since

2.0.36

ansiToHtml()

public static function ansiToHtml(string $string, array $styleMap = []): string

Converts an ANSI formatted string to HTML.

Note: xTerm 256 bit colors are currently not supported.

Parameters

Parameter	Type	Description
$string	string	The string to convert.
$styleMap	array	An optional mapping of ANSI control codes such as FG_COLOR or BOLD to a set of css style definitions. The CSS style definitions are represented as an array where the array keys correspond to the css style attribute names and the values are the css values. values may be arrays that will be merged and imploded with ' ' when rendered.

Returns

string: HTML representation of the ANSI formatted string

beginAnsiFormat()

public static function beginAnsiFormat(array $format): mixed

Echoes an ANSI format code that affects the formatting of any text that is printed afterwards.

Parameters

Parameter	Type	Description
$format	array	An array containing formatting values. You can pass any of the FG_*, BG_* and TEXT_* constants and also xtermFgColor() and xtermBgColor() to specify a format.

Returns

mixed

See also

• ansiFormatCode()
• endAnsiFormat()

clearLine()

public static function clearLine(): mixed

Clears the line, the cursor is currently on by sending ANSI control code EL with argument 2 to the terminal.

Cursor position will not be changed.

Returns

mixed

clearLineAfterCursor()

public static function clearLineAfterCursor(): mixed

Clears text from cursor position to the end of the line by sending ANSI control code EL with argument 0 to the terminal.

Cursor position will not be changed.

Returns

mixed

clearLineBeforeCursor()

public static function clearLineBeforeCursor(): mixed

Clears text from cursor position to the beginning of the line by sending ANSI control code EL with argument 1 to the terminal.

Cursor position will not be changed.

Returns

mixed

clearScreen()

public static function clearScreen(): mixed

Clears entire screen content by sending ANSI control code ED with argument 2 to the terminal.

Cursor position will not be changed. Note: ANSI.SYS implementation used in windows will reset cursor position to upper left corner of the screen.

Returns

mixed

clearScreenAfterCursor()

public static function clearScreenAfterCursor(): mixed

Clears text from cursor to the end of the screen by sending ANSI control code ED with argument 0 to the terminal.

Cursor position will not be changed.

Returns

mixed

clearScreenBeforeCursor()

public static function clearScreenBeforeCursor(): mixed

Clears text from cursor to the beginning of the screen by sending ANSI control code ED with argument 1 to the terminal.

Cursor position will not be changed.

Returns

mixed

confirm()

public static function confirm(string $message, bool $default = false): bool

Asks user to confirm by typing y or n.

A typical usage looks like the following:

if (Console::confirm("Are you sure?")) {
    echo "user typed yes\n";
} else {
    echo "user typed no\n";
}

Parameters

Parameter	Type	Description
$message	string	To print out before waiting for user input
$default	bool	This value is returned if no selection is made.

Returns

bool: Whether user confirmed

endAnsiFormat()

public static function endAnsiFormat(): mixed

Resets any ANSI format set by previous method beginAnsiFormat() Any output after this will have default text format.

This is equal to calling.

echo Console::ansiFormatCode([Console::RESET])

Returns

mixed

endProgress()

public static function endProgress(string|bool $remove = false, bool $keepPrefix = true): mixed

Ends a progress bar that has been started by startProgress().

Parameters

Parameter	Type	Description
$remove	string|bool	This can be false to leave the progress bar on screen and just print a newline. If set to true, the line of the progress bar will be cleared. This may also be a string to be displayed instead of the progress bar.
$keepPrefix	bool	Whether to keep the prefix that has been specified for the progressbar when progressbar gets removed. Defaults to true.

Returns

mixed

See also

• startProgress()
• updateProgress()

error()

public static function error(string|null $string = null): int|bool

Prints text to STDERR appended with a carriage return (PHP_EOL).

Parameters

Parameter	Type	Description
$string	string|null	The text to print

Returns

int|bool: Number of bytes printed or false on error.

errorSummary()

public static function errorSummary(yii\base\Model|yii\base\Model[] $models, array $options = []): string

Generates a summary of the validation errors.

Parameters

Parameter	Type	Description
$models	yii\base\Model|yii\base\Model[]	The model(s) whose validation errors are to be displayed.
$options	array	The tag options in terms of name-value pairs. The following options are specially handled: - showAllErrors: boolean, if set to true every error message for each attribute will be shown otherwise only the first error message for each attribute will be shown. Defaults to false.

Returns

string: The generated error summary

Since

2.0.14

escape()

public static function escape(string $string): string

Escapes % so they don’t get interpreted as color codes when the string is parsed by renderColoredString().

Parameters

Parameter	Type	Description
$string	string	String to escape

Returns

string

getScreenSize()

public static function getScreenSize(bool $refresh = false): array|bool

Returns terminal screen size.

Usage:

list($width, $height) = ConsoleHelper::getScreenSize();

Parameters

Parameter	Type	Description
$refresh	bool	Whether to force checking and not re-use cached size value. This is useful to detect changing window size while the application is running but may not get up to date values on every terminal.

Returns

array|bool: An array of ($width, $height) or false when it was not able to determine size.

hideCursor()

public static function hideCursor(): mixed

Hides the cursor by sending ANSI DECTCEM code ?25l to the terminal.

Use showCursor() to bring it back. Do not forget to show cursor when your application exits. Cursor might stay hidden in terminal after exit.

Returns

mixed

input()

public static function input(string|null $prompt = null): string

Asks the user for input. Ends when the user types a carriage return (PHP_EOL). Optionally, It also provides a prompt.

Parameters

Parameter	Type	Description
$prompt	string|null	The prompt to display before waiting for input (optional)

Returns

string: The user’s input

isRunningOnWindows()

public static function isRunningOnWindows(): bool

Returns true if the console is running on windows.

Returns

bool

markdownToAnsi()

public static function markdownToAnsi(string $markdown): string

Converts Markdown to be better readable in console environments by applying some ANSI format.

Parameters

Parameter	Type	Description
$markdown	string	The markdown string.

Returns

string: The parsed result as ANSI formatted string.

moveCursorBackward()

public static function moveCursorBackward(int $steps = 1): mixed

Moves the terminal cursor backward by sending ANSI control code CUB to the terminal.

If the cursor is already at the edge of the screen, this has no effect.

Parameters

Parameter	Type	Description
$steps	int	Number of steps the cursor should be moved backward

Returns

mixed

moveCursorDown()

public static function moveCursorDown(int $rows = 1): mixed

Moves the terminal cursor down by sending ANSI control code CUD to the terminal.

If the cursor is already at the edge of the screen, this has no effect.

Parameters

Parameter	Type	Description
$rows	int	Number of rows the cursor should be moved down

Returns

mixed

moveCursorForward()

public static function moveCursorForward(int $steps = 1): mixed

Moves the terminal cursor forward by sending ANSI control code CUF to the terminal.

If the cursor is already at the edge of the screen, this has no effect.

Parameters

Parameter	Type	Description
$steps	int	Number of steps the cursor should be moved forward

Returns

mixed

moveCursorNextLine()

public static function moveCursorNextLine(int $lines = 1): mixed

Moves the terminal cursor to the beginning of the next line by sending ANSI control code CNL to the terminal.

Parameters

Parameter	Type	Description
$lines	int	Number of lines the cursor should be moved down

Returns

mixed

moveCursorPrevLine()

public static function moveCursorPrevLine(int $lines = 1): mixed

Moves the terminal cursor to the beginning of the previous line by sending ANSI control code CPL to the terminal.

Parameters

Parameter	Type	Description
$lines	int	Number of lines the cursor should be moved up

Returns

mixed

moveCursorTo()

public static function moveCursorTo(int $column, int|null $row = null): mixed

Moves the cursor to an absolute position given as column and row by sending ANSI control code CUP or CHA to the terminal.

Parameters

Parameter	Type	Description
$column	int	1-based column number, 1 is the left edge of the screen.
$row	int|null	1-based row number, 1 is the top edge of the screen. if not set, will move cursor only in current line.

Returns

mixed

moveCursorUp()

public static function moveCursorUp(int $rows = 1): mixed

Moves the terminal cursor up by sending ANSI control code CUU to the terminal.

If the cursor is already at the edge of the screen, this has no effect.

Parameters

Parameter	Type	Description
$rows	int	Number of rows the cursor should be moved up

Returns

mixed

output()

public static function output(string|null $string = null): int|bool

Prints text to STDOUT appended with a carriage return (PHP_EOL).

Parameters

Parameter	Type	Description
$string	string|null	The text to print

Returns

int|bool: Number of bytes printed or false on error.

prompt()

public static function prompt(string $text, array $options = []): string

Prompts the user for input and validates it.

Parameters

Parameter	Type	Description
$text	string	Prompt string
$options	array	The options to validate the input: - required: whether it is required or not - default: default value if no input is inserted by the user - pattern: regular expression pattern to validate user input - validator: a callable function to validate input. The function must accept two parameters: - input: the user input to validate - error: the error value passed by reference if validation failed.

Returns

string: The user input

renderColoredString()

public static function renderColoredString(string $string, bool $colored = true): string

Converts a string to ansi formatted by replacing patterns like %y (for yellow) with ansi control codes.

Uses almost the same syntax as https://github.com/pear/Console_Color2/blob/master/Console/Color2.php The conversion table is: (‘bold’ meaning ‘light’ on some terminals). It’s almost the same conversion table irssi uses. <pre> text text background ------------------------------------------------ %k %K %0 black dark grey black %r %R %1 red bold red red %g %G %2 green bold green green %y %Y %3 yellow bold yellow yellow %b %B %4 blue bold blue blue %m %M %5 magenta bold magenta magenta %p %P magenta (think: purple) %c %C %6 cyan bold cyan cyan %w %W %7 white bold white white

 %F     Blinking, Flashing
 %U     Underline
 %8     Reverse
 %_,%9  Bold

 %n     Resets the color
 %%     A single %

</pre> First param is the string to convert, second is an optional flag if colors should be used. It defaults to true, if set to false, the color codes will just be removed (And %% will be transformed into %)

Parameters

Parameter	Type	Description
$string	string	String to convert
$colored	bool	Should the string be colored?

Returns

string

restoreCursorPosition()

public static function restoreCursorPosition(): mixed

Restores the cursor position saved with saveCursorPosition() by sending ANSI control code RCP to the terminal.

Returns

mixed

saveCursorPosition()

public static function saveCursorPosition(): mixed

Saves the current cursor position by sending ANSI control code SCP to the terminal.

Position can then be restored with restoreCursorPosition().

Returns

mixed

scrollDown()

public static function scrollDown(int $lines = 1): mixed

Scrolls whole page down by sending ANSI control code SD to the terminal.

New lines are added at the top. This is not supported by ANSI.SYS used in windows.

Parameters

Parameter	Type	Description
$lines	int	Number of lines to scroll down

Returns

mixed

scrollUp()

public static function scrollUp(int $lines = 1): mixed

Scrolls whole page up by sending ANSI control code SU to the terminal.

New lines are added at the bottom. This is not supported by ANSI.SYS used in windows.

Parameters

Parameter	Type	Description
$lines	int	Number of lines to scroll up

Returns

mixed

select()

public static function select(string $prompt, array $options = [], string|null $default = null): string

Gives the user an option to choose from. Giving ’?’ as an input will show a list of options to choose from and their explanations.

Parameters

Parameter	Type	Description
$prompt	string	The prompt message
$options	array	Key-value array of options to choose from. Key is what is inputed and used, value is what’s displayed to end user by help command.
$default	string|null	Value to use when the user doesn’t provide an option. If the default is null, the user is required to select an option.

Returns

string: An option character the user chose

showCursor()

public static function showCursor(): mixed

Will show a cursor again when it has been hidden by hideCursor() by sending ANSI DECTCEM code ?25h to the terminal.

Returns

mixed

startProgress()

public static function startProgress(int $done, int $total, string $prefix = '', int|float|bool|null $width = null): mixed

Starts display of a progress bar on screen.

This bar will be updated by updateProgress() and may be ended by endProgress().

The following example shows a simple usage of a progress bar:

Console::startProgress(0, 1000);
for ($n = 1; $n <= 1000; $n++) {
    usleep(1000);
    Console::updateProgress($n, 1000);
}
Console::endProgress();

Git clone like progress (showing only status information):

Console::startProgress(0, 1000, 'Counting objects: ', false);
for ($n = 1; $n <= 1000; $n++) {
    usleep(1000);
    Console::updateProgress($n, 1000);
}
Console::endProgress("done." . PHP_EOL);

Parameters

Parameter	Type	Description
$done	int	The number of items that are completed.
$total	int	The total value of items that are to be done.
$prefix	string	An optional string to display before the progress bar. Default to empty string which results in no prefix to be displayed.
$width	int|float|bool|null	Optional width of the progressbar. This can be an integer representing the number of characters to display for the progress bar or a float between 0 and 1 representing the percentage of screen with the progress bar may take. It can also be set to false to disable the bar and only show progress information like percent, number of items and ETA. If not set, the bar will be as wide as the screen. Screen size will be detected using getScreenSize().

Returns

mixed

See also

• startProgress()
• updateProgress()
• endProgress()

stderr()

public static function stderr(string $string): int|bool

Prints a string to STDERR.

Parameters

Parameter	Type	Description
$string	string	The string to print

Returns

int|bool: Number of bytes printed or false on error

stdin()

public static function stdin(bool $raw = false): string

Gets input from STDIN and returns a string right-trimmed for EOLs.

Parameters

Parameter	Type	Description
$raw	bool	If set to true, returns the raw string without trimming

Returns

string: The string read from stdin

stdout()

public static function stdout(string $string): int|bool

Prints a string to STDOUT.

Parameters

Parameter	Type	Description
$string	string	The string to print

Returns

int|bool: Number of bytes printed or false on error

streamSupportsAnsiColors()

public static function streamSupportsAnsiColors(mixed $stream): bool

Returns true if the stream supports colorization. ANSI colors are disabled if not supported by the stream.

• windows without ansicon
• not tty consoles

Parameters

Parameter	Type	Description
$stream	mixed

Returns

bool: True if the stream supports ANSI colors, otherwise false.

stripAnsiFormat()

public static function stripAnsiFormat(string $string): string

Strips ANSI control codes from a string.

Parameters

Parameter	Type	Description
$string	string	String to strip

Returns

string

updateProgress()

public static function updateProgress(int $done, int $total, string|null $prefix = null): mixed

Updates a progress bar that has been started by startProgress().

Parameters

Parameter	Type	Description
$done	int	The number of items that are completed.
$total	int	The total value of items that are to be done.
$prefix	string|null	An optional string to display before the progress bar. Defaults to null meaning the prefix specified by startProgress() will be used. If prefix is specified it will update the prefix that will be used by later calls.

Returns

mixed

See also

• startProgress()
• endProgress()

wrapText()

public static function wrapText(string $text, int $indent = 0, bool $refresh = false): string

Word wrap text with indentation to fit the screen size.

If screen size could not be detected, or the indentation is greater than the screen size, the text will not be wrapped.

The first line will not be indented, so Console::wrapText("Lorem ipsum dolor sit amet.", 4) will result in the following output, given the screen width is 16 characters:

Lorem ipsum
    dolor sit
    amet.

Parameters

Parameter	Type	Description
$text	string	The text to be wrapped
$indent	int	Number of spaces to use for indentation.
$refresh	bool	Whether to force refresh of screen size. This will be passed to getScreenSize().

Returns

string: The wrapped text.

Since

2.0.4

xtermBgColor()

public static function xtermBgColor(int $colorCode): string

Returns the ansi format code for xterm background color.

You can pass the return value of this to one of the formatting methods: ansiFormat(), ansiFormatCode(), beginAnsiFormat().

Parameters

Parameter	Type	Description
$colorCode	int	Xterm color code

Returns

string

See also

• https://en.wikipedia.org/wiki/Talk:ANSI_escape_code#xterm-256colors

xtermFgColor()

public static function xtermFgColor(int $colorCode): string

Returns the ansi format code for xterm foreground color.

You can pass the return value of this to one of the formatting methods: ansiFormat(), ansiFormatCode(), beginAnsiFormat().

Parameters

Parameter	Type	Description
$colorCode	int	Xterm color code

Returns

string

See also

• https://en.wikipedia.org/wiki/Talk:ANSI_escape_code#xterm-256colors