Class ConsoleIo

A wrapper around the various IO operations shell tasks need to do.

Packages up the stdout, stderr, and stdin streams providing a simple consistent interface for shells to use. This class also makes mocking streams easy to do in unit tests.

Namespace: Cake\Console

Constants

int

NORMAL ¶
```
1
```
Output constant for making normal shells.
int

QUIET ¶
```
0
```
Output constants for making quiet shells.
int

VERBOSE ¶
```
2
```
Output constant making verbose shells.

Property Summary

$_err protected

Cake\Console\ConsoleOutput

The error stream
$_helpers protected

Cake\Console\HelperRegistry

The helper registry.
$_in protected

Cake\Console\ConsoleInput

The input stream
$_lastWritten protected

int

The number of bytes last written to the output stream used when overwriting the previous message.
$_level protected

int

The current output level.
$_out protected

Cake\Console\ConsoleOutput

The output stream
$forceOverwrite protected

bool

Whether or not files should be overwritten
$interactive protected

bool

Method Summary

__construct() public

Constructor
_getInput() protected

Prompts the user for input, and returns it.
abort() public

Halts the the current process with a StopException.
ask() public

Prompts the user for input, and returns it.
askChoice() public

Prompts the user for input based on a list of options, and returns it.
createFile() public

Create a file at the given path.
err() public

Outputs a single or multiple error messages to stderr. If no parameters are passed outputs just a newline.
error() public

Convenience method for err() that wraps message between tag
getStyle() public

Get defined style.
helper() public

Render a Console Helper
hr() public

Outputs a series of minus characters to the standard output, acts as a visual separator.
info() public

Convenience method for out() that wraps message between tag
level() public

Get/set the current output level.
nl() public

Returns a single or multiple linefeeds sequences.
out() public

Outputs a single or multiple messages to stdout. If no parameters are passed outputs just a newline.
overwrite() public

Overwrite some already output text.
quiet() public

Output at all levels.
setInteractive() public
setLoggers() public

Connects or disconnects the loggers to the console output.
setOutputAs() public

Change the output mode of the stdout stream
setStyle() public

Adds a new output style.
styles() public

Gets defined styles.
success() public

Convenience method for out() that wraps message between tag
verbose() public

Output at the verbose level.
warning() public

Convenience method for err() that wraps message between tag
wrapMessageWithType() protected

Wraps a message with a given message type, e.g.

Method Detail

__construct() ¶ public

__construct(Cake\Console\ConsoleOutput|null $out = null, Cake\Console\ConsoleOutput|null $err = null, Cake\Console\ConsoleInput|null $in = null, Cake\Console\HelperRegistry|null $helpers = null)

Constructor

Parameters

Cake\Console\ConsoleOutput|null $out optional: A ConsoleOutput object for stdout.
Cake\Console\ConsoleOutput|null $err optional: A ConsoleOutput object for stderr.
Cake\Console\ConsoleInput|null $in optional: A ConsoleInput object for stdin.
Cake\Console\HelperRegistry|null $helpers optional: A HelperRegistry instance

_getInput() ¶ protected

_getInput(string $prompt, string|null $options, string|null $default): string

Prompts the user for input, and returns it.

Parameters

string $prompt: Prompt text.
string|null $options: String of options. Pass null to omit.
string|null $default: Default input value. Pass null to omit.

Returns

string

abort() ¶ public

abort(string $message, int $code = CommandInterface::CODE_ERROR): void

Halts the the current process with a StopException.

Parameters

string $message: Error message.
int $code optional: Error code.

Returns

void

Throws

Cake\Console\Exception\StopException

ask() ¶ public

ask(string $prompt, string|null $default = null): string

Prompts the user for input, and returns it.

Parameters

string $prompt: Prompt text.
string|null $default optional: Default input value.

Returns

string

askChoice() ¶ public

askChoice(string $prompt, string|array $options, string|null $default = null): string

Prompts the user for input based on a list of options, and returns it.

Parameters

string $prompt: Prompt text.
string|array $options: Array or string of options.
string|null $default optional: Default input value.

Returns

string

createFile() ¶ public

createFile(string $path, string $contents, bool $forceOverwrite = false): bool

Create a file at the given path.

This method will prompt the user if a file will be overwritten. Setting forceOverwrite to true will suppress this behavior and always overwrite the file.

If the user replies a subsequent forceOverwrite parameters will be coerced to true and all files will be overwritten.

Parameters

string $path: The path to create the file at.
string $contents: The contents to put into the file.
bool $forceOverwrite optional: Whether or not the file should be overwritten. If true, no question will be asked about whether or not to overwrite existing files.

Returns

bool

Throws

Cake\Console\Exception\StopException
When `q` is given as an answer to whether or not a file should be overwritten.

err() ¶ public

err(string|string[] $message = '', int $newlines = 1): int

Outputs a single or multiple error messages to stderr. If no parameters are passed outputs just a newline.

Parameters

string|string[] $message optional: A string or an array of strings to output
int $newlines optional: Number of newlines to append

Returns

int

error() ¶ public

error(string|string[] $message, int $newlines = 1): int

Convenience method for err() that wraps message between tag

Parameters

string|string[] $message: A string or an array of strings to output
int $newlines optional: Number of newlines to append

Returns

int

getStyle() ¶ public

getStyle(string $style): array

Get defined style.

Parameters

string $style: The style to get.

Returns

array

helper() ¶ public

helper(string $name, array $settings = []): Cake\Console\Helper

Render a Console Helper

Create and render the output for a helper object. If the helper object has not already been loaded, it will be loaded and constructed.

Parameters

string $name: The name of the helper to render
array $settings optional: Configuration data for the helper.

Returns

Cake\Console\Helper

hr() ¶ public

hr(int $newlines = 0, int $width = 79): void

Outputs a series of minus characters to the standard output, acts as a visual separator.

Parameters

int $newlines optional: Number of newlines to pre- and append
int $width optional: Width of the line, defaults to 79

Returns

void

info() ¶ public

info(string|string[] $message, int $newlines = 1, int $level = self::NORMAL): int|null

Convenience method for out() that wraps message between tag

Parameters

string|string[] $message: A string or an array of strings to output
int $newlines optional: Number of newlines to append
int $level optional: The message's output level, see above.

Returns

int|null

level() ¶ public

level(int|null $level = null): int

Get/set the current output level.

Parameters

int|null $level optional: The current output level.

Returns

int

nl() ¶ public

nl(int $multiplier = 1): string

Returns a single or multiple linefeeds sequences.

Parameters

int $multiplier optional: Number of times the linefeed sequence should be repeated

Returns

string

out() ¶ public

out(string|string[] $message = '', int $newlines = 1, int $level = self::NORMAL): int|null

Outputs a single or multiple messages to stdout. If no parameters are passed outputs just a newline.

Output levels

There are 3 built-in output level. ConsoleIo::QUIET, ConsoleIo::NORMAL, ConsoleIo::VERBOSE. The verbose and quiet output levels, map to the verbose and quiet output switches present in most shells. Using ConsoleIo::QUIET for a message means it will always display. While using ConsoleIo::VERBOSE means it will only display when verbose output is toggled.

Parameters

string|string[] $message optional: A string or an array of strings to output
int $newlines optional: Number of newlines to append
int $level optional: The message's output level, see above.

Returns

int|null

overwrite() ¶ public

overwrite(array|string $message, int $newlines = 1, int|null $size = null): void

Overwrite some already output text.

Useful for building progress bars, or when you want to replace text already output to the screen with new text.

Warning You cannot overwrite text that contains newlines.

Parameters

array|string $message: The message to output.
int $newlines optional: Number of newlines to append.
int|null $size optional: The number of bytes to overwrite. Defaults to the length of the last message output.

Returns

void

quiet() ¶ public

quiet(string|string[] $message, int $newlines = 1): int|null

Output at all levels.

Parameters

string|string[] $message: A string or an array of strings to output
int $newlines optional: Number of newlines to append

Returns

int|null

setInteractive() ¶ public

setInteractive(bool $value): void

Parameters

bool $value: Value

Returns

void

setLoggers() ¶ public

setLoggers(int|bool $enable): void

Connects or disconnects the loggers to the console output.

Used to enable or disable logging stream output to stdout and stderr If you don't wish all log output in stdout or stderr through Cake's Log class, call this function with $enable=false.

Parameters

int|bool $enable: Use a boolean to enable/toggle all logging. Use one of the verbosity constants (self::VERBOSE, self::QUIET, self::NORMAL) to control logging levels. VERBOSE enables debug logs, NORMAL does not include debug logs, QUIET disables notice, info and debug logs.

Returns

void

setOutputAs() ¶ public

setOutputAs(int $mode): void

Change the output mode of the stdout stream

Parameters

int $mode: The output mode.

Returns

void

setStyle() ¶ public

setStyle(string $style, array $definition): void

Adds a new output style.

Parameters

string $style: The style to set.
array $definition: The array definition of the style to change or create.

Returns

void

styles() ¶ public

styles(): array

Gets defined styles.

Returns

array

success() ¶ public

success(string|string[] $message, int $newlines = 1, int $level = self::NORMAL): int|null

Convenience method for out() that wraps message between tag

Parameters

string|string[] $message: A string or an array of strings to output
int $newlines optional: Number of newlines to append
int $level optional: The message's output level, see above.

Returns

int|null

verbose() ¶ public

verbose(string|string[] $message, int $newlines = 1): int|null

Output at the verbose level.

Parameters

string|string[] $message: A string or an array of strings to output
int $newlines optional: Number of newlines to append

Returns

int|null

warning() ¶ public

warning(string|string[] $message, int $newlines = 1): int

Convenience method for err() that wraps message between tag

Parameters

string|string[] $message: A string or an array of strings to output
int $newlines optional: Number of newlines to append

Returns

int

wrapMessageWithType() ¶ protected

wrapMessageWithType(string $messageType, string|string[] $message): string|string[]

Wraps a message with a given message type, e.g.

Parameters

string $messageType: The message type, e.g. "warning".
string|string[] $message: The message to wrap.

Returns

string|string[]

Property Detail

`$_err` ¶ protected

The error stream

Type

Cake\Console\ConsoleOutput

`$_helpers` ¶ protected

The helper registry.

Type

Cake\Console\HelperRegistry

`$_in` ¶ protected

The input stream

Type

Cake\Console\ConsoleInput

`$_lastWritten` ¶ protected

The number of bytes last written to the output stream used when overwriting the previous message.

Type

int

`$_level` ¶ protected

The current output level.

Type

int

`$_out` ¶ protected

The output stream

Type

Cake\Console\ConsoleOutput

`$forceOverwrite` ¶ protected

Whether or not files should be overwritten

Type

bool

`$interactive` ¶ protected

Type

bool

Namespaces

Class ConsoleIo

Constants

Property Summary

Method Summary

__construct() public

_getInput() protected

abort() public

ask() public

askChoice() public

createFile() public

err() public

error() public

getStyle() public

helper() public

hr() public

info() public

level() public

nl() public

out() public

overwrite() public

quiet() public

setInteractive() public

setLoggers() public

setOutputAs() public

setStyle() public

styles() public

success() public

verbose() public

warning() public

wrapMessageWithType() protected

Method Detail

__construct() ¶ public

Parameters

_getInput() ¶ protected

Parameters

Returns

abort() ¶ public

Parameters

Returns

Throws

ask() ¶ public

Parameters

Returns

askChoice() ¶ public

Parameters

Returns

createFile() ¶ public

Parameters

Returns

Throws

err() ¶ public

Parameters

Returns

error() ¶ public

Parameters

Returns

See Also

getStyle() ¶ public

Parameters

Returns

See Also

helper() ¶ public

Parameters

Returns

hr() ¶ public

Parameters

Returns

info() ¶ public

Parameters

Returns

See Also

level() ¶ public

Parameters

Returns

nl() ¶ public

Parameters

Returns

out() ¶ public

Output levels

`$_err` ¶ protected

`$_helpers` ¶ protected

`$_in` ¶ protected

`$_lastWritten` ¶ protected

`$_level` ¶ protected

`$_out` ¶ protected

`$forceOverwrite` ¶ protected

`$interactive` ¶ protected