Class Shell
Base class for command-line utilities for automating programmer chores.
Is the equivalent of Cake\Controller\Controller on the command line.
Constants summary
-
int
CODE_ERROR1
-
int
CODE_SUCCESS0
-
int
NORMAL\Cake\Console\ConsoleIo::NORMAL
-
int
QUIET\Cake\Console\ConsoleIo::QUIET
-
int
VERBOSE\Cake\Console\ConsoleIo::VERBOSE
Properties summary
- $OptionParser public
\Cake\Console\ConsoleOptionParser
An instance of ConsoleOptionParser that has been configured for this class.
- $Tasks public
\Cake\Console\TaskRegistry
Task Collection for the command, used to create Tasks.
- $_io protected
\Cake\Console\ConsoleIo
ConsoleIo instance.
- $_modelFactories protected
(callable|\Cake\Datasource\Locator\LocatorInterface)[]
A list of overridden model factory functions.
- $_modelType protected
string
The model type to use.
- $_tableLocator protected
\Cake\ORM\Locator\LocatorInterface|null
Table locator instance
- $_taskMap protected
array
Normalized map of tasks.
- $args public
array
Contains arguments parsed from the command line.
- $command public
string|null
The command (method/task) that is being run.
- $interactive public
bool
If true, the script will ask for permission to perform actions.
- $modelClass protected
string|null
This object's primary model class name. Should be a plural form.
- $name public
string
The name of the shell in camelized.
- $params public
array
Contains command switches parsed from the command line.
- $plugin public
string
The name of the plugin the shell belongs to.
- $rootName protected
string
The root command name used when generating help output.
- $taskNames public
array
Contains the loaded tasks
- $tasks public
array|bool
Contains tasks to load and instantiate
Method Summary
- __debugInfo() public
Returns an array that can be used to describe the internal state of this object.
- dispatchShell() public
Dispatch a command to another Shell. Similar to Object::requestAction() but intended for running shells from other shells.
- err() public
Outputs a single or multiple error messages to stderr. If no parameters are passed outputs just a newline.
- hr() public
Outputs a series of minus characters to the standard output, acts as a visual separator.
- initialize() public
Initializes the Shell acts as constructor for subclasses allows configuration of tasks prior to shell execution
- log() public
Convenience method to write a message to Log. See Log::write() for more information on writing to logs.
- out() public
Outputs a single or multiple messages to stdout. If no parameters are passed outputs just a newline.
Method Detail
__construct() public
__construct(?\Cake\Console\ConsoleIo $io, ?\Cake\ORM\Locator\LocatorInterface $locator)
Constructs this Shell instance.
Parameters
-
\Cake\Console\ConsoleIo|null
$io optional An io instance.
-
\Cake\ORM\Locator\LocatorInterface|null
$locator optional Table locator instance.
Links
__debugInfo() public
__debugInfo()
Returns an array that can be used to describe the internal state of this object.
Returns
array
__get() public
__get(string $name)
Overload get for lazy building of tasks
Parameters
-
string
$name The task to get.
Returns
\Cake\Console\Shell
Object of Task
_displayHelp() protected
_displayHelp(?string $command)
Display the help in the correct format
Parameters
-
string|null
$command optional The command to get help for.
Returns
int|null
The number of bytes returned from writing to stdout.
_mergeProperty() protected
_mergeProperty(string $property, array $parentClasses, array $options)
Merge a single property with the values declared in all parent classes.
Parameters
-
string
$property The name of the property being merged.
-
array
$parentClasses An array of classes you want to merge with.
-
array
$options Options for merging the property, see _mergeVars()
_mergePropertyData() protected
_mergePropertyData(array $current, array $parent, bool $isAssoc)
Merge each of the keys in a property together.
Parameters
-
array
$current The current merged value.
-
array
$parent The parent class' value.
-
bool
$isAssoc Whether or not the merging should be done in associative mode.
Returns
mixed
The updated value.
_mergeVars() protected
_mergeVars(array $properties, array $options)
Merge the list of $properties with all parent classes of the current class.
Options:
-
associative
- A list of properties that should be treated as associative arrays. Properties in this list will be passed through Hash::normalize() before merging.
Parameters
-
string[]
$properties An array of properties and the merge strategy for them.
-
array
$options optional The options to use when merging properties.
_setModelClass() protected
_setModelClass(string $name)
Set the modelClass property based on conventions.
If the property is already set it will not be overwritten
Parameters
-
string
$name Class name.
_setOutputLevel() protected
_setOutputLevel()
Set the output level based on the parameters.
This reconfigures both the output level for out() and the configured stdout/stderr logging
_stop() protected
_stop(int $status)
Stop execution of the current script.
Raises a StopException to try and halt the execution.
Parameters
-
int
$status optional see https://secure.php.net/exit for values
Throws
Cake\Console\Exception\StopException
_validateTasks() protected
_validateTasks()
Checks that the tasks in the task map are actually available
Throws
RuntimeException
_welcome() protected
_welcome()
Displays a header for the shell
abort() public
abort(string $message, int $exitCode)
Displays a formatted error message and exits the application with an error code.
Parameters
-
string
$message The error message
-
int
$exitCode optional The exit code for the shell task.
Throws
Cake\Console\Exception\StopException
Links
clear() public
clear()
createFile() public
createFile(string $path, string $contents)
Creates a file at given path
Parameters
-
string
$path Where to put the file.
-
string
$contents Content to put in the file.
Returns
bool
Success
Links
dispatchShell() public
dispatchShell()
Dispatch a command to another Shell. Similar to Object::requestAction() but intended for running shells from other shells.
Usage:
With a string command:
return $this->dispatchShell('schema create DbAcl');
Avoid using this form if you have string arguments, with spaces in them. The dispatched will be invoked incorrectly. Only use this form for simple command dispatching.
With an array command:
return $this->dispatchShell('schema', 'create', 'i18n', '--dry');
With an array having two key / value pairs:
-
command
can accept either a string or an array. Represents the command to dispatch -
extra
can accept an array of extra parameters to pass on to the dispatcher. This parameters will be available in theparam
property of the calledShell
return $this->dispatchShell([ 'command' => 'schema create DbAcl', 'extra' => ['param' => 'value'] ]);
or
return $this->dispatchShell([ 'command' => ['schema', 'create', 'DbAcl'], 'extra' => ['param' => 'value'] ]);
Returns
int
The CLI command exit code. 0 is success.
Links
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 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.
getIo() public
getIo()
Get the io object for this shell.
Returns
\Cake\Console\ConsoleIo
The current ConsoleIo object.
getModelType() public
getModelType()
Get the model type to be used by this class
Returns
string
getOptionParser() public
getOptionParser()
Gets the option parser instance and configures it.
By overriding this method you can configure the ConsoleOptionParser before returning it.
Returns
\Cake\Console\ConsoleOptionParser
Links
getTableLocator() public
getTableLocator()
Gets the table locator.
Returns
\Cake\ORM\Locator\LocatorInterface
hasMethod() public
hasMethod(string $name)
Check to see if this shell has a callable method by the given name.
Parameters
-
string
$name The method name to check.
Returns
bool
Links
hasTask() public
hasTask(string $task)
Check to see if this shell has a task with the provided name.
Parameters
-
string
$task The task name to check.
Returns
bool
Success
Links
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 63
Links
in() public
in(string $prompt, mixed $options, ?string $default)
Prompts the user for input, and returns it.
Parameters
-
string
$prompt Prompt text.
-
string|array|null
$options optional Array or string of options.
-
string|null
$default optional Default input value.
Returns
string|null
Either the default value, or the user-provided input.
Links
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.
See Also
initialize() public
initialize()
Initializes the Shell acts as constructor for subclasses allows configuration of tasks prior to shell execution
Links
loadModel() public
loadModel(?string $modelClass, ?string $modelType)
Loads and constructs repository objects required by this object
Typically used to load ORM Table objects as required. Can also be used to load other types of repository objects your application uses.
If a repository provider does not return an object a MissingModelException will be thrown.
Parameters
-
string|null
$modelClass optional Name of model class to load. Defaults to $this->modelClass. The name can be an alias like
'Post'
or FQCN likeApp\Model\Table\PostsTable::class
.-
string|null
$modelType optional The type of repository to load. Defaults to the getModelType() value.
Returns
\Cake\Datasource\RepositoryInterface
The model instance created.
Throws
Cake\Datasource\Exception\MissingModelException
If the model class cannot be found.
UnexpectedValueException
If $modelClass argument is not provided and ModelAwareTrait::$modelClass property value is empty.
loadTasks() public
loadTasks()
Loads tasks defined in public $tasks
Returns
true
log() public
log(string $message, mixed $level, mixed $context)
Convenience method to write a message to Log. See Log::write() for more information on writing to logs.
Parameters
-
string
$message Log message.
-
int|string
$level optional Error level.
-
string|array
$context optional Additional log data relevant to this message.
Returns
bool
Success of log write.
main() public
main(mixed $args)
Main entry method for the shell.
Parameters
-
mixed
$args
modelFactory() public
modelFactory(string $type, mixed $factory)
Override a existing callable to generate repositories of a given type.
Parameters
-
string
$type The name of the repository type the factory function is for.
-
callable|\Cake\Datasource\Locator\LocatorInterface
$factory The factory function used to create instances.
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
Links
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. Shell::QUIET, Shell::NORMAL, Shell::VERBOSE. The verbose and quiet output levels, map to the verbose
and quiet
output switches present in most shells. Using Shell::QUIET for a message means it will always display. While using Shell::VERBOSE means it will only display when verbose output is toggled.
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.
Links
param() public
param(string $name)
Safely access the values in $this->params.
Parameters
-
string
$name The name of the parameter to get.
Returns
string|bool|null
Value. Will return null if it doesn't exist.
parseDispatchArguments() public
parseDispatchArguments(array $args)
Parses the arguments for the dispatchShell() method.
Parameters
-
array
$args Arguments fetch from the dispatchShell() method with func_get_args()
Returns
array
First value has to be an array of the command arguments. Second value has to be an array of extra parameter to pass on to the dispatcher
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.
runCommand() public
runCommand(array $argv, bool $autoMethod, array $extra)
Runs the Shell with the provided argv.
Delegates calls to Tasks and resolves methods inside the class. Commands are looked up with the following order:
- Method on the shell.
- Matching task name.
-
main()
method.
If a shell implements a main()
method, all missing method calls will be sent to main()
with the original method name in the argv.
For tasks to be invoked they must be exposed as subcommands. If you define any subcommands, you must define all the subcommands your shell needs, whether they be methods on this class or methods on tasks.
Parameters
-
array
$argv Array of arguments to run the shell with. This array should be missing the shell name.
-
bool
$autoMethod optional Set to true to allow any public method to be called even if it was not defined as a subcommand. This is used by ShellDispatcher to make building simple shells easy.
-
array
$extra optional -
Extra parameters that you can manually pass to the Shell to be dispatched. Built-in extra parameter is :
-
requested
: if used, will prevent the Shell welcome message to be displayed
-
Returns
int|bool|null
Links
setIo() public
setIo(\Cake\Console\ConsoleIo $io)
Set the io object for this shell.
Parameters
-
\Cake\Console\ConsoleIo
$io The ConsoleIo object to use.
setModelType() public
setModelType(string $modelType)
Set the model type to be used by this class
Parameters
-
string
$modelType The model type
Returns
$this
setRootName() public
setRootName(string $name)
Set the root command name for help output.
Parameters
-
string
$name The name of the root command.
Returns
$this
setTableLocator() public
setTableLocator(\Cake\ORM\Locator\LocatorInterface $tableLocator)
Sets the table locator.
Parameters
-
\Cake\ORM\Locator\LocatorInterface
$tableLocator LocatorInterface instance.
Returns
$this
shortPath() public
shortPath(string $file)
Makes absolute file path easier to read
Parameters
-
string
$file Absolute file path
Returns
string
short path
Links
startup() public
startup()
Starts up the Shell and displays the welcome message.
Allows for checking and configuring prior to command or main execution
Override this method if you want to remove the welcome information, or otherwise modify the pre-command flow.
Links
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.
See Also
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.
warn() public
warn(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
wrapText() public
wrapText(string $text, mixed $options)
Wrap a block of text.
Allows you to set the width, and indenting on a block of text.
Options
-
width
The width to wrap to. Defaults to 72 -
wordWrap
Only wrap on words breaks (spaces) Defaults to true. -
indent
Indent the text with the string provided. Defaults to null.
Parameters
-
string
$text Text the text to format.
-
int|array
$options optional Array of options to use, or an integer to wrap the text to.
Returns
string
Wrapped / indented text
See Also
Links
Property Detail
$OptionParser public
An instance of ConsoleOptionParser that has been configured for this class.
Type
\Cake\Console\ConsoleOptionParser
$Tasks public
Task Collection for the command, used to create Tasks.
Type
\Cake\Console\TaskRegistry
$_io protected
ConsoleIo instance.
Type
\Cake\Console\ConsoleIo
$_modelFactories protected
A list of overridden model factory functions.
Type
(callable|\Cake\Datasource\Locator\LocatorInterface)[]
$_modelType protected
The model type to use.
Type
string
$_tableLocator protected
Table locator instance
Type
\Cake\ORM\Locator\LocatorInterface|null
$_taskMap protected
Normalized map of tasks.
Type
array
$args public
Contains arguments parsed from the command line.
Type
array
$command public
The command (method/task) that is being run.
Type
string|null
$interactive public
If true, the script will ask for permission to perform actions.
Type
bool
$modelClass protected
This object's primary model class name. Should be a plural form.
CakePHP will not inflect the name.
Example: For an object named 'Comments', the modelClass would be 'Comments'. Plugin classes should use Plugin.Comments
style names to correctly load models from the correct plugin.
Use empty string to not use auto-loading on this object. Null auto-detects based on controller name.
Type
string|null
$name public
The name of the shell in camelized.
Type
string
$params public
Contains command switches parsed from the command line.
Type
array
$plugin public
The name of the plugin the shell belongs to.
Is automatically set by ShellDispatcher when a shell is constructed.
Type
string
$rootName protected
The root command name used when generating help output.
Type
string
$taskNames public
Contains the loaded tasks
Type
array
$tasks public
Contains tasks to load and instantiate
Type
array|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.Shell.html