Как создавать пользовательские консольные команды с помощью компонента Symfony Console

() translation by (you can also view the original English article)

В этой статье мы рассмотрим то, каким образом вы можете создавать пользовательские консольные команды (CLI) в ваших PHP-приложениях с помощью компонента Symfony Console. После установки необходимых библиотек мы создадим несколько примеров для демонстрации концепций компонента Console.

Фактически, этот компонент используется несколькими PHP фреймворками для разработки приложений CLI, и несколько популярных фреймворков уже используют этот компонент в качестве отправной точки.

Что такое Console Component?

Компонент Symfony Console позволяет создавать пользовательские команды CLI в ваших PHP-приложениях. Если вы когда-либо работали с Laravel или Symfony, вы скорее всего знакомы с инструментами CLI, которые они предоставляют, чтобы облегчить такие ежедневные операции как:

генерация кода каркасов
очистка кешей
установка, включение и выключение дополнительных сервисов
запуск миграции базы данных
и другие

Например, в случае с Laravel он поставляется с инструментом artisan, который предоставляет множество полезных команд для облегчения нашей жизни. Вы можете быть удивлены, узнав, что инструмент artisan построен поверх самого компонента Symfony Console! На самом деле существует множество фреймворков, которые используют компонент Console для создания своих инструментов командной строки.

В этой статье мы рассмотрим основы компонента Console, чтобы вы могли создавать пользовательские команды CLI в своих PHP-приложениях. Для начала мы перейдем к установке компонента Console с помощью Composer. После установки мы создадим несколько примеров для демонстрационных целей.

Установка и настройка

В этом разделе мы собираемся установить компонент Console, необходимый для создания консольных команд в ваших PHP-приложениях. Я предполагаю, что вы установили Composer так как нам понадобится установить компонент Console, который доступен в Packagist.

После того, как вы установили Composer, перейдите и установите компонент Console, используя следующую команду.

1	$composer require symfony/console

Это должно было создать файл composer.json, со следующим содержимым:

{
    "require": {
        "symfony/console": "^4.0"
    }
}

Давайте изменим файл composer.json, чтобы он выглядел следующим образом:

{
    "require": {
        "symfony/console": "^4.0"
    },
    "autoload": {
         "psr-4": {
             "Console\\": "src"
         },
         "classmap": ["src"]
     }
}

Поскольку мы добавили новую запись в classmap, давайте продолжим и обновим автозагрузчик Composer, выполнив следующую команду.

1	$composer dump -o

Теперь вы можете использовать пространство имен Console для автозагрузки классов в каталоге src.

Ваша первая команда HelloWorld

Создание консольных команд с помощью компонента Console - это процесс, состоящий из двух этапов.

Во-первых, вам нужно создать консольное приложение, которое загружает необходимые зависимости и регистрирует ваши пользовательские команды.
Затем вам нужно создать файлы для всех команд, которые вы зарегистрировали в консольном приложении.

Создание консольного приложения

В этом разделе мы перейдем к созданию пользовательского консольного приложения.

Предлагаемая структура каталогов нашего консольного приложения следующим образом.

|-- bin
|   `-- console
|-- composer.json
|-- composer.lock
|-- src
|   `-- App
|       `-- Commands
|           |-- ClearcacheCommand.php
|           `-- HelloworldCommand.php
`-- vendor

Идем дальше и создаем файл /bin/console приложения со следующим содержимым. Обратите внимание, что расширение файла отсутствует, а также убедитесь, что это выполняемый файл, так как нам нужно запустить его из командной строки.

#!/usr/bin/env php
<?php
require_once __DIR__ . '/../vendor/autoload.php';

use Symfony\Component\Console\Application;

$app = new Application();
$app->run();

Первая строка в файле #!/usr/bin/env php гарантирует, что она запускается в среде PHP. Двигаемся дальше и попробуйте запустить его и посмотреть, что происходит.

$bin/console
Console Tool

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  help  Displays help for a command
  list  Lists commands

Неплохо! Имея всего несколько строк кода, у вас есть приложение! Но в данный момент оно пока не делает ничего полезного. В следующем разделе мы увидим, как вы можете создавать пользовательские команды и регистрировать их в нашем пользовательском консольном приложении.

Создайте файл команды Hello World

Давайте продолжим и создадим нашу первую пользовательскую команду: HelloworldCommand. Создайте файл src/App/Commands/HelloworldCommand.php со следующим содержимым.

<?php
namespace Console\App\Commands;

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Input\InputArgument;

class HelloworldCommand extends Command
{
    protected function configure()
    {
        $this->setName('hello-world')
            ->setDescription('Prints Hello-World!')
            ->setHelp('Demonstration of custom commands created by Symfony Console component.')
            ->addArgument('username', InputArgument::REQUIRED, 'Pass the username.');
    }

    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $output->writeln(sprintf('Hello World!, %s', $input->getArgument('username')));
    }
}

При создании пользовательской команды необходимо создать два основных метода: configure и execute.

Как следует из названия, метод configure позволяет настроить вашу команду, чтобы вы могли настроить имя команды, краткое описание, текст справки и т.д. Вы также можете настроить аргументы для своей команды, если вы хотите передавать параметры во время выполнения команды.

В приведенном выше примере имя команды установлено в hello-world. Кроме того, мы хотим передать имя пользователя в качестве первого аргумента, и поэтому мы настроили его с помощью метода addArgument.

С другой стороны, метод execute содержит логику приложения команды. В нашем случае мы сделали всё довольно просто, отобразив Hello World в качестве результата команды.

Прежде чем вы сможете продолжить эту команду, вам необходимо зарегистрировать ее в консольном приложении, которое мы создали в предыдущем разделе. Давайте быстро изменим файл bin/console, чтобы он выглядел следующим образом.

#!/usr/bin/env php
<?php
require_once __DIR__ . '/../vendor/autoload.php';

use Symfony\Component\Console\Application;
use Console\App\Commands\HelloworldCommand;

$app = new Application();
$app->add(new HelloworldCommand());
$app->run();

Как вы можете видеть, мы использовали метод add объекта Application для добавления команды HelloworldCommand. Давайте быстро перечислим все доступные команды.

$bin/console list
Console Tool

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  hello-world      Prints Hello-World!
  help             Displays help for a command
  list             Lists commands

Как и ожидалось, команда hello-world появляется в списке доступных команд! Запустим её!

1	$bin/console hello-world tutsplus
2	Hello World!, tutsplus

Вот как вы можете настроить основные команды!

Реальный пример команды - Очистка кэша

В предыдущем разделе мы построили команду hello-world, чтобы продемонстрировать концепции компонента Console. В этом разделе мы продолжим и создаем реальный пример, который демонстрирует, как вы можете создать команду для очистки кэшей в своем приложении.

Создадим файл Clear Cache Command

Двигаемся дальше и создаем файл src/App/Commands/ClearcacheCommand.php со следующим содержимым.

<?php
namespace Console\App\Commands;

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputOption;

class ClearcacheCommand extends Command
{
    protected function configure()
    {
        $this->setName('clear-cache')
            ->setDescription('Clears the application cache.')
            ->setHelp('Allows you to delete the application cache. Pass the --groups parameter to clear caches of specific groups.')
            ->addOption(
                    'groups',
                    'g',
                    InputOption::VALUE_OPTIONAL,
                    'Pass the comma separated group names if you don\'t want to clear all caches.',
                    ''
                );
    }

    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $output->writeln('Cache is about to cleared...');

        if ($input->getOption('groups'))
        {
            $groups = explode(",", $input->getOption('groups'));

            if (is_array($groups) && count($groups))
            {
                foreach ($groups as $group)
                {
                    $output->writeln(sprintf('%s cache is cleared', $group));
                }
            }
        }
        else
        {
            $output->writeln('All caches are cleared.');
        }

        $output->writeln('Complete.');
    }
}

Метод configure будет почти такой же, за исключением того, что мы использовали метод addOption для добавления опции к нашей команде. Таким образом, вы можете передавать сгруппированные значения с помощью параметра -groups.

С другой стороны, метод execute содержит логику приложения нашей команды.

Если вы хотите очистить кеш определенных групп, вам необходимо передать имена групп вместе с параметром --group. С другой стороны, пропустите параметр --group, если вы хотите очистить все кеши. Возможно, вы заметили, что мы сделали параметр --group необязательным, предоставив значение InputOption::VALUE_OPTIONAL в третьем аргументе метода addOption.

Регистрация и тестирование

Прежде чем мы начнем и запустим команду, давайте зарегистрируем команду в нашем консольном приложении.

#!/usr/bin/env php
<?php
require_once __DIR__ . '/../vendor/autoload.php';

use Symfony\Component\Console\Application;
use Console\App\Commands\HelloworldCommand;
use Console\App\Commands\ClearcacheCommand;

$app = new Application();
$app->add(new HelloworldCommand());
$app->add(new ClearcacheCommand());
$app->run();

Теперь идите и запустите команду bin/console clear-cache, чтобы очистить все кеши!

1	$bin/console clear-cache
2	Cache is about to cleared...
3	All caches are cleared.
4	Complete.

Затем, если вы хотите очистить определенные кеши, вы можете попробовать что-то вроде этого.

$bin/console clear-cache --groups=group1,group2
Cache is about to cleared...
group1 cache is cleared
group2 cache is cleared
Complete.

Конечно, вам нужно будет реализовать реальную логику для очистки кэшей, но это должно стать для вас хорошей отправной точкой.

Заключение

Сегодня мы рассмотрели один из популярных компонентов, предоставляемых фреймворком Symfony: Console Component. Это действительно полезный компонент, если вы хотите разработать собственное приложение CLI, которое поможет вам с легкостью выполнять ваши повседневные задачи.

В первой части статьи мы прошли установку и настройку компонента. Затем во вторй части мы создали несколько примеров консольных команд.

Сообщите нам, что вы думаете в комментариях ниже.

1	<?php
2	namespace Console\App\Commands;
3
4	use Symfony\Component\Console\Command\Command;
5	use Symfony\Component\Console\Input\InputInterface;
6	use Symfony\Component\Console\Output\OutputInterface;
7	use Symfony\Component\Console\Input\InputArgument;
8	use Symfony\Component\Console\Input\InputOption;
9
10	class ClearcacheCommand extends Command
11	{
12	protected function configure()
13	{
14	$this->setName('clear-cache')
15	->setDescription('Clears the application cache.')
16	->setHelp('Allows you to delete the application cache. Pass the --groups parameter to clear caches of specific groups.')
17	->addOption(
18	'groups',
19	'g',
20	InputOption::VALUE_OPTIONAL,
21	'Pass the comma separated group names if you don\'t want to clear all caches.',
22	''
23	);
24	}
25
26	protected function execute(InputInterface $input, OutputInterface $output)
27	{
28	$output->writeln('Cache is about to cleared...');
29
30	if ($input->getOption('groups'))
31	{
32	$groups = explode(",", $input->getOption('groups'));
33
34	if (is_array($groups) && count($groups))
35	{
36	foreach ($groups as $group)
37	{
38	$output->writeln(sprintf('%s cache is cleared', $group));
39	}
40	}
41	}
42	else
43	{
44	$output->writeln('All caches are cleared.');
45	}
46
47	$output->writeln('Complete.');
48	}
49	}