Fr3nch13/CakePHP Utilities

ConsoleIo
in package

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.

Table of Contents

Constants

NORMAL  = 1
Output constant for making normal shells.
QUIET  = 0
Output constants for making quiet shells.
VERBOSE  = 2
Output constant making verbose shells.

Properties

$_err  : ConsoleOutput
The error stream
$_helpers  : HelperRegistry
The helper registry.
$_in  : ConsoleInput
The input stream
$_lastWritten  : int
The number of bytes last written to the output stream used when overwriting the previous message.
$_level  : int
The current output level.
$_out  : ConsoleOutput
The output stream
$forceOverwrite  : bool
Whether files should be overwritten
$interactive  : bool

Methods

__construct()  : mixed
Constructor
abort()  : void
Halts the the current process with a StopException.
ask()  : string
Prompts the user for input, and returns it.
askChoice()  : string
Prompts the user for input based on a list of options, and returns it.
comment()  : int|null
Convenience method for out() that wraps message between <comment /> tag
createFile()  : bool
Create a file at the given path.
err()  : int
Outputs a single or multiple error messages to stderr. If no parameters are passed outputs just a newline.
error()  : int
Convenience method for err() that wraps message between <error /> tag
getStyle()  : array<string|int, mixed>
Get defined style.
helper()  : Helper
Render a Console Helper
hr()  : void
Outputs a series of minus characters to the standard output, acts as a visual separator.
info()  : int|null
Convenience method for out() that wraps message between <info /> tag
level()  : int
Get/set the current output level.
nl()  : string
Returns a single or multiple linefeeds sequences.
out()  : int|null
Outputs a single or multiple messages to stdout. If no parameters are passed outputs just a newline.
overwrite()  : void
Overwrite some already output text.
quiet()  : int|null
Output at all levels.
setInteractive()  : void
setLoggers()  : void
Connects or disconnects the loggers to the console output.
setOutputAs()  : void
Change the output mode of the stdout stream
setStyle()  : void
Adds a new output style.
styles()  : array<string|int, mixed>
Gets defined styles.
success()  : int|null
Convenience method for out() that wraps message between <success /> tag
verbose()  : int|null
Output at the verbose level.
warning()  : int
Convenience method for err() that wraps message between <warning /> tag
_getInput()  : string
Prompts the user for input, and returns it.
wrapMessageWithType()  : array<string|int, string>|string
Wraps a message with a given message type, e.g. <warning>

Constants

NORMAL

Output constant for making normal shells.

public int NORMAL = 1

QUIET

Output constants for making quiet shells.

public int QUIET = 0

VERBOSE

Output constant making verbose shells.

public int VERBOSE = 2

Properties

$_lastWritten

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

protected int $_lastWritten = 0

$_level

The current output level.

protected int $_level = self::NORMAL

$forceOverwrite

Whether files should be overwritten

protected bool $forceOverwrite = false

$interactive

protected bool $interactive = true

Methods

abort()

Halts the the current process with a StopException.

public abort(string $message[, int $code = CommandInterface::CODE_ERROR ]) : void
Parameters
$message : string

Error message.

$code : int = CommandInterface::CODE_ERROR

Error code.

Tags
psalm-return

never-return

throws
StopException

ask()

Prompts the user for input, and returns it.

public ask(string $prompt[, string|null $default = null ]) : string
Parameters
$prompt : string

Prompt text.

$default : string|null = null

Default input value.

Return values
string —

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

askChoice()

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

public askChoice(string $prompt, array<string|int, string>|string $options[, string|null $default = null ]) : string
Parameters
$prompt : string

Prompt text.

$options : array<string|int, string>|string

Array or string of options.

$default : string|null = null

Default input value.

Return values
string —

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

comment()

Convenience method for out() that wraps message between <comment /> tag

public comment(array<string|int, string>|string $message[, int $newlines = 1 ][, int $level = self::NORMAL ]) : int|null
Parameters
$message : array<string|int, string>|string

A string or an array of strings to output

$newlines : int = 1

Number of newlines to append

$level : int = self::NORMAL

The message's output level, see above.

Tags
see
https://book.cakephp.org/4/en/console-and-shells.html#ConsoleIo::out
Return values
int|null —

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

createFile()

Create a file at the given path.

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

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
$path : string

The path to create the file at.

$contents : string

The contents to put into the file.

$forceOverwrite : bool = false

Whether the file should be overwritten. If true, no question will be asked about whether to overwrite existing files.

Tags
throws
StopException

When q is given as an answer to whether a file should be overwritten.

Return values
bool —

Success.

err()

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

public err([array<string|int, string>|string $message = '' ][, int $newlines = 1 ]) : int
Parameters
$message : array<string|int, string>|string = ''

A string or an array of strings to output

$newlines : int = 1

Number of newlines to append

Return values
int —

The number of bytes returned from writing to stderr.

error()

Convenience method for err() that wraps message between <error /> tag

public error(array<string|int, string>|string $message[, int $newlines = 1 ]) : int
Parameters
$message : array<string|int, string>|string

A string or an array of strings to output

$newlines : int = 1

Number of newlines to append

Tags
see
https://book.cakephp.org/4/en/console-and-shells.html#ConsoleIo::err
Return values
int —

The number of bytes returned from writing to stderr.

getStyle()

Get defined style.

public getStyle(string $style) : array<string|int, mixed>
Parameters
$style : string

The style to get.

Tags
see
ConsoleOutput::getStyle()
Return values
array<string|int, mixed>

helper()

Render a Console Helper

public helper(string $name[, array<string, mixed> $config = [] ]) : 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
$name : string

The name of the helper to render

$config : array<string, mixed> = []

Configuration data for the helper.

Return values
Helper —

The created helper instance.

hr()

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

public hr([int $newlines = 0 ][, int $width = 79 ]) : void
Parameters
$newlines : int = 0

Number of newlines to pre- and append

$width : int = 79

Width of the line, defaults to 79

info()

Convenience method for out() that wraps message between <info /> tag

public info(array<string|int, string>|string $message[, int $newlines = 1 ][, int $level = self::NORMAL ]) : int|null
Parameters
$message : array<string|int, string>|string

A string or an array of strings to output

$newlines : int = 1

Number of newlines to append

$level : int = self::NORMAL

The message's output level, see above.

Tags
see
https://book.cakephp.org/4/en/console-and-shells.html#ConsoleIo::out
Return values
int|null —

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

level()

Get/set the current output level.

public level([int|null $level = null ]) : int
Parameters
$level : int|null = null

The current output level.

Return values
int —

The current output level.

nl()

Returns a single or multiple linefeeds sequences.

public nl([int $multiplier = 1 ]) : string
Parameters
$multiplier : int = 1

Number of times the linefeed sequence should be repeated

Return values
string

out()

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

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

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
$message : array<string|int, string>|string = ''

A string or an array of strings to output

$newlines : int = 1

Number of newlines to append

$level : int = self::NORMAL

The message's output level, see above.

Return values
int|null —

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

overwrite()

Overwrite some already output text.

public overwrite(array<string|int, string>|string $message[, int $newlines = 1 ][, int|null $size = null ]) : void

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
$message : array<string|int, string>|string

The message to output.

$newlines : int = 1

Number of newlines to append.

$size : int|null = null

The number of bytes to overwrite. Defaults to the length of the last message output.

quiet()

Output at all levels.

public quiet(array<string|int, string>|string $message[, int $newlines = 1 ]) : int|null
Parameters
$message : array<string|int, string>|string

A string or an array of strings to output

$newlines : int = 1

Number of newlines to append

Return values
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) : void
Parameters
$value : bool

Value

setLoggers()

Connects or disconnects the loggers to the console output.

public setLoggers(int|bool $enable) : void

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
$enable : int|bool

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.

setStyle()

Adds a new output style.

public setStyle(string $style, array<string|int, mixed> $definition) : void
Parameters
$style : string

The style to set.

$definition : array<string|int, mixed>

The array definition of the style to change or create.

Tags
see
ConsoleOutput::setStyle()

success()

Convenience method for out() that wraps message between <success /> tag

public success(array<string|int, string>|string $message[, int $newlines = 1 ][, int $level = self::NORMAL ]) : int|null
Parameters
$message : array<string|int, string>|string

A string or an array of strings to output

$newlines : int = 1

Number of newlines to append

$level : int = self::NORMAL

The message's output level, see above.

Tags
see
https://book.cakephp.org/4/en/console-and-shells.html#ConsoleIo::out
Return values
int|null —

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

verbose()

Output at the verbose level.

public verbose(array<string|int, string>|string $message[, int $newlines = 1 ]) : int|null
Parameters
$message : array<string|int, string>|string

A string or an array of strings to output

$newlines : int = 1

Number of newlines to append

Return values
int|null —

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

warning()

Convenience method for err() that wraps message between <warning /> tag

public warning(array<string|int, string>|string $message[, int $newlines = 1 ]) : int
Parameters
$message : array<string|int, string>|string

A string or an array of strings to output

$newlines : int = 1

Number of newlines to append

Tags
see
https://book.cakephp.org/4/en/console-and-shells.html#ConsoleIo::err
Return values
int —

The number of bytes returned from writing to stderr.

_getInput()

Prompts the user for input, and returns it.

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

Prompt text.

$options : string|null

String of options. Pass null to omit.

$default : string|null

Default input value. Pass null to omit.

Return values
string —

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

wrapMessageWithType()

Wraps a message with a given message type, e.g. <warning>

protected wrapMessageWithType(string $messageType, array<string|int, string>|string $message) : array<string|int, string>|string
Parameters
$messageType : string

The message type, e.g. "warning".

$message : array<string|int, string>|string

The message to wrap.

Return values
array<string|int, string>|string —

The message wrapped with the given message type.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results