Class Shell
Base class for command-line utilities for automating programmer chores.
- CakeObject
- Shell
Direct Subclasses
Indirect Subclasses
Copyright: Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
License: MIT License
Location: Cake/Console/Shell.php
Properties summary
-
$OptionParser
publicAn instance of ConsoleOptionParser that has been configured for this class. -
$Tasks
publicTask Collection for the command, used to create Tasks. -
$_helpers
protectedarray
Contains helpers which have been previously instantiated -
$_lastWritten
protectedinteger
The number of bytes last written to the output stream used when overwriting the previous message.
-
$_taskMap
protectedstring
Normalized map of tasks. -
$args
publicarray
Contains arguments parsed from the command line. -
$command
publicstring
The command (method/task) that is being run. -
$interactive
publicboolean
If true, the script will ask for permission to perform actions. -
$modelClass
publicstring
This shell's primary model class name, the first model in the $uses property -
$name
publicstring
The name of the shell in camelized. -
$params
publicarray
Contains command switches parsed from the command line. -
$plugin
publicstring
The name of the plugin the shell belongs to. Is automatically set by ShellDispatcher when a shell is constructed.
-
$stderr
publicstderr object. -
$stdin
publicstdin object -
$stdout
publicstdout object. -
$taskNames
publicarray
Contains the loaded tasks -
$tasks
publicarray
Contains tasks to load and instantiate -
$uses
publicarray
Contains models to load and instantiate
Method Summary
-
__construct() public
Constructs this Shell instance. -
__get() public
Overload get for lazy building of tasks -
__isset() public
Lazy loads models using the loadModel() method if declared in $uses -
_checkUnitTest() protected
Action to create a Unit Test -
_configureStdErrLogger() protected
Configure the stderr logger -
_configureStdOutLogger() protected
Configure the stdout logger -
_controllerName() protected
Creates the proper controller plural name for the specified controller class name -
_controllerPath() protected
Creates the proper controller path for the specified controller class name -
_displayHelp() protected
Display the help in the correct format -
_getInput() protected
Prompts the user for input, and returns it. -
_loadModels() protected
If $uses is an array load each of the models in the array -
_loggerIsConfigured() protected
Checks if the given logger is configured -
_modelKey() protected
Creates the proper underscored model key for associations -
_modelName() protected
Creates the proper model camelized name (singularized) for the specified name -
_modelNameFromKey() protected
Creates the proper model name from a foreign key -
_pluginPath() protected
Find the correct path for a plugin. Scans $pluginPaths for the plugin you want. -
_pluralHumanName() protected
Creates the plural human name used in views -
_pluralName() protected
Creates the plural name for views -
_singularHumanName() protected
Creates the singular human name used in views -
_singularName() protected
creates the singular name for use in views. -
_useLogger() protected
Used to enable or disable logging stream output to stdout and stderr If you don't wish to see in your stdout or stderr everything that is logged through CakeLog, call this function with first param as false
-
_welcome() protected
Displays a header for the shell -
clear() public
Clear the console -
createFile() public
Creates a file at given path -
dispatchShell() public
Dispatch a command to another Shell. Similar to CakeObject::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.
-
error() public
Displays a formatted error message and exits the application with status code 1
-
getOptionParser() public
Gets the option parser instance and configures it. -
hasMethod() public
Check to see if this shell has a callable method by the given name. -
hasTask() public
Check to see if this shell has a task with the provided name. -
helper() public
Load given shell helper class -
hr() public
Outputs a series of minus characters to the standard output, acts as a visual separator. -
in() public
Prompts the user for input, and returns it. -
initialize() public
Initializes the Shell acts as constructor for subclasses allows configuration of tasks prior to shell execution
-
loadModel() public
Loads and instantiates models required by this shell. -
loadTasks() public
Loads tasks defined in public $tasks -
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. -
param() public
Safely access the values in $this->params. -
runCommand() public
Runs the Shell with the provided argv. -
shortPath() public
Makes absolute file path easier to read -
startup() public
Starts up the Shell and displays the welcome message. Allows for checking and configuring prior to command or main execution
-
wrapText() public
Wrap a block of text. Allows you to set the width, and indenting on a block of text.
Method Detail
__construct() public ¶
__construct( ConsoleOutput
$stdout = null , ConsoleOutput
$stderr = null , ConsoleInput
$stdin = null )
Constructs this Shell instance.
Parameters
-
ConsoleOutput
$stdout optional null - A ConsoleOutput object for stdout.
-
ConsoleOutput
$stderr optional null - A ConsoleOutput object for stderr.
-
ConsoleInput
$stdin optional null - A ConsoleInput object for stdin.
Link
Overrides
__get() public ¶
__get( string $name )
Overload get for lazy building of tasks
Parameters
- string $name
- The property name to access.
Returns
__isset() public ¶
__isset( string $name )
Lazy loads models using the loadModel() method if declared in $uses
Parameters
- string $name
- The name of the model to look for.
_controllerName() protected ¶
_controllerName( string $name )
Creates the proper controller plural name for the specified controller class name
Parameters
- string $name
- Controller class name
Returns
Controller plural name
_controllerPath() protected ¶
_controllerPath( string $name )
Creates the proper controller path for the specified controller class name
Parameters
- string $name
- Controller class name
Returns
Path to controller
_displayHelp() protected ¶
_displayHelp( string $command )
Display the help in the correct format
Parameters
- string $command
- The command to get help for.
_getInput() protected ¶
_getInput( string $prompt , string|array $options , string $default )
Prompts the user for input, and returns it.
Parameters
- string $prompt
- Prompt text.
- string|array $options
- Array or string of options.
- string $default
- Default input value.
Returns
the default value, or the user-provided input.
_loadModels() protected ¶
_loadModels( )
If $uses is an array load each of the models in the array
Returns
_loggerIsConfigured() protected ¶
_loggerIsConfigured( string $logger )
Checks if the given logger is configured
Parameters
- string $logger
- The name of the logger to check
Returns
_modelKey() protected ¶
_modelKey( string $name )
Creates the proper underscored model key for associations
Parameters
- string $name
- Model class name
Returns
Singular model key
_modelName() protected ¶
_modelName( string $name )
Creates the proper model camelized name (singularized) for the specified name
Parameters
- string $name
- Name
Returns
Camelized and singularized model name
_modelNameFromKey() protected ¶
_modelNameFromKey( string $key )
Creates the proper model name from a foreign key
Parameters
- string $key
- Foreign key
Returns
Model name
_pluginPath() protected ¶
_pluginPath( string $pluginName )
Find the correct path for a plugin. Scans $pluginPaths for the plugin you want.
Parameters
- string $pluginName
- Name of the plugin you want ie. DebugKit
Returns
path path to the correct plugin.
_pluralHumanName() protected ¶
_pluralHumanName( string $name )
Creates the plural human name used in views
Parameters
- string $name
- Controller name
Returns
Plural human name
_pluralName() protected ¶
_pluralName( string $name )
Creates the plural name for views
Parameters
- string $name
- Name to use
Returns
Plural name for views
_singularHumanName() protected ¶
_singularHumanName( string $name )
Creates the singular human name used in views
Parameters
- string $name
- Controller name
Returns
Singular human name
_singularName() protected ¶
_singularName( string $name )
creates the singular name for use in views.
Parameters
- string $name
- The plural underscored value.
Returns
name
_useLogger() protected ¶
_useLogger( boolean $enable = true )
Used to enable or disable logging stream output to stdout and stderr If you don't wish to see in your stdout or stderr everything that is logged through CakeLog, call this function with first param as false
Parameters
- boolean $enable optional true
- whether to enable CakeLog output or not
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
Success
Link
dispatchShell() public ¶
dispatchShell( )
Dispatch a command to another Shell. Similar to CakeObject::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');
Returns
The return of the other shell.
Link
err() public ¶
err( string|array $message = null , integer $newlines = 1 )
Outputs a single or multiple error messages to stderr. If no parameters are passed outputs just a newline.
Parameters
- string|array $message optional null
- A string or an array of strings to output
- integer $newlines optional 1
- Number of newlines to append
Link
error() public ¶
error( string $title , string $message = null )
Displays a formatted error message and exits the application with status code 1
Parameters
- string $title
- Title of the error
- string $message optional null
- An optional error message
Link
getOptionParser() public ¶
getOptionParser( )
Gets the option parser instance and configures it.
By overriding this method you can configure the ConsoleOptionParser before returning it.
Returns
Link
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
Link
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
Success
Link
helper() public ¶
helper( string $name )
Load given shell helper class
Parameters
- string $name
- Name of the helper class. Supports plugin syntax.
Returns
Throws
If invalid class name is provided
hr() public ¶
hr( integer $newlines = 0 , integer $width = 63 )
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 63
- Width of the line, defaults to 63
Link
in() public ¶
in( string $prompt , string|array $options = null , string $default = null )
Prompts the user for input, and returns it.
Parameters
- string $prompt
- Prompt text.
- string|array $options optional null
- Array or string of options.
- string $default optional null
- Default input value.
Returns
Either the default value, or the user-provided input.
Link
initialize() public ¶
initialize( )
Initializes the Shell acts as constructor for subclasses allows configuration of tasks prior to shell execution
Link
loadModel() public ¶
loadModel( string $modelClass = null , mixed $id = null )
Loads and instantiates models required by this shell.
Parameters
- string $modelClass optional null
- Name of model class to load
- mixed $id optional null
- Initial ID the instanced model class should have
Returns
true when single model found and instance created, error returned if model not found.
Throws
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
Link
out() public ¶
out( string|array $message = null , integer $newlines = 1 , integer $level = Shell::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. 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|array $message optional null
- A string or an array of strings to output
- integer $newlines optional 1
- Number of newlines to append
- integer $level optional Shell::NORMAL
- The message's output level, see above.
Returns
Returns the number of bytes returned from writing to stdout.
Link
overwrite() public ¶
overwrite( array|string $message , integer $newlines = 1 , integer $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 $size optional null
- The number of bytes to overwrite. Defaults to the length of the last message output.
Returns
Returns the number of bytes returned from writing to stdout.
param() public ¶
param( string $name )
Safely access the values in $this->params.
Parameters
- string $name
- The name of the parameter to get.
Returns
Value. Will return null if it doesn't exist.
runCommand() public ¶
runCommand( string $command , array $argv )
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.
Parameters
- string $command
The command name to run on this shell. If this argument is empty, and the shell has a
main()
method, that will be called instead.- array $argv
- Array of arguments to run the shell with. This array should be missing the shell name.
Link
shortPath() public ¶
shortPath( string $file )
Makes absolute file path easier to read
Parameters
- string $file
- Absolute file path
Returns
short path
Link
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.
Link
wrapText() public ¶
wrapText( string $text , string|integer|array $options = array() )
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 72wordWrap
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.
- string|integer|array $options optional array()
- Array of options to use, or an integer to wrap the text to.
Returns
Wrapped / indented text
See
Link
Methods inherited from CakeObject
_mergeVars() protected ¶
_mergeVars( array $properties , string $class , boolean $normalize = true )
Merges this objects $property with the property in $class' definition. This classes value for the property will be merged on top of $class'
This provides some of the DRY magic CakePHP provides. If you want to shut it off, redefine this method as an empty function.
Parameters
- array $properties
- The name of the properties to merge.
- string $class
- The class to merge the property with.
- boolean $normalize optional true
- Set to true to run the properties through Hash::normalize() before merging.
_set() protected ¶
_set( array $properties = array() )
Allows setting of multiple properties of the object in a single line of code. Will only set properties that are part of a class declaration.
Parameters
- array $properties optional array()
- An associative array containing properties and corresponding values.
_stop() protected ¶
_stop( integer|string $status = 0 )
Stop execution of the current script. Wraps exit() making testing easier.
Parameters
- integer|string $status optional 0
- see http://php.net/exit for values
dispatchMethod() public ¶
dispatchMethod( string $method , array $params = array() )
Calls a method on this object with the given parameters. Provides an OO wrapper
for call_user_func_array
Parameters
- string $method
- Name of the method to call
- array $params optional array()
- Parameter list to use when calling $method
Returns
Returns the result of the method call
log() public ¶
log( string $msg , integer $type = LOG_ERR , null|string|array $scope = null )
Convenience method to write a message to CakeLog. See CakeLog::write() for more information on writing to logs.
Parameters
- string $msg
- Log message
- integer $type optional LOG_ERR
- Error type constant. Defined in app/Config/core.php.
- null|string|array $scope optional null
The scope(s) a log message is being created in. See CakeLog::config() for more information on logging scopes.
Returns
Success of log write
requestAction() public ¶
requestAction( string|array $url , array $extra = array() )
Calls a controller's method from any location. Can be used to connect controllers together or tie plugins into a main application. requestAction can be used to return rendered views or fetch the return value from controller actions.
Under the hood this method uses Router::reverse() to convert the $url parameter into a string URL. You should use URL formats that are compatible with Router::reverse()
Passing POST and GET data
POST and GET data can be simulated in requestAction. Use $extra['url']
for
GET data. The $extra['data']
parameter allows POST data simulation.
Parameters
- string|array $url
String or array-based URL. Unlike other URL arrays in CakePHP, this URL will not automatically handle passed and named arguments in the $url parameter.
- array $extra optional array()
if array includes the key "return" it sets the AutoRender to true. Can also be used to submit GET/POST data, and named/passed arguments.
Returns
Boolean true or false on success/failure, or contents of rendered action if 'return' is set in $extra.
toString() public ¶
toString( )
CakeObject-to-string conversion. Each class can override this method as necessary.
Returns
The name of this class
Properties detail
$OptionParser ¶
ConsoleOptionParser
An instance of ConsoleOptionParser that has been configured for this class.
$_lastWritten ¶
The number of bytes last written to the output stream used when overwriting the previous message.
$modelClass ¶
This shell's primary model class name, the first model in the $uses property
null
$plugin ¶
The name of the plugin the shell belongs to. Is automatically set by ShellDispatcher when a shell is constructed.
null