Shells, Tasks & Console Tools¶

The CakePHP console¶

This section provides an introduction into CakePHP at the command-line. If you’ve ever needed access to your CakePHP MVC classes in a cron job or other command-line script, this section is for you.

PHP provides a CLI client that makes interfacing with your file system and applications much smoother. The CakePHP console provides a framework for creating shell scripts. The Console uses a dispatcher-type setup to load a shell or task, and provide its parameters.

Before we get into specifics, let’s make sure we can run the CakePHP console. First, you’ll need to bring up a system shell. The examples shown in this section will be in bash, but the CakePHP Console is Windows-compatible as well. Let’s execute the Console program from bash. This example assumes that the user is currently logged into a bash prompt and is currently at the root of a CakePHP application.

CakePHP applications contain a Console directory that contains all the shells and tasks for an application. It also comes with an executable:

$ cd /path/to/cakephp/app
$ Console/cake

It’s often wise to add the core cake executable to your system path so you can use the cake command anywhere. This comes in handy when you are creating new projects. See Adding cake to your system path for how to make cake available systemwide.

Running the Console with no arguments produces this help message:

Welcome to CakePHP v2.0.0 Console
---------------------------------------------------------------
App : app
Path: /path/to/cakephp/app/
---------------------------------------------------------------
Current Paths:

 -app: app
 -working: /path/to/cakephp/app
 -root: /path/to/cakephp/
 -core: /path/to/cakephp/core

Changing Paths:

your working path should be the same as your application path
to change your path use the '-app' param.
Example: -app relative/path/to/cakephp/app or -app /absolute/path/to/cakephp/app

Available Shells:

 acl [CORE]                              i18n [CORE]
 api [CORE]                              import [app]
 bake [CORE]                             schema [CORE]
 command_list [CORE]                     testsuite [CORE]
 console [CORE]                          upgrade [CORE]

To run a command, type 'cake shell_name [args]'
To get help on a specific command, type 'cake shell_name help'

The first information printed relates to paths. This is especially helpful if you’re running the console from different parts of the filesystem.

Since many users add the CakePHP console to their system’s path so it can be accessed easily. Printing out the working, root, app, and core paths allows you to see where the console will be making changes. To change the app folder you wish to work with, you can supply its path as the first argument to the cake command. This next example shows how to specify an app folder, assuming you’ve already added the console folder to your PATH:

$ cake -app /path/to/cakephp/app

The path supplied can be relative to the current working directory or supplied as an absolute path.

Creating a shell¶

Let’s create a shell for use in the Console. For this example, we’ll create a simple Hello world shell. In your applications Console/Command directory create HelloShell.php. Put the following code inside it:

class HelloShell extends AppShell {
    public function main() {
        $this->out('Hello world.');
    }
}

The conventions for shell classes are that the class name should match the file name, with the suffix of Shell. In our shell we created a main() method. This method is called when a shell is called with no additional commands. We’ll add some more commands in a bit, but for now let’s just run our shell. From your application directory, run:

Console/cake hello

You should see the following output:

Welcome to CakePHP v2.0.0 Console
---------------------------------------------------------------
App : app
Path: /Users/markstory/Sites/cake_dev/app/
---------------------------------------------------------------
Hello world.

As mentioned before, the main() method in shells is a special method called whenever there are no other commands or arguments given to a shell. You may have also noticed that HelloShell is extending AppShell. Much like The App Controller, AppShell gives you a base class to contain all your common functions or logic. You can define an AppShell, by creating app/Console/Command/AppShell.php. If you don’t have one, CakePHP will use the built-in one. Since our main method wasn’t very interesting let’s add another command that does something:

class HelloShell extends AppShell {
    public function main() {
        $this->out('Hello world.');
    }

    public function hey_there() {
        $this->out('Hey there ' . $this->args[0]);
    }
}

After saving this file you should be able to run Console/cake hello hey_there your-name and see your name printed out. Any public method not prefixed by an _ is allowed to be called from the command line. In our hey_there method we also used $this->args, this property contains an array of all the positional arguments provided to a command. You can also use switches or options on shell applications, these are available at $this->params, and through the param() method. We’ll cover that in a bit.

When using a main() method you won’t be able to use the positional arguments or parameters. This is because the first positional argument or option is interpreted as the command name. If you want to use arguments and options, you should use method names other than main.

class UserShell extends AppShell {
    public $uses = array('User');

    public function show() {
        $user = $this->User->findByUsername($this->args[0]);
        $this->out(print_r($user, true));
    }
}

Shell tasks¶

There will be times when building more advanced console applications, you’ll want to compose functionality into re-usable classes that can be shared across many shells. Tasks allow you to extract commands into classes. For example the bake is made almost entirely of tasks. You define a shell’s tasks by using the $tasks property:

class UserShell extends AppShell {
    public $tasks = array('Template');
}

You can use tasks from plugins using the standard plugin syntax. Tasks are stored in Console/Command/Task/ in files named after their classes. So if we were to create a new ‘FileGenerator’ task, you would create Console/Command/Task/FileGeneratorTask.php.

Each task must at least implement an execute() method. The ShellDispatcher, will call this method when the task is invoked. A task class looks like:

class FileGeneratorTask extends Shell {
    public $uses = array('User');
    public function execute() {

    }
}

A shell can also access its tasks as properties, which makes tasks great for making re-usable chunks of functionality similar to Components:

// found in Console/Command/SeaShell.php
class SeaShell extends AppShell {
    public $tasks = array('Sound'); // found in Console/Command/Task/SoundTask.php
    public function main() {
        $this->Sound->execute();
    }
}

You can also access tasks directly from the command line:

$ cake sea sound

$Project = $this->Tasks->load('Project');

$ProgressBar = $this->Tasks->load('ProgressBar.ProgressBar');

Invoking other shells from your shell¶

Shells no longer have direct access to the ShellDispatcher any more through $this->Dispatch. There are still many cases where you will want to invoke one shell from another though. Shell::dispatchShell() gives you the ability to call other shells by providing the argv for the sub shell. You can provide arguments and options either as var args or as a string:

// As a string
$this->dispatchShell('schema create Blog --plugin Blog');

// As an array
$this->dispatchShell('schema', 'create', 'Blog', '--plugin', 'Blog');

The above shows how you can call the schema shell to create the schema for a plugin from inside your plugin’s shell.

Console output levels¶

Shells often need different levels of verbosity. When running as cron jobs, most output is un-necessary. And there are times when you are not interested in everything that a shell has to say. You can use output levels to flag output appropriately. The user of the shell, can then decide what level of detail they are interested in by setting the correct flag when calling the shell. Shell::out() supports 3 types of output by default.

• QUIET - Only absolutely important information should be marked for quiet output.

• NORMAL - The default level, and normal usage

• VERBOSE - Mark messages that may be too noisy for everyday use, but helpful for debugging as VERBOSE

You can mark output as follows:

// would appear at all levels.
$this->out('Quiet message', 1, Shell::QUIET);

// would not appear when quiet output is toggled
$this->out('normal message', 1, Shell::NORMAL);
$this->out('loud message', 1, Shell::VERBOSE);

// would only appear when verbose output is enabled.
$this->out('extra message', 1, Shell::VERBOSE);

You can control the output level of shells, by using the --quiet and --verbose options. These options are added by default, and allow you to consistently control output levels inside your CakePHP shells.

Styling output¶

Styling output is done by including tags - just like HTML - in your output. ConsoleOutput will replace these tags with the correct ansi code sequence, or remove the tags if you are on a console that doesn’t support ansi codes. There are several built-in styles, and you can create more. The built-in ones are

• error Error messages. Red underlined text.

• warning Warning messages. Yellow text.

• info Informational messages. Cyan text.

• comment Additional text. Blue text.

• question Text that is a question, added automatically by shell.

You can create additional styles using $this->stdout->styles(). To declare a new output style you could do:

$this->stdout->styles('flashy', array('text' => 'magenta', 'blink' => true));

This would then allow you to use a <flashy> tag in your shell output, and if ansi colours are enabled, the following would be rendered as blinking magenta text $this->out('<flashy>Whoooa</flashy> Something went wrong');. When defining styles you can use the following colours for the text and background attributes:

• black

• red

• green

• yellow

• blue

• magenta

• cyan

• white

You can also use the following options as boolean switches, setting them to a truthy value enables them.

• bold

• underline

• blink

• reverse

Adding a style makes it available on all instances of ConsoleOutput as well, so you don’t have to redeclare styles for both stdout and stderr objects.

$this->stdout->outputAs(ConsoleOutput::RAW);

Configuring options and generating help¶

class ConsoleOptionParser¶

Console option parsing in CakePHP has always been a little bit different from everything else on the command line. In 2.0 ConsoleOptionParser helps provide a more familiar command line option and argument parser.

OptionParsers allow you to accomplish two goals at the same time. First they allow you to define the options and arguments, separating basic input validation and your code. Secondly, it allows you to provide documentation, that is used to generate well formatted help file.

The console framework gets your shell’s option parser by calling $this->getOptionParser(). Overriding this method allows you to configure the OptionParser to match the expected inputs of your shell. You can also configure subcommand option parsers, which allow you to have different option parsers for subcommands and tasks. The ConsoleOptionParser implements a fluent interface and includes methods for easily setting multiple options/arguments at once.

public function getOptionParser() {
    $parser = parent::getOptionParser();
    //configure parser
    return $parser;
}

public function getOptionParser() {
    $parser = parent::getOptionParser();
    $parser->addArgument('type', array(
        'help' => 'Either a full path or type of class.'
    ))->addArgument('className', array(
        'help' => 'A CakePHP core class name (e.g: Component, HtmlHelper).'
    ))->addOption('method', array(
        'short' => 'm',
        'help' => __('The specific method you want help on.')
    ))->description(__('Lookup doc block comments for classes in CakePHP.'));
    return $parser;
}

// Set multiple lines at once
$parser->description(array('line one', 'line two'));

// read the current value
$parser->description();

// Set multiple lines at once
$parser->epilog(array('line one', 'line two'));

// read the current value
$parser->epilog();

$parser->addArgument('model', array('help' => 'The model to bake'));

$parser->addArguments(array(
    'node' => array('help' => 'The node to create', 'required' => true),
    'parent' => array('help' => 'The parent node', 'required' => true)
));

$parser->addArgument('type', array(
    'help' => 'The type of node to interact with.',
    'required' => true,
    'choices' => array('aro', 'aco')
));

$parser->addOption('connection', array(
    'short' => 'c',
    'help' => 'connection',
    'default' => 'default',
));

$parser->addOption('no-commit', array('boolean' => true));

$parser->addOptions(array(
    'node' => array('short' => 'n', 'help' => 'The node to create'),
    'parent' => array('short' => 'p', 'help' => 'The parent node')
));

$parser->addOption('accept', array(
    'help' => 'What version to accept.',
    'choices' => array('working', 'theirs', 'mine')
));

$parser->addOption('verbose', array(
    'help' => 'Enable verbose output.',
    'boolean' => true
));

if ($this->params['verbose']) {
    // do something
}

// as of 2.7
if ($this->param('verbose')) {
    // do something
}

$parser->addSubcommand('model', array(
    'help' => 'Bake a model',
    'parser' => $this->Model->getOptionParser()
));

$parser->addSubcommand('check', array(
    'help' => __('Check the permissions between an ACO and ARO.'),
    'parser' => array(
        'description' => array(
            __("Use this command to grant ACL permissions. Once executed, the "),
            __("ARO specified (and its children, if any) will have ALLOW access "),
            __("to the specified ACO action (and the ACO's children, if any).")
        ),
        'arguments' => array(
            'aro' => array('help' => __('ARO to check.'), 'required' => true),
            'aco' => array('help' => __('ACO to check.'), 'required' => true),
            'action' => array('help' => __('Action to check'))
        )
    )
));

public function getOptionParser() {
    return ConsoleOptionParser::buildFromArray(array(
        'description' => array(
            __("Use this command to grant ACL permissions. Once executed, the "),
            __("ARO specified (and its children, if any) will have ALLOW access "),
            __("to the specified ACO action (and the ACO's children, if any).")
        ),
        'arguments' => array(
            'aro' => array('help' => __('ARO to check.'), 'required' => true),
            'aco' => array('help' => __('ACO to check.'), 'required' => true),
            'action' => array('help' => __('Action to check'))
        )
    ));
}

cake bake --help
cake bake -h

cake bake model --help
cake bake model -h

cake bake --help xml
cake bake -h xml

<?xml version="1.0"?>
<shell>
    <command>bake fixture</command>
    <description>Generate fixtures for use with the test suite. You can use
        `bake fixture all` to bake all fixtures.</description>
    <epilog>
        Omitting all arguments and options will enter into an interactive
        mode.
    </epilog>
    <subcommands/>
    <options>
        <option name="--help" short="-h" boolean="1">
            <default/>
            <choices/>
        </option>
        <option name="--verbose" short="-v" boolean="1">
            <default/>
            <choices/>
        </option>
        <option name="--quiet" short="-q" boolean="1">
            <default/>
            <choices/>
        </option>
        <option name="--count" short="-n" boolean="">
            <default>10</default>
            <choices/>
        </option>
        <option name="--connection" short="-c" boolean="">
            <default>default</default>
            <choices/>
        </option>
        <option name="--plugin" short="-p" boolean="">
            <default/>
            <choices/>
        </option>
        <option name="--records" short="-r" boolean="1">
            <default/>
            <choices/>
        </option>
    </options>
    <arguments>
        <argument name="name" help="Name of the fixture to bake.
            Can use Plugin.name to bake plugin fixtures." required="">
            <choices/>
        </argument>
    </arguments>
</shell>

Routing in shells / CLI¶

In command-line interface (CLI), specifically your shells and tasks, env('HTTP_HOST') and other webbrowser specific environment variables are not set.

If you generate reports or send emails that make use of Router::url() those will contain the default host http://localhost/ and thus resulting in invalid URLs. In this case you need to specify the domain manually. You can do that using the Configure value App.fullBaseUrl from your bootstrap or config, for example.

For sending emails, you should provide CakeEmail class with the host you want to send the email with:

$Email = new CakeEmail();
$Email->domain('www.example.org');

This asserts that the generated message IDs are valid and fit to the domain the emails are sent from.

Shell API¶

class AppShell¶

AppShell can be used as a base class for all your shells. It should extend Shell, and be located in Console/Command/AppShell.php

class Shell($stdout = null, $stderr = null, $stdin = null)¶

Shell is the base class for all shells, and provides a number of functions for interacting with user input, outputting text a generating errors.

property Shell::$tasks¶

An array of tasks you want loaded for this shell/task.

property Shell::$uses¶

An array of models that should be loaded for this shell/task.

Shell::clear()¶

Clears the current output being displayed.

Shell::param($name)¶

Get the value of an option/parameter. Will return null if the parameter does not exist.

New in version 2.7.

Shell::createFile($path, $contents)¶

Parameters:

• $path (string) – Absolute path to the file you want to create.

• $contents (string) – Contents to put in the file.

Creates a file at a given path. If the Shell is interactive, a warning will be generated, and the user asked if they want to overwrite the file if it already exists. If the shell’s interactive property is false, no question will be asked and the file will simply be overwritten.

Shell::dispatchShell()¶

Dispatch a command to another Shell. Similar to Controller::requestAction() but intended for running shells from other shells.

See Invoking other shells from your shell.

Shell::err($message = null, $newlines = 1)¶

Parameters:

• $method (string) – The message to print.

• $newlines (integer) – The number of newlines to follow the message.

Outputs a method to stderr, works similar to Shell::out()

Shell::error($title, $message = null)¶

Parameters:

• $title (string) – Title of the error

• $message (string) – An optional error message

Displays a formatted error message and exits the application with status code 1

Shell::getOptionParser()¶

Should return a ConsoleOptionParser object, with any sub-parsers for the shell.

Shell::hasMethod($name)¶

Check to see if this shell has a callable method by the given name.

Shell::hasTask($task)¶

Check to see if this shell has a task with the provided name.

Shell::hr($newlines = 0, $width = 63)¶

Parameters:

• $newlines (int) – The number of newlines to precede and follow the line.

• $width (int) – The width of the line to draw.

Create a horizontal line preceded and followed by a number of newlines.

Shell::in($prompt, $options = null, $default = null)¶

Parameters:

• $prompt (string) – The prompt to display to the user.

• $options (array) – An array of valid choices the user can pick from. Picking an invalid option will force the user to choose again.

• $default (string) – The default option if there is one.

This method helps you interact with the user, and create interactive shells. It will return the users answer to the prompt, and allows you to provide a list of valid options the user can choose from:

$selection = $this->in('Red or Green?', array('R', 'G'), 'R');

The selection validation is case-insensitive.

Shell::initialize()¶

Initializes the Shell acts as constructor for subclasses allows configuration of tasks prior to shell execution.

Shell::loadTasks()¶

Loads tasks defined in public Shell::$tasks

Shell::nl($multiplier = 1)¶

Parameters:

• $multiplier (int) – Number of times the linefeed sequence should be repeated

Returns a number of linefeed sequences.

Shell::out($message = null, $newlines = 1, $level = Shell::NORMAL)¶

Parameters:

• $message (string) – The message to print.

• $newlines (integer) – The number of newlines to follow the message.

• $level (integer) – The highest Console output levels this message should display at.

The primary method for generating output to the user. By using levels, you can limit how verbose a shell is. out() also allows you to use colour formatting tags, which will enable coloured output on systems that support it. There are several built-in styles for colouring text, and you can define your own.

• error Error messages.

• warning Warning messages.

• info Informational messages.

• comment Additional text.

• question Magenta text used for user prompts

By formatting messages with style tags you can display styled output:

$this->out(
    '<warning>This will remove data from the filesystems.</warning>'
);

By default on *nix systems ConsoleOutput objects default to colour output. On Windows systems, plain output is the default unless the ANSICON environment variable is present.

Shell::overwrite($message = null, $newlines = 1, $size = null)¶

Parameters:

• $message (string) – The message to print.

• $newlines (integer) – The number of newlines to follow the message.

• $size (integer) – The number of bytes to overwrite

A useful method to generate progress bars or to avoid outputting too many lines.

Warning: You cannot overwrite text that contains newlines.

New in version 2.6.

Shell::runCommand($command, $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.

Shell::shortPath($file)¶

Makes absolute file path easier to read.

Shell::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.

Shell::wrapText($text, $options = array())¶

Wrap a block of text. Allows you to set the width, and indenting on a block of text.

Parameters:

• $text (string) – The text to format

• $options (array) –

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

More topics¶