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 summary

  • int
    NORMAL
    1
  • int
    QUIET
    0
  • int
    VERBOSE
    2

Properties 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.

  • 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 $out, ?\Cake\Console\ConsoleOutput $err, ?\Cake\Console\ConsoleInput $in, ?\Cake\Console\HelperRegistry $helpers)

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 $options, ?string $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

string

Either the default value, or the user-provided input.

abort() public 

abort(mixed $message, mixed $code)

Halts the the current process with a StopException.

Parameters

string $message

Error message.

int $code optional

Error code.

Throws

Cake\Console\Exception\StopException

ask() public 

ask(string $prompt, ?string $default)

Prompts the user for input, and returns it.

Parameters

string $prompt

Prompt text.

string|null $default optional

Default input value.

Returns

string

Either the default value, or the user-provided input.

askChoice() public 

askChoice(string $prompt, mixed $options, ?string $default)

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

Either the default value, or the user-provided input.

createFile() public 

createFile(string $path, string $contents, bool $forceOverwrite)

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

Success.

Throws

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

err() public 

err(mixed $message, int $newlines)

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

The number of bytes returned from writing to stderr.

error() public 

error(mixed $message, int $newlines)

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

The number of bytes returned from writing to stderr.

See Also

https://book.cakephp.org/4/en/console-and-shells.html#ConsoleIo::err

getStyle() public 

getStyle(string $style)

Get defined style.

Parameters

string $style

The style to get.

Returns

array

See Also

\Cake\Console\ConsoleOutput::getStyle()

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

\Cake\Console\Helper

The created helper instance.

hr() public 

hr(int $newlines, int $width)

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

info() public 

info(mixed $message, int $newlines, int $level)

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

The number of bytes returned from writing to stdout or null if provided $level is greater than current level.

See Also

https://book.cakephp.org/4/en/console-and-shells.html#ConsoleIo::out

level() public 

level(?int $level)

Get/set the current output level.

Parameters

int|null $level optional

The current output level.

Returns

int

The current output level.

nl() public 

nl(int $multiplier)

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(mixed $message, int $newlines, int $level)

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

The number of bytes returned from writing to stdout or null if provided $level is greater than current level.

overwrite() public 

overwrite(mixed $message, int $newlines, ?int $size)

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.

quiet() public 

quiet(mixed $message, int $newlines)

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

The number of bytes returned from writing to stdout or null if current level is less than ConsoleIo::QUIET

setInteractive() public 

setInteractive(bool $value)

Parameters

bool $value

Value

setLoggers() public 

setLoggers(mixed $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

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.

setOutputAs() public 

setOutputAs(int $mode)

Change the output mode of the stdout stream

Parameters

int $mode

The output mode.

See Also

\Cake\Console\ConsoleOutput::setOutputAs()

setStyle() public 

setStyle(string $style, array $definition)

Adds a new output style.

Parameters

string $style

The style to set.

array $definition

The array definition of the style to change or create.

See Also

\Cake\Console\ConsoleOutput::setStyle()

styles() public 

styles()

Gets defined styles.

Returns

array

See Also

\Cake\Console\ConsoleOutput::styles()

success() public 

success(mixed $message, int $newlines, int $level)

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

The number of bytes returned from writing to stdout or null if provided $level is greater than current level.

See Also

https://book.cakephp.org/4/en/console-and-shells.html#ConsoleIo::out

verbose() public 

verbose(mixed $message, int $newlines)

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

The number of bytes returned from writing to stdout or null if current level is less than ConsoleIo::VERBOSE

warning() public 

warning(mixed $message, int $newlines)

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

The number of bytes returned from writing to stderr.

See Also

https://book.cakephp.org/4/en/console-and-shells.html#ConsoleIo::err

wrapMessageWithType() protected 

wrapMessageWithType(string $messageType, mixed $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

string|string[]

The message wrapped with the given message type.

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

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.1/class-Cake.Console.ConsoleIo.html