Console Tools, Shells & Tasks

Console Tools, Shells & Tasks

CakePHP features not only a web framework but also a console framework forcreating console applications. Console applications are ideal for handling avariety of background tasks such as maintenance, and completing work outside ofthe request-response cycle. CakePHP console applications allow you to reuse yourapplication classes from the command line.

CakePHP comes with a number of console applications out of the box. Some ofthese applications are used in concert with other CakePHP features (like i18n),and others are for general use to get you working faster.

The CakePHP Console

This section provides an introduction into CakePHP at the command-line. Consoletools are ideal for use in cron jobs, or command line based utilities that don’tneed to be accessible from a web browser.

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

Note

A command-line (CLI) build of PHP must be available on the systemif you plan to use the Console.

Before we get into specifics, let’s make sure you can run the CakePHP console.First, you’ll need to bring up a system terminal. The examples shown in thissection will be in bash, but the CakePHP Console is compatible with Windows aswell. This example assumes that you are currently logged into a bash prompt atthe root of your CakePHP application.

A CakePHP application contains src/Command, src/Shell andsrc/Shell/Task directories that contain its shells and tasks. It alsocomes with an executable in the bin directory:

$ cd /path/to/app
$ bin/cake

Note

For Windows, the command needs to be bin\cake (note the backslash).

Deprecated since version 3.6.0: Shells are deprecated as of 3.6.0, but will not be removed until 5.x.Use Console Commands instead.

Running the Console with no arguments produces this help message:

Welcome to CakePHP v3.6.0 Console

App : App

Path: /Users/markstory/Sites/cakephp-app/src/

Current Paths:

app: src
root: /Users/markstory/Sites/cakephp-app
core: /Users/markstory/Sites/cakephp-app/vendor/cakephp/cakephp

Available Commands:

version
help
cache
completion
i18n
schema_cache
plugin
routes
server
bug
console
event
orm
bake
bake.bake
migrations
migrations.migrations

To run a command, type cake shell_name [args|options]
To get help on a specific command, type cake shell_name --help

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

You could then run the any of the listed commands by using its name:

# run server shell
bin/cake server
 
# run migrations shell
bin/cake migrations -h
 
# run bake (with plugin prefix)
bin/cake bake.bake -h

Plugin commands can be invoked without a plugin prefix if the commands’s namedoes not overlap with an application or framework shell. In the case that twoplugins provide a command with the same name, the first loaded plugin will getthe short alias. You can always use the plugin.command format tounambiguously reference a command.

Console Applications

By default CakePHP will automatically discover all the commands in yourapplication and its plugins. You may want to reduce the number of exposedcommands, when building standalone console applications. You can use yourApplication’s console() hook to limit which commands are exposed andrename commands that are exposed:

// in src/Application.php
namespace App;
 
use App\Shell\UserShell;
use App\Shell\VersionShell;
use Cake\Http\BaseApplication;
 
class Application extends BaseApplication
{
    public function console($commands)
    {
        // Add by classname
        $commands->add('user', UserCommand::class);
 
        // Add instance
        $commands->add('version', new VersionCommand());
 
        return $commands;
    }
}

In the above example, the only commands available would be help, versionand user. See the Commands section for how to add commands inyour plugins.

Note

When adding multiple commands that use the same Command class, the helpcommand will display the shortest option.

New in version 3.5.0: The console hook was added.

Renaming Commands

There are cases where you will want to rename commands, to create nestedcommands or subcommands. While the default auto-discovery of commands will notdo this, you can register your commands to create any desired naming.

You can customize the command names by defining each command in your plugin:

public function console($commands)
{
    // Add commands with nested naming
    $commands->add('user dump', UserDumpCommand::class)
    $commands->add('user:show', UserShowCommand::class)
 
    // Rename a command entirely
    $commands->add('lazer', UserDeleteCommand::class)
 
    return $commands;
}

When overriding the console() hook in your application, remember tocall $commands->autoDiscover() to add commands from CakePHP, yourapplication, and plugins.

If you need to rename/remove any attached commands, you can use theConsole.buildCommands event on your application event manager to modify theavailable commands.

Commands

See the Console Commands chapter on how to create your firstcommand. Then learn more about commands:

CakePHP Provided Commands

Routing in the Console Environment

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

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

For sending emails, you should provide Email class with the host you want tosend the email with:

use Cake\Mailer\Email;
 
$email = new Email();
// Prior to 3.4 use domain()
$email->setDomain('www.example.org');

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