asika/joomla-console-quickstart

Joomla Console Example & Quickstart

Joomla Console Example & Quick Start

The Joomla Console package provide an elegant and nested command structure for your cli application., _(*1)

The Command Calling Flow

If we type:, _(*2)

``` bash $ php cli/console.php command1 command2 command3 -a -b -cd --help, <sub>(*3)</sub>

The command calling flow is:

defaultCommand (console application) ->configure ->execute, <sub>(*4)</sub>

command1
    ->configure
    ->execute

    commend2
        ->configure
        ->execute

        commend3
            ->configure
            ->execute

        return exitCode

    return exitCode

return exitCode

return exitCode, <sub>(*5)</sub>

## Initialising Console

Console is extends from [AbstractCliApplication](https://github.com/joomla/joomla-framework/tree/staging/src/Joomla/Application#command-line-applications), help us create a command line application.

An example console application skeleton in `cli/console.php` file:

``` php
<?php

// Load the Composer autoloader
include __DIR__ . '/../vendor/autoload.php';

use Joomla\Console\Console;

$console = new Console;

$console->execute();

The execute() will find commands matched the cli input argument. If there are not any command registered, console will execute the Default Command., <sub>(*6)</sub>

Default Command

DefaultCommand is a command object extends from base Command object. It provides some useful helper, we can list all commands by typing:, <sub>(*7)</sub>

``` bash $ php cli/app.php, <sub>(*8)</sub>

By default, the output is:

``` bash
Joomla! Console - version: 1.0
------------------------------------------------------------

[console.php Help]

The default application command

Usage:
  console.php <command> [option]


Options:

  -h / --help
      Display this help message.

  -q / --quiet
      Do not output any message.

  -v / --verbose
      Increase the verbosity of messages.

  --no-ansi
      Suppress ANSI colors on unsupported terminals.


Available commands:

  help    List all arguments and show usage & manual.


Welcome to Joomla! Console.

Set Executing Code for DefaultCommand

We can add closure to every commands, that this command will execute this function first. Use setCode() on $console, the Console will auto pass the code to DefaultCommand:, <sub>(*9)</sub>

``` php <?php // cli/console.php, <sub>(*10)</sub>

// ..., <sub>(*11)</sub>

$console->setCode( function($command) { $command->out('This is default command.');, <sub>(*12)</sub>

    return 0; // Return exit code.
}

);, <sub>(*13)</sub>

$console->execute();, <sub>(*14)</sub>

This will do same action:

``` php
<?php
// cli/console.php

// ...

$console
    ->getDefaultCommand() // Return the DefaultCommand
    ->setCode(
        function($command)
        {
            $command->out('This is default command.');

            return 0; // Return exit code.
        }
    );

$console->execute();

Retype $ php cli/console.php and output:, <sub>(*15)</sub>

This is default command.

If we want to get help again, just type:, <sub>(*16)</sub>

``` bash $ cli/console.php help, <sub>(*17)</sub>

OR

``` bash
$ cli/console.php --help

Note: Command only return integer between 0 and 255, 0 means success, while others means failure or other status. The exit code of Unix/Linux meaning please see: Exit Codes Meanings, <sub>(*18)</sub>

Add Help Message to Console

Console includes some help message like: name, version, description, usage and help., <sub>(*19)</sub>

If we add this messages to Console:, <sub>(*20)</sub>

``` php // cli/console.php, <sub>(*21)</sub>

// ..., <sub>(*22)</sub>

$console = with(new Console) ->setName('Example Console') ->setVersion('1.2.3') ->setUsage('console.php [-h|--help] [-q|--quiet]') ->setDescription('Hello World') ->setHelp( <<<HELP Hello, this is an example console, if you want to do something, see above:, <sub>(*23)</sub>

$ foo bar -h => foo bar --help, <sub>(*24)</sub>

$ foo bar yoo -q => foo bar yoo --quiet HELP );, <sub>(*25)</sub>

// ..., <sub>(*26)</sub>

The help will show:

![help](http://cl.ly/SPTF/cli-help.jpg)

## Add First Level Command to Console

Now, we just use the default command. But there are not first level arguments we can call except `HelpCommand`.

We can add a command by this code:

``` php
<?php
// cli/console.php

$console->register('foo')
    ->setDescription('This is first level foo command.')
    ->setUsage('foo command [--option]')
    ->setHelp('foo help')
    ->setCode(
        function($command)
        {
            $command->out('This is Foo Command executing code.');
        }
    );

Then we type:, <sub>(*27)</sub>

``` bash $ cli/console.php foo, <sub>(*28)</sub>

We will get:

This is Foo Command executing code., <sub>(*29)</sub>

If we type help:

$ cli/console.php -h, <sub>(*30)</sub>

The foo command description has auto added to default command arguments list.

![foo-help](http://cl.ly/SOfp/p2013-11-10-3.jpg)

## Using My Command Object

We can create our own command object instead setting it in runtime.

This is an example FooCommand:

``` php
<?php
// src/Myapp/Command/FooCommand.php

namespace Myapp\Command;

use Joomla\Console\Command\Command;

class FooCommand extends Command
{
    protected $name = 'foo';

    public function configure()
    {
        $this->setDescription('This is first level foo command.')
            ->setUsage('foo command [--option]')
            ->setHelp('foo help');
    }

    public function doExecute()
    {
        $this->out('This is Foo Command executing code.');
    }
}

And we register it in Console:, <sub>(*31)</sub>

``` php <?php // cli/console.php, <sub>(*32)</sub>

$console->addCommand(new FooCommand);, <sub>(*33)</sub>

## Using Arguments and Options

We can use this code to get arguments and options

``` php
public function configure()
{
    $this->setDescription('This is first level foo command.')
        ->setUsage('foo command [--option]')
        ->addOption(
            's', // option name
            0,   // default value
            'Add this option can make output lower case.', // option description
            Option::IS_GLOBAL // sub command will extends this global option
        )
        ->addOption(
            array('y', 'yell', 'Y'), // First element will be option name, others will be alias
            0,
            'Yell will make output upper case.',
            Option::IS_PRIVATE // sub command will not extends private option, this is default value, we don't need set private manually.
        )
        ->setHelp('foo help');
}

public function doExecute()
{
    if (empty($this->input->args[0]))
    {
        $this->out('Please enter a name: ');
        $name = fread(STDIN, 8792);
    }
    else
    {
        $name = $this->input->args[0];
    }

    $reply = 'Hello ' . $name;

    if ($this->getOption('y'))
    {
        $reply = strtoupper($reply);
    }

    if ($this->getOption('q'))
    {
        $reply = strtolower($reply);
    }

    $this->out($reply);
}

If we type:, <sub>(*34)</sub>

``` bash $ php cli/console.php foo Asika --yell, <sub>(*35)</sub>

OR

``` bash
$ php cli/console.php foo Asika -y

The getOption() method will auto detect option aliases, then we can get:, <sub>(*36)</sub>

HELLO: ASIKA

Note: We have to addOption() first, then the getOption('x') is able to get the input option which we wanted., <sub>(*37)</sub>

If we don't do this first, we have to use $this->input->get('x') to get option value, but this way do not support option aliases., <sub>(*38)</sub>

Add Second Level Commands and more...

If we want to add several commands after FooCommand, we can use AddArgument() method. Now we add two bar and yoo command to FooCommand., <sub>(*39)</sub>

Adding command in runtime.

We use addArgument() to add commands., <sub>(*40)</sub>

If a command has one or more sub commands, the arguments means to call sub command which name equals to first argument., <sub>(*41)</sub>

If a command has on sub commands, Command object will run executing code if set, or run doExecute() if executing code not set. Then the remaining arguments will save in $this->input->args., <sub>(*42)</sub>

``` php <?php // src/Myapp/Command/FooCommand.php, <sub>(*43)</sub>

use Joomla\Console\Option\Option;, <sub>(*44)</sub>

//..., <sub>(*45)</sub>

public function configure()
{
    $this->setDescription('This is first level foo command.')
        ->setUsage('foo command [--option]')
        ->setHelp('foo help')
        ->addArgument(
            'bar',
            'Bar description.'
        )
        ->addArgument(
            'yoo',
            'Yoo description.',
            array(
                new Option(array('y', 'yell'), 0),
                new Option('s', 0, 'desc', Option::IS_GLOBAL)
            )
        );
}

### Adding command by classes

We declare `BarCommand` and `YooCommand` class first.

``` php
<?php
// src/Myapp/Command/Foo/BarCommand.php

namespace Myapp\Command\Foo;

use Joomla\Console\Command\Command;

class BarCommand extends Command
{
    protected $name = 'bar';

    public function configure()
    {
        $this->setDescription('This is second level bar command.')
            ->setUsage('bar command [--option]')
            ->setHelp('bar help')
            ->addOption(new Option(array('y', 'yell'), 0))
            ->addOption(new Option('s', 0, 'desc', Option::IS_GLOBAL));
    }

    public function doExecute()
    {
        $this->out('This is Bar Command executing code.');
    }
}

Then register them to FooCommand:, <sub>(*46)</sub>

``` php <?php // src/Myapp/Command/FooCommand.php, <sub>(*47)</sub>

use Myapp\Command\Foo\BarCommand; use Myapp\Command\Foo\YooCommand;, <sub>(*48)</sub>

//..., <sub>(*49)</sub>

public function configure()
{
    $this->setDescription('This is first level foo command.')
        ->setUsage('foo command [--option]')
        ->setHelp('foo help')
        ->addArgument(new BarCommand)
        ->addArgument(new YooCommand);
}

OK, typing:

``` bash
$ cli/console.php foo bar

We get:, <sub>(*50)</sub>

This is Bar Command executing code.

HelpCommand

HelpCommand will auto generate help list for us., <sub>(*51)</sub>

When we use addArgument(), addOption() and set some description or other information to these objects, they will save all information in it. Then when we type $ cli/console.php help somethine or $ cli/console.php somethine --help, The HelpCommand will return the help message to us., <sub>(*52)</sub>

Every command has these information, you can use setter and getter to access them:, <sub>(*53)</sub>

• Name (Command name. The name of DefaultCommand is file name.)
• Description (Command description, will show after title in help output.)
• Usage (Will show in help output of current command.)
• Help (Will show in the help output bottom as a manual of current command)

The Console information:, <sub>(*54)</sub>

• Name (Name of this application, will show as title in help output.)
• Description (DefaultCommand description.)
• Usage (DefaultCommand usage.)
• Help (DefaultCommand help)

Use Your Own Descriptor

If you want to override the Descriptor for your apps, you can do this:, <sub>(*55)</sub>

``` php <?php use Myapp\Command\Descriptor\XmlDescriptorHelper; use Myapp\Command\Descriptor\XmlCommandDescriptor; use Myapp\Command\Descriptor\XmlOptionDescriptor;, <sub>(*56)</sub>

// ..., <sub>(*57)</sub>

$descriptor = new new XmlDescriptorHelper( new XmlCommandDescriptor, new XmlOptionDescriptor );, <sub>(*58)</sub>

$console->getDefaultCommand() ->getArgument('help') ->setDescriptor($descriptor);, <sub>(*59)</sub>

// ... ```, <sub>(*60)</sub>