Zend Framework 2 has :doc:`native MVC integration with console<zend.console.introduction>`. The integration also works with :doc:`modules loaded with Module Manager <zend.module-manager.intro>`.
ZF2 ships with RouteNotFoundStrategy which is responsible of displaying usage information inside Console, in case the user has not provided any arguments, or arguments could not be understood. The strategy currently supports two types of information: :ref:`application banners <banner>` and :ref:`usage information<usage>`.
To run the console ZF 2 component, go to your public folder, and type php index.php. By default, it will simply output the current ZF 2 version, like this:
Our Application module (and any other module) can provide application banner. In order to do so, our Module class has to implement Zend\ModuleManager\Feature\ConsoleBannerProviderInterface. Let's do this now.
As you can see, the application banner should be a single line string that returns the module's name and (if available) its current version.
If several modules define their own banner, they are all shown one after the other (they will be joined together in the order modules are loaded). This way, it makes it very easy to spot which modules provide console commands.
After running our application, we'll see our newly created banner.
Let's create and load second module that provides a banner.
User module will add-on a short info about itself:
Because User module is loaded after Application module, the result will look like this:
Application banner is displayed as-is - no trimming or other adjustments will be performed on the text. As you can see, banners are also automatically colorized as blue.
In order to display usage information, our Module class has to implement Zend\ModuleManager\Feature\ConsoleUsageProviderInterface. Let's modify our example and add new method:
This will display the following information:
Similar to :ref:`application banner <banner>` multiple modules can provide usage information, which will be joined together and displayed to the user. The order in which usage information is displayed is the order in which modules are loaded.
As you can see, Console component also prepended each module's usage by the module's name. This helps to visually separate each modules (this can be useful when you have multiple modules that provide commands). By default, the component colorizes those in red.
Usage info provided in modules does not connect with :doc:`console routing <zend.console.routes>`. You can describe console usage in any form you prefer and it does not affect how MVC handles console commands. In order to handle real console requests you need to define 1 or more :doc:`console routes <zend.console.routes>`.
In order to output free-form text as usage information, getConsoleUsage() can return a string, or an array of strings, for example:
The text provided is displayed as-is - no trimming or other adjustments will be performed. If you'd like to fit your usage information inside console window, you could check its width with $console->getWidth().
List of commands
If getConsoleUsage() returns and associative array, it will be automatically aligned in 2 columns. The first column will be prepended with script name (the entry point for the application). This is useful to display different ways of running the application.
Commands and their descriptions will be aligned in two columns, that fit inside Console window. If the window is resized, some texts might be wrapped but all content will be aligned accordingly. If you don't like this behavior, you can always return :ref:`free-form text <free-form>` that will not be transformed in any way.
List of params and flags
Returning an array of arrays from getConsoleUsage() will produce a listing of parameters. This is useful for explaining flags, switches, possible values and other information. The output will be aligned in multiple columns for readability.
Below is an example:
Using this method, we can display more than 2 columns of information, for example:
All info will be aligned in one or more columns that fit inside Console window. If the window is resized, some texts might be wrapped but all content will be aligned accordingly. In case the number of columns changes (i.e. the array() contains different number of elements) a new table will be started, with new alignment and different column widths.
If you don't like this behavior, you can always return :ref:`free-form text <free-form>` that will not be transformed in any way.
You can use mix together all of the above styles to provide comprehensive usage information, for example:
As a reminder, here are the best practices when providing usage for your commands:
- Your getConsoleBanner should only return a one-line string containing the module's name and its version (if available).
- Your getConsoleUsage should not return module's name; it is prepended automatically for you by Console component.