README

该 Joomla Console 包为您的 cli 应用程序提供了一个优雅且嵌套的命令结构。

命令调用流程

如果我们输入

$ php cli/console.php command1 command2 command3 -a -b -cd --help

命令调用流程是

rootCommand (console application)
    ->configure
    ->execute

    command1
        ->configure
        ->execute

        commend2
            ->configure
            ->execute

            commend3
                ->configure
                ->execute

            return exitCode

        return exitCode

    return exitCode

return exitCode

初始化控制台

控制台继承自 AbstractCliApplication，帮助我们创建命令行应用程序。

cli/console.php 文件中的控制台应用程序骨架示例

<?php

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

use Joomla\Console\Console;

$console = new Console;

$console->execute();

execute() 将找到与 cli 输入参数匹配的命令。如果没有注册任何命令，控制台将执行 默认命令。

默认命令

RootCommand 是一个继承自基本 Command 对象的命令对象。它提供了一些有用的辅助工具，我们可以通过输入来列出所有命令：

$ php cli/app.php

默认情况下，输出是

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.

为 RootCommand 设置执行代码

我们可以为每个命令添加闭包，这样这个命令将首先执行这个函数。在 $console 上使用 setHandler()，控制台将自动将代码传递给 RootCommand。

<?php
// cli/console.php

// ...

$console->setHandler(
	function($command)
	{
		$command->out('This is default command.');

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

$console->execute();

这将执行相同的行为

<?php
// cli/console.php

// ...

$console
    ->getRootCommand() // Return the RootCommand
    ->setHandler(
        function($command)
        {
            $command->out('This is default command.');

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

$console->execute();

重新输入 $ php cli/console.php 并输出

This is default command.

如果我们想再次获取帮助，只需输入

$ cli/console.php help

或者

$ cli/console.php --help

注意：命令只返回介于 0 到 255 之间的整数，0 表示成功，而其他表示失败或其他状态。Unix/Linux 的退出代码含义请参阅：退出代码含义

向控制台添加帮助信息

控制台包括一些帮助信息，如： name、version、description、usage 和 help。

如果我们将这些消息添加到控制台

// cli/console.php

// ...

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

$ foo bar -h => foo bar --help

---------

$ foo bar yoo -q => foo bar yoo --quiet
HELP
	);

// ...

帮助将显示

向控制台添加一级命令

现在，我们只是使用默认命令。除了 HelpCommand 之外，没有一级参数可以调用。

我们可以通过以下代码添加命令

<?php
// cli/console.php

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

然后我们输入

$ cli/console.php foo

我们将得到

This is Foo Command executing code.

如果我们输入 help

$ cli/console.php -h

foo 命令描述已自动添加到默认命令参数列表中。

使用我的命令对象

我们可以创建自己的命令对象，而不是在运行时设置它。

这是一个示例 FooCommand

<?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.');
    }
}

并将其注册到控制台

<?php
// cli/console.php

$console->addCommand(new FooCommand);

使用参数和选项

我们可以使用此代码来获取参数和选项

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);
}

如果我们输入

$ php cli/console.php foo Asika --yell

或者

$ php cli/console.php foo Asika -y

getOption() 方法将自动检测选项别名，然后我们可以获取

HELLO: ASIKA

注意：我们必须先调用 addOption()，然后 getOption('x') 才能获取我们想要的输入选项。

如果我们不先这样做，我们不得不使用 $this->input->get('x') 来获取选项值，但这种方式不支持选项别名。

添加二级命令和其他...

如果我们想在 FooCommand 之后添加几个命令，我们可以使用 addCommand() 方法。现在我们将两个 bar 和 yoo 命令添加到 FooCommand。

在运行时添加命令。

我们使用 addCommand() 来添加命令。

如果一个命令有一个或多个子命令，则参数意味着调用名称等于第一个参数的子命令。

如果一个命令有一个子命令，命令对象将在设置执行代码时运行它，如果没有设置执行代码，则运行 doExecute()。然后剩余的参数将保存在 $this->input->args 中。

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

use Joomla\Console\Option\Option;

//...

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

通过类添加命令

我们首先声明 BarCommand 和 YooCommand 类。

<?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.');
    }
}

然后注册它们到 FooCommand

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

use Myapp\Command\Foo\BarCommand;
use Myapp\Command\Foo\YooCommand;

//...

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

好的，键入

$ cli/console.php foo bar

我们得到

This is Bar Command executing code.

HelpCommand

HelpCommand 将自动为我们生成帮助列表。

当我们使用 addCommand()、addOption() 并为这些对象设置一些描述或其他信息时，它们将保存所有信息。然后当我们键入 $ cli/console.php help somethine 或 $ cli/console.php somethine --help，HelpCommand 将返回帮助信息给我们。

每个命令都有这些信息，您可以使用设置器和获取器来访问它们

Name (命令名称。根命令的名称是文件名。)
Description (命令描述，将在帮助输出标题后显示。)
Usage (将在当前命令的帮助输出中显示。)
Help (将在帮助输出底部显示，作为当前命令的手册)

控制台信息

Name (此应用程序的名称，将在帮助输出中作为标题显示。)
Description (根命令描述。)
Usage (根命令用法。)
Help (根命令帮助)

使用您自己的描述符

如果您想覆盖您应用程序的 Descriptor，您可以这样做

<?php
use Myapp\Command\Descriptor\XmlDescriptorHelper;
use Myapp\Command\Descriptor\XmlCommandDescriptor;
use Myapp\Command\Descriptor\XmlOptionDescriptor;

// ...

$descriptor = new new XmlDescriptorHelper(
    new XmlCommandDescriptor,
    new XmlOptionDescriptor
);

$console->getRootCommand()
    ->getChild('help')
    ->setDescriptor($descriptor);

// ...

在不使用控制台的情况下使用命令

我们可以使用 Command 而不使用 Console 或 CliApplication，请参阅 Command README。

通过 Composer 安装

将 "joomla/application": "dev-master" 添加到 composer.json 中的 require 块，确保您有 "minimum-stability": "dev"，然后运行 composer install。

{
    "require": {
        "asika/joomla-console": "dev-master"
    },
    "minimum-stability": "dev"
}

或者，您可以直接在命令行中运行以下命令

composer init --stability="dev"
composer require asika/joomla-console "dev-master"

asika/ joomla-console

维护者

详细信息