Краткий обзор подсистемы команд в Symfony

Веб-разработка
5 июля 2023
8 мин чтения
Краткий обзор подсистемы команд в Symfony

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

В современных версиях Symfony команды можно объявлять через PHP-атрибуты, а зависимости передавать через контейнер сервисов.

php bin/console list
php bin/console about

Для запуска конкретной команды используется её имя:

php bin/console app:sync-products

Допустим, необходимо разработать синхронизацию товаров с 1С. Начать можно с отдельной консольной команды: она позволяет запускать синхронизацию вручную, проверять результат и только после этого подключать выполнение по расписанию.

Для генерации класса команды используется Symfony MakerBundle.

composer require --dev symfony/maker-bundle
php bin/console make:command

Если MakerBundle уже установлен, повторная установка не требуется.

Генератор предложит указать имя команды и создаст PHP-класс. В дальнейшем класс можно редактировать вручную. Для регистрации команды в современных проектах используется атрибут #[AsCommand].

Краткий обзор подсистемы команд в Symfony - изображение 1

Ниже пример команды с обязательным аргументом и опцией --force. Он использует классический способ наследования от Command, который подходит для поддерживаемых версий Symfony.

Создадим файл src/Command/SyncProductsCommand.php:

<?php

declare(strict_types=1);

namespace App\Command;

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

#[AsCommand(
    name: 'app:sync-products',
    description: 'Запускает синхронизацию товаров с 1С',
)]
final class SyncProductsCommand extends Command
{
    protected function configure(): void
    {
        $this
            ->addArgument(
                'source',
                InputArgument::REQUIRED,
                'Источник данных',
            )
            ->addOption(
                'force',
                null,
                InputOption::VALUE_NONE,
                'Принудительный запуск',
            );
    }

    protected function execute(
        InputInterface $input,
        OutputInterface $output,
    ): int {
        $source = (string) $input->getArgument('source');
        $force = (bool) $input->getOption('force');

        $output->writeln('Источник: ' . $source);
        $output->writeln('Принудительный запуск: ' . ($force ? 'да' : 'нет'));

        return Command::SUCCESS;
    }
}

Пример демонстрирует интерфейс команды, а не выполняет реальный обмен с 1С. Для синхронизации потребуется отдельный сервис с логикой получения и обработки данных.

Запуск:

php bin/console app:sync-products catalog
php bin/console app:sync-products catalog --force

При стандартной конфигурации Symfony с автозагрузкой сервисов из src/ команда регистрируется автоматически.

Краткий обзор подсистемы команд в Symfony - изображение 2

В примере source — обязательный аргумент, который передаётся сразу после имени команды. --force — опция-флаг, которую можно указывать независимо от позиции аргумента.

Атрибут #[AsCommand] определяет имя и описание команды. Аргументы и опции в классическом варианте задаются через configure().

Для аргументов можно указать обязательность, значения по умолчанию и описание. Опции поддерживают короткие имена, значения и режим флага.

Начиная с Symfony 7.3 доступны также invokable-команды: аргументы и опции можно описывать непосредственно в параметрах метода __invoke() через атрибуты #[Argument] и #[Option].

Например:

<?php

declare(strict_types=1);

namespace App\Command;

use Symfony\Component\Console\Attribute\Argument;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Attribute\Option;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Style\SymfonyStyle;

#[AsCommand(name: 'app:sync-demo')]
final class SyncDemoCommand
{
    public function __invoke(
        SymfonyStyle $io,
        #[Argument(description: 'Источник данных')]
        string $source,
        #[Option(description: 'Принудительный запуск')]
        bool $force = false,
    ): int {
        $io->writeln('Источник: ' . $source);
        $io->writeln('Принудительный запуск: ' . ($force ? 'да' : 'нет'));

        return Command::SUCCESS;
    }
}

Этот вариант требует Symfony 7.3 или новее. Для более старых проектов используйте наследование от Command и методы configure() / execute().

Symfony Console также предоставляет компоненты для интерактивного ввода, оформления сообщений и отображения прогресса. Для большинства прикладных команд удобно использовать SymfonyStyle, а для предотвращения параллельного выполнения одной операции — механизмы блокировок.

При реализации интерактивных команд предусмотрите возможность неинтерактивного запуска в CI, cron или других системах автоматизации.

Многие библиотеки Symfony и сторонние пакеты добавляют собственные консольные команды. Их список можно посмотреть через php bin/console list, а параметры отдельной команды — через --help.

Например, DoctrineBundle предоставляет команды для работы с базой данных. Конкретный список зависит от установленных пакетов и их версий.

Содержание

Когда лучше всего применять команды?

  • Регулярные операции: синхронизация данных, отправка уведомлений, очистка временных файлов, импорт и экспорт. Для запуска по расписанию можно использовать cron, systemd timers или соответствующую инфраструктуру приложения.
  • Разовые исправления данных: операции, которые требуют бизнес-логики, обращения к внешним сервисам или обработки большого количества записей. В отличие от миграций схемы, такие действия удобнее оформлять отдельной командой.
  • Административные функции: операции, которым не нужен публичный веб-интерфейс.
  • Диагностика и отладка: воспроизведение проблем, запуск проверок и анализ состояния приложения.
  • Развёртывание: проверка конфигурации, подготовка данных и служебные операции перед релизом.

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

Как расширять и переопределять команды?

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

Однако не всякую стороннюю команду следует переопределять. Если требуется выполнить собственную операцию, обычно проще создать новую команду с отдельным именем и использовать нужные сервисы.

Пример из старой версии статьи связан с командами Doctrine doctrine:query:sql и dbal:run-sql.

В разных версиях DoctrineBundle менялись имена и регистрация команд. Современная команда для выполнения SQL — dbal:run-sql, если она присутствует в установленной конфигурации. Не следует привязывать это изменение к абстрактной «версии 2.2» без указания конкретного пакета.

Проверить доступные команды можно так:

php bin/console list doctrine
php bin/console list dbal
php bin/console dbal:run-sql --help

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

Чтобы найти сервис команды в контейнере, сначала проверьте имя PHP-класса и регистрацию:

php bin/console debug:container --show-hidden | grep -i command

Если известен класс команды, можно запросить его напрямую:

php bin/console debug:container 'App\Command\SyncProductsCommand'

Команды сторонних библиотек не всегда доступны как обычные публичные сервисы. Результат зависит от способа регистрации и оптимизации контейнера.

Для Doctrine-команд имя, под которым команда запускается из CLI, не обязательно совпадает с идентификатором сервиса в контейнере. Ищите регистрацию по классу и просматривайте определения в исходном коде установленной версии пакета.

Краткий обзор подсистемы команд в Symfony - изображение 3

Если поиск по имени CLI-команды ничего не возвращает, попробуйте найти сервис по полному имени PHP-класса или изучить конфигурацию соответствующего bundle.

Так пусто:

Краткий обзор подсистемы команд в Symfony - изображение 4

А так есть:

Краткий обзор подсистемы команд в Symfony - изображение 5

Для изменения поведения сторонней команды сначала рассмотрите менее сложные варианты:

  1. Создать собственную команду с другим именем и использовать те же сервисы приложения.
  2. Декорировать сервис исходной команды, если её регистрация и контракт допускают такую замену.
  3. Использовать CompilerPass, только если необходимо изменять определение сервиса на этапе компиляции контейнера.

Например, собственную команду можно зарегистрировать через атрибут #[AsCommand], а логику вынести в отдельный сервис. Тогда изменение поведения не требует вмешательства в контейнер сторонней библиотеки.

Декорирование настраивается через decorates в services.yaml, но его применение к конкретной консольной команде необходимо проверять: простое декорирование сервиса не гарантирует сохранение регистрации CLI-имени и всех особенностей команды. Для некоторых сторонних команд более надёжным решением остаётся отдельная команда или специально настроенный CompilerPass.

Краткий обзор подсистемы команд в Symfony - изображение 6

Если выбран вариант с CompilerPass, необходимо зарегистрировать его в процессе сборки контейнера, обычно через Kernel::build(). Это низкоуровневый механизм Symfony, который следует использовать только при понятной структуре определений сервиса.

Краткий обзор подсистемы команд в Symfony - изображение 7

После изменения конфигурации проверьте, какой сервис зарегистрирован в контейнере. Для этого используйте debug:container и диагностические команды Symfony.

Краткий обзор подсистемы команд в Symfony - изображение 8

Затем проверьте фактическое поведение нужной CLI-команды. Само наличие сервиса в контейнере ещё не доказывает, что именно он вызывается при запуске определённого имени команды.

Краткий обзор подсистемы команд в Symfony - изображение 9

Для старых команд Doctrine принцип тот же: сначала определите установленную версию пакета, реальный класс команды и способ регистрации. Только после этого выбирайте переопределение определения сервиса, декорирование или отдельную реализацию.

Краткий обзор подсистемы команд в Symfony - изображение 10

Подробнее о создании команд, атрибутах и настройке контейнера читайте в официальной документации:

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

Редакция NJ Soft
Редакция NJ Soft
Редактор блога

Поделиться:

Нужна разработка или поддержка проекта?

Разрабатываем веб-сервисы и мобильные приложения, дорабатываем и поддерживаем существующие проекты. Расскажите о задаче — предложим решение.