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.
Properties summary
-
$_errprotectedThe error stream -
$_helpersprotectedThe helper registry. -
$_inprotectedThe input stream -
$_lastWrittenprotectedintegerThe number of bytes last written to the output stream used when overwriting the previous message.
-
$_levelprotectedintegerThe current output level. -
$_outprotectedThe output stream -
$forceOverwriteprotectedbooleanWhether or not files should be overwritten
Method Summary
-
__construct() public
Constructor -
_getInput() protected
Prompts the user for input, and returns it. -
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 betweentag -
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 betweentag -
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.
-
outputAs() public deprecated
Change the output mode of the stdout stream -
overwrite() public
Overwrite some already output text. -
quiet() public
Output at all levels. -
setLoggers() public
Connects or disconnects the loggers to the console output. -
setOutputAs() public
Change the output mode of the stdout stream -
styles() public
Add a new output style or get defined styles. -
success() public
Convenience method for out() that wraps message betweentag -
verbose() public
Output at the verbose level. -
warning() public
Convenience method for err() that wraps message betweentag -
wrapMessageWithType() protected
Wraps a message with a given message type, e.g.
Method Detail
__construct() public ¶
__construct( Cake\Console\ConsoleOutput $out = null , Cake\Console\ConsoleOutput $err = null , Cake\Console\ConsoleInput $in = null , Cake\Console\HelperRegistry $helpers = null )
Constructor
Parameters
-
Cake\Console\ConsoleOutput$out optional null - A ConsoleOutput object for stdout.
-
Cake\Console\ConsoleOutput$err optional null - A ConsoleOutput object for stderr.
-
Cake\Console\ConsoleInput$in optional null - A ConsoleInput object for stdin.
-
Cake\Console\HelperRegistry$helpers optional null - A HelperRegistry instance
_getInput() protected ¶
_getInput( string $prompt , string|null $options , string|null $default )
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
Either the default value, or the user-provided input.
ask() public ¶
ask( string $prompt , string|null $default = null )
Prompts the user for input, and returns it.
Parameters
- string $prompt
- Prompt text.
- string|null $default optional null
- Default input value.
Returns
Either the default value, or the user-provided input.
askChoice() public ¶
askChoice( string $prompt , string|array $options , string|null $default = null )
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 null
- Default input value.
Returns
Either the default value, or the user-provided input.
createFile() public ¶
createFile( string $path , string $contents , boolean $forceOverwrite = false )
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.
- boolean $forceOverwrite optional false
Whether or not the file should be overwritten. If true, no question will be asked about whether or not to overwrite existing files.
Returns
Success.
Throws
Cake\Console\Exception\StopExceptionWhen q is given as an answer
to whether or not a file should be overwritten.
err() public ¶
err( string|string[] $message = '' , integer $newlines = 1 )
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
- integer $newlines optional 1
- Number of newlines to append
Returns
The number of bytes returned from writing to stderr.
error() public ¶
error( string|string[]|null $message = null , integer $newlines = 1 )
Convenience method for err() that wraps message between
Parameters
- string|string[]|null $message optional null
- A string or an array of strings to output
- integer $newlines optional 1
- Number of newlines to append
Returns
The number of bytes returned from writing to stderr.
See
helper() public ¶
helper( string $name , array $settings = [] )
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
hr() public ¶
hr( integer $newlines = 0 , integer $width = 79 )
Outputs a series of minus characters to the standard output, acts as a visual separator.
Parameters
- integer $newlines optional 0
- Number of newlines to pre- and append
- integer $width optional 79
- Width of the line, defaults to 79
info() public ¶
info( string|string[]|null $message = null , integer $newlines = 1 , integer $level = self::NORMAL )
Convenience method for out() that wraps message between
Parameters
- string|string[]|null $message optional null
- A string or an array of strings to output
- integer $newlines optional 1
- Number of newlines to append
- integer $level optional self::NORMAL
- The message's output level, see above.
Returns
The number of bytes returned from writing to stdout.
See
level() public ¶
level( integer|null $level = null )
Get/set the current output level.
Parameters
- integer|null $level optional null
- The current output level.
Returns
The current output level.
nl() public ¶
nl( integer $multiplier = 1 )
Returns a single or multiple linefeeds sequences.
Parameters
- integer $multiplier optional 1
- Number of times the linefeed sequence should be repeated
Returns
out() public ¶
out( string|string[] $message = '' , integer $newlines = 1 , integer $level = self::NORMAL )
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
- integer $newlines optional 1
- Number of newlines to append
- integer $level optional self::NORMAL
- The message's output level, see above.
Returns
The number of bytes returned from writing to stdout.
outputAs() public deprecated ¶
outputAs( integer $mode )
Change the output mode of the stdout stream
Deprecated
Parameters
- integer $mode
- The output mode.
See
overwrite() public ¶
overwrite( array|string $message , integer $newlines = 1 , integer|null $size = null )
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.
- integer $newlines optional 1
- Number of newlines to append.
- integer|null $size optional null
The number of bytes to overwrite. Defaults to the length of the last message output.
quiet() public ¶
quiet( string|string[] $message , integer $newlines = 1 )
Output at all levels.
Parameters
- string|string[] $message
- A string or an array of strings to output
- integer $newlines optional 1
- Number of newlines to append
Returns
The number of bytes returned from writing to stdout.
setLoggers() public ¶
setLoggers( integer|boolean $enable )
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
- integer|boolean $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.
setOutputAs() public ¶
setOutputAs( integer $mode )
Change the output mode of the stdout stream
Parameters
- integer $mode
- The output mode.
See
styles() public ¶
styles( string|null $style = null , array|false|null $definition = null )
Add a new output style or get defined styles.
Parameters
- string|null $style optional null
- The style to get or create.
- array|false|null $definition optional null
The array definition of the style to change or create a style or false to remove a style.
Returns
If you are getting styles, the style or null will be returned. If you are creating/modifying styles true will be returned.
See
success() public ¶
success( string|string[]|null $message = null , integer $newlines = 1 , integer $level = self::NORMAL )
Convenience method for out() that wraps message between
Parameters
- string|string[]|null $message optional null
- A string or an array of strings to output
- integer $newlines optional 1
- Number of newlines to append
- integer $level optional self::NORMAL
- The message's output level, see above.
Returns
The number of bytes returned from writing to stdout.
See
verbose() public ¶
verbose( string|string[] $message , integer $newlines = 1 )
Output at the verbose level.
Parameters
- string|string[] $message
- A string or an array of strings to output
- integer $newlines optional 1
- Number of newlines to append
Returns
The number of bytes returned from writing to stdout.
warning() public ¶
warning( string|string[]|null $message = null , integer $newlines = 1 )
Convenience method for err() that wraps message between
Parameters
- string|string[]|null $message optional null
- A string or an array of strings to output
- integer $newlines optional 1
- Number of newlines to append
Returns
The number of bytes returned from writing to stderr.
See
wrapMessageWithType() protected ¶
wrapMessageWithType( string $messageType , string|string[] $message )
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
The message wrapped with the given message type.
Properties detail
$_lastWritten ¶
The number of bytes last written to the output stream used when overwriting the previous message.