XELOS Console Application

The console application consists of command sets. A commands set is a class that represent a bundle of related commands. Each command set provides run methods for each of the defined command in the command set. The definition of commands and its run method must follow a strict conventions as described in the next chapter.

Convention

A command consists of the following parts:

php xf [<vendor_name>/<module_name>:]<command>[:<subcommand>[:<subcommand>...]] arguments options

Examples:
Core:   php xf cache:clear
Module: php xf xelos/groups:group:template:reapply
Vendor: php xf blueend/kickstart:kickstart:doc 

Commands can be define in core, module or vendor module.

Core

Location:   class/Core/Console/Command   
Namespace:  XELOS\Framework\Core\Console\Command   
Cmd:        php xf <command>

Module

Location:   modules/<module_name>/class/Console   
Namespace:  XELOS\Modules\<ModuleName>\Console   
Cmd:        php xf xelos/<module_name>:<command> 

Vendor

Location:   vendor/<vendor_name>/modules/<module_name>/class/Console   
Namespace:  XELOS\Vendor\<VendorName>\Modules\<ModuleName>\Console   
Cmd:        php xf <vendor>/<module_name>:<command>  

CommandSet Implementation

The implementation of a new command set requires at least one class per command set. This class must extend the base class XELOS\Framework\Core\Console\Base\CommandSet and implement the abstract method CommandSet::setupCommandDefinitions. This method must be used to define the commands, arguments and options provided by the command set implementation. To define one or more commands you have to use the method CommandSet::registerCommandDefinition(...) within the setupCommandDefinitions method.

class MyCommand extends CommandSet {

    public function setupCommandDefinitions(): void {

        $this->registerCommandDefinition('mycommand:do', 'Do some stuff.')
                    ->addArgument('stuff', 'The stuff i have to do')
                    ->addOption('slow', 'If used, the stuff will be done slowly.')
                ;

        $this->registerCommandDefinition('mycommand:make', 'Make some stuff.')
                    ->addArgument('stuff', 'The stuff i have to make')
                    ->addOption('fast', 'If used, the stuff will be done fast.')
                ;
    }
}

The method CommandSet::registerCommandDefinition(...) returns an object of CommandDefinition which provides fluent add methods for adding arguments and options for the command. The argument and option can be set as optional by the third parameter of the add method.

Each command must provide a run method for execution. The name of the run method must be the name of the command in camel case and the 'run' prefix. For example, the command set implementation must provide a method for the defined command 'mycommand:do' with name MyCommand::runMycommandDo(...): void

class MyCommand extends CommandSet {

    public function setupCommandDefinitions(): void {
        $this->registerCommandDefinition('mycommand:do', 'Do some stuff.');
        $this->registerCommandDefinition('mycommand:make', 'Make some stuff.');
    }

    public function runMycommandDo(Input $input, Output $output): void {
        ...
    }

    public function runMycommandMake(Input $input, Output $output): void {
        ...
    }
}

The run method provides an input and output object as method parameters. The input object provides all information and data entered initially by the user and the possibility to initiate a new input by the user. The following example shows the most important usage of the input object.

class MyCommand extends CommandSet {

    public function runMycommandMake(Input $input, Output $output): void {
        $hasStuff= $input->hasArgument('stuff');
        $stuff   = $input->getArgument('stuff');
        $file    = $input->getOption('f'); // --f='/path/to/file'
        $special = $input->getOption('special');
        $isSlow  = $input->hasOption('slow');
        $interact= $input->isInteractive();
    }
}

The output object provides different method to output something on the console.

class MyCommand extends CommandSet {

    public function runMycommandMake(Input $input, Output $output): void {
        $output->message('some text');
        $output->error('some text');
        $output->success('some text');
    }
}

Global Options

Each command set can check for global options without to define them itself. The overwrite of global options is not allowed and triggers an exception.

 -h, --help             Displays help for this command. [optional]
 -n, --no-interaction   Do not ask any interactive question. [optional]
 -v|vv|vvv, --verbose   Increase the verbosity of messages. [optional]
 --testrun              Uses an test config if existing. [optional]
 --docker               Uses special handling for XELOS running on docker. [optional]
 --debug-profiling      Displays debug information for command execution. [optional]

Verbosity

The console provides a verbosity control which can be set via the global verbosity options. The verbosity information can be get from the input object $input->getVerbosity() or $input->isVerbose(). The verbosity is used to map verbosity levels (defined in the Output class) to log levels which defined in ConsoleLogger class. The ConsoleLogger is a kind of bridge between the console output and the Logger.