Console routes and routing

Zend Framework 2 has native MVC integration with console, which means that command line arguments are read and used to determine the appropriate action controller and action method that will handle the request. Actions can perform any number of task prior to returning a result, that will be displayed to the user in his console window.

There are several routes you can use with Console. All of them are defined in Zend\Mvc\Router\Console\* classes.

See also

Routes are used to handle real commands, but they are not used to create help messages (usage information). When a zf2 application is run in console for the first time (without arguments) it can display usage information that is provided by modules. To learn more about providing usage information, please read this chapter: Console-aware modules.

Router configuration

All Console Routes are automatically read from the following configuration location:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
// This can sit inside of modules/Application/config/module.config.php or any other module's config.
array(
    'router' => array(
        'routes' => array(
            // HTTP routes are here
        )
    ),

    'console' => array(
        'router' => array(
            'routes' => array(
                // Console routes go here
            )
        )
    ),
)

Console Routes will only be processed when the application is run inside console (terminal) window. They have no effect in web (http) request and will be ignored. It is possible to define only HTTP routes (only web application) or only Console routes (which means we want a console-only application which will refuse to run in a browser).

A single route can be described with the following array:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// inside config.console.router.routes:
// [...]
'my-first-route' => array(
    'type'    => 'simple',       // <- simple route is created by default, we can skip that
    'options' => array(
        'route'    => 'foo bar',
        'defaults' => array(
            'controller' => 'Application\Controller\Index',
            'action'     => 'password'
        )
    )
)

We have created a simple console route with a name my-first-route. It expects two parameters: foo and bar. If user puts these in a console, Application\Controller\IndexController::passwordAction() action will be invoked.

See also

You can read more about how ZF2 routing works in this chapter.

Basic route

This is the default route type for console. It recognizes the following types of parameters:

Literal parameters

These parameters are expected to appear on the command line exactly the way they are spelled in the route. For example:

1
2
3
4
5
6
7
8
9
'show-users' => array(
    'options' => array(
        'route'    => 'show users',
        'defaults' => array(
            'controller' => 'Application\Controller\Users',
            'action'     => 'show'
        )
    )
)

This route will only match for the following command line

> zf show users

It expects mandatory literal parameters show users. It will not match if there are any more params, or if one of the words is missing. The order of words is also enforced.

We can also provide optional literal parameters, for example:

1
2
3
4
5
6
7
8
9
'show-users' => array(
    'options' => array(
        'route'    => 'show [all] users',
        'defaults' => array(
            'controller' => 'Application\Controller\Users',
            'action'     => 'show'
        )
    )
)

Now this route will match for both of these commands:

> zf show users
> zf show all users

We can also provide parameter alternative:

1
2
3
4
5
6
7
8
9
'show-users' => array(
    'options' => array(
        'route'    => 'show [all|deleted|locked|admin] users',
        'defaults' => array(
            'controller' => 'Application\Controller\Users',
            'action'     => 'show'
        )
    )
)

This route will match both without and with second parameter being one of the words, which enables us to capture commands such:

> zf show users
> zf show locked users
> zf show admin users
etc.

Note

Whitespaces in route definition are ignored. If you separate your parameters with more spaces, or separate alternatives and pipe characters with spaces, it won’t matter for the parser. The above route definition is equivalent to: show [  all | deleted | locked | admin  ]   users

Literal flags

Flags are a common concept for console tools. You can define any number of optional and mandatory flags. The order of flags is ignored. The can be defined in any order and the user can provide them in any other order.

Let’s create a route with optional long flags

1
2
3
4
5
6
7
8
9
'check-users' => array</