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.
Constants
Property Summary
-
$_err protected
Cake\Console\ConsoleOutputThe error stream
-
$_helpers protected
Cake\Console\HelperRegistryThe helper registry.
-
$_in protected
Cake\Console\ConsoleInputThe input stream
-
$_lastWritten protected
intThe number of bytes last written to the output stream used when overwriting the previous message.
-
$_level protected
intThe current output level.
-
$_out protected
Cake\Console\ConsoleOutputThe output stream
-
$forceOverwrite protected
boolWhether 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.
-
comment() public
Convenience method for out() that wraps message between
tag -
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): stringPrompts 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
stringabort() ¶ public
abort(string $message, int $code = CommandInterface::CODE_ERROR): neverHalts the the current process with a StopException.
Parameters
-
string$message Error message.
-
int$code optional Error code.
Returns
neverThrows
Cake\Console\Exception\StopExceptionask() ¶ public
ask(string $prompt, string|null $default = null): stringPrompts the user for input, and returns it.
Parameters
-
string$prompt Prompt text.
-
string|null$default optional Default input value.
Returns
stringaskChoice() ¶ public
askChoice(string $prompt, array<string>|string $options, string|null $default = null): stringPrompts the user for input based on a list of options, and returns it.
Parameters
-
string$prompt Prompt text.
-
array<string>|string$options Array or string of options.
-
string|null$default optional Default input value.
Returns
stringcomment() ¶ public
comment(array<string>|string $message, int $newlines = 1, int $level = self::NORMAL): int|nullConvenience method for out() that wraps message between
Parameters
-
array<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|nullSee Also
createFile() ¶ public
createFile(string $path, string $contents, bool $forceOverwrite = false): boolCreate 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 the file should be overwritten. If true, no question will be asked about whether to overwrite existing files.
Returns
boolThrows
Cake\Console\Exception\StopExceptionWhen `q` is given as an answer to whether a file should be overwritten.
err() ¶ public
err(array<string>|string $message = '', int $newlines = 1): intOutputs a single or multiple error messages to stderr. If no parameters are passed outputs just a newline.
Parameters
-
array<string>|string$message optional A string or an array of strings to output
-
int$newlines optional Number of newlines to append
Returns
interror() ¶ public
error(array<string>|string $message, int $newlines = 1): intConvenience method for err() that wraps message between
Parameters
-
array<string>|string$message A string or an array of strings to output
-
int$newlines optional Number of newlines to append
Returns
intSee Also
getStyle() ¶ public
getStyle(string $style): arrayGet defined style.
Parameters
-
string$style The style to get.
Returns
arraySee Also
helper() ¶ public
helper(string $name, array<string, mixed> $config = []): Cake\Console\HelperRender 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<string, mixed>$config optional Configuration data for the helper.
Returns
Cake\Console\Helperhr() ¶ public
hr(int $newlines = 0, int $width = 79): voidOutputs 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
voidinfo() ¶ public
info(array<string>|string $message, int $newlines = 1, int $level = self::NORMAL): int|nullConvenience method for out() that wraps message between
Parameters
-
array<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|nullSee Also
level() ¶ public
level(int|null $level = null): intGet/set the current output level.
Parameters
-
int|null$level optional The current output level.
Returns
intnl() ¶ public
nl(int $multiplier = 1): stringReturns a single or multiple linefeeds sequences.
Parameters
-
int$multiplier optional Number of times the linefeed sequence should be repeated
Returns
stringout() ¶ public
out(array<string>|string $message = '', int $newlines = 1, int $level = self::NORMAL): int|nullOutputs 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
-
array<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|nulloverwrite() ¶ public
overwrite(array<string>|string $message, int $newlines = 1, int|null $size = null): voidOverwrite 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>|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
voidquiet() ¶ public
quiet(array<string>|string $message, int $newlines = 1): int|nullOutput at all levels.
Parameters
-
array<string>|string$message A string or an array of strings to output
-
int$newlines optional Number of newlines to append
Returns
int|nullsetInteractive() ¶ public
setInteractive(bool $value): voidParameters
-
bool$value Value
Returns
voidsetLoggers() ¶ public
setLoggers(int|bool $enable): voidConnects 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.
If you would like to take full control of how console application logging
to stdout works add a logger that uses 'className' => 'Console'. By
providing a console logger you replace the framework default behavior.
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
voidsetOutputAs() ¶ public
setOutputAs(int $mode): voidChange the output mode of the stdout stream
Parameters
-
int$mode The output mode.
Returns
voidSee Also
setStyle() ¶ public
setStyle(string $style, array $definition): voidAdds a new output style.
Parameters
-
string$style The style to set.
-
array$definition The array definition of the style to change or create.
Returns
voidSee Also
styles() ¶ public
styles(): arrayGets defined styles.
Returns
arraySee Also
success() ¶ public
success(array<string>|string $message, int $newlines = 1, int $level = self::NORMAL): int|nullConvenience method for out() that wraps message between
Parameters
-
array<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|nullSee Also
verbose() ¶ public
verbose(array<string>|string $message, int $newlines = 1): int|nullOutput at the verbose level.
Parameters
-
array<string>|string$message A string or an array of strings to output
-
int$newlines optional Number of newlines to append
Returns
int|nullwarning() ¶ public
warning(array<string>|string $message, int $newlines = 1): intConvenience method for err() that wraps message between
Parameters
-
array<string>|string$message A string or an array of strings to output
-
int$newlines optional Number of newlines to append
Returns
intSee Also
wrapMessageWithType() ¶ protected
wrapMessageWithType(string $messageType, array<string>|string $message): array<string>|stringWraps a message with a given message type, e.g.
Parameters
-
string$messageType The message type, e.g. "warning".
-
array<string>|string$message The message to wrap.
Returns
array<string>|stringProperty Detail
$_lastWritten ¶ protected
The number of bytes last written to the output stream used when overwriting the previous message.
Type
int