Команди консолі
Дата оновлення перекладу 2024-06-07
Команди консолі
Фреймворк Symfony надає безліч команд через скрипт bin/console
(наприклад,
добре відома команда bin/console cache:clear
). Ці команди створюються за
допомогою Компонента Console. Ви можете також
використовувати його для створення власних команд.
Running Commands
Each Symfony application comes with a large set of commands. You can use
the list
command to view all available commands in the application:
1 2 3 4 5 6 7 8 9 10 11 12 13
$ php bin/console list
...
Доступні команди:
about Відобразити інформацію про поточний проект
completion Скинути сценарій завершення роботи оболонки
help Відобразити допомогу для команди
list Перечислити команди
assets
assets:install Встановити веб-ресурси пакета під публічним каталогом
cache
cache:clear Очистити кеш
...
Note
list
є командою за замовчуванням, тому це те саме, що й запуск php bin/console
.
Якщо ви знайшли потрібну вам команду, ви можете запустити її з опцією --help
,
щоб переглянути документацію команди:
1
$ php bin/console assets:install --help
Note
--help
- одна з вбудованих глобальних опцій компонента Console,
які доступні для всіх команд, у тому числі тих, які ви можете створити.
Щоб дізнатися про них більше, ви можете прочитати
цей розділ .
APP_ENV і APP_DEBUG
Консольні команди виконуються у середовищі , визначеному у
змінній APP_ENV
файлу .env
, за замовчуванням - dev
. Він також зчитує
значення APP_DEBUG
, щоб вмикати і вимикати режим "налагодження" (за замовчуванням
- 1
, тобто увімкнено).
Щоб запустити команду в іншому середовищі або режимі налагодження, відредагуйте значення
APP_ENV
і APP_DEBUG
.
1 2
# очищує кеш для середовища prod
$ APP_ENV=prod php bin/console cache:clear
Заповнення консолі
Якщо ви використовуєте оболонку Bash, Zsh або Fish, ви можете встановити скрипт завершення Symfony, щоб отримати автозаповнення при друкуванні команд в терміналі. Всі команди підтримують заповнення імені та опції, а деякі можуть навіть заповнювати значення.
Спочатку вам потрібно встановити скрипт заповнення один раз. Виконайте
bin/console completion --help
для інструкцій з установки для вашої оболонки.
Note
При використанні Bash, переконайтеся, що ви встановили та налаштували пакет
"заповнення bash" для вашої ОС (зазвичай називається bash-completion
).
Після установки та перезапуску вашого терміналу, ви готові до використання заповнення (за замовчуванням, шляхом натискання клавіши Tab).
Tip
Багато інструментів PHP побудовані з використанням компонента Symfony Console (наприклад, Composer, PHPstan та Behat). Якщо вони використовують версію 5.4 або вище, ви також можете встановити їх скрипт заповнення, щоб включити заповнення консолі:
1 2
$ php vendor/bin/phpstan completion --help
$ composer completion --help
Створення команди
Команди визначаються в класах, що розширюють Command. Наприклад, ви можете захотіти, щоб команда створювала користувача:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
// src/Command/CreateUserCommand.php
namespace App\Command;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
// імʼя команди - це те, що користувачі друкують після "php bin/console"
#[AsCommand(name: 'app:create-user')]
class CreateUserCommand extends Command
{
protected function execute(InputInterface $input, OutputInterface $output): int
{
// ... введіть тут код, щоб створити користувача
// цей метод має повернути ціле число з "кодом завершення"
// команди. Ви також можете використовувати ці константи, щоб зробити код більш читаним
// повернути це, якщо при виконанні команди не було проблем
// (рівноцінно поверненню int(0))
return Command::SUCCESS;
// або повернути це, якщо під час виконання виникла помилка
// (рівноцінно поверненню int(1))
// return Command::FAILURE;
// або повернути це, щоб вказати на неправильне використання команди, наприклад, невалідні опції
// або відсутні аргументи (рівноцінно поверненню int(2))
// return Command::INVALID
}
}
Конфігурація команди
Ви можете за бажанням визначити опис, повідомлення допомоги і
аргументи та опції введення by overriding the
configure()
method:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
// src/Command/CreateUserCommand.php
// ...
class CreateUserCommand extends Command
{
// ...
protected function configure(): void
{
$this
// опис команди, що відображається при виконанні "php bin/console list"
->setDescription('Creates a new user.')
// допомога команди, відображена при запуску команди з опцією "--help"
->setHelp('This command allows you to create a user...')
;
}
}
Tip
Визначення статичної властивості $defaultDescription
замість використання методу
setDescription()
дозволяє отримати описс команди без інстанціювання її класу. Це
робить виконання команди php bin/console list
значно швидшим.
Якщо ви хочете завжди виконувати команду list
швидко, додайте до неї опцію --short
(php bin/console list --short
). Це запобігатиме інстанціюванню класів команди, але
не відображатиме жодного опису для команд, які використовують метод setDescription()
замість статичної властивості.
Метод configure()
викликається автоматично наприкінці конструктору команди.
Якщо ваша команда визначає свій конструктор, спочатку встановіть властивості та
викликчте батьківський конструктор для того, щоб ці властивості стали доступні
в методі configure()
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
// ...
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputArgument;
class CreateUserCommand extends Command
{
// ...
public function __construct(bool $requirePassword = false)
{
// гарною практикою вважається викликати спочатку батьківський конструктор, а
// потім встановлювати нові властивості. Це не спрацює у даному випадку, тому
// що configure() потребує встановлених властивостей в конструкторі
$this->requirePassword = $requirePassword;
parent::__construct();
}
protected function configure(): void
{
$this
// ...
->addArgument('password', $this->requirePassword ? InputArgument::REQUIRED : InputArgument::OPTIONAL, 'User password')
;
}
}
Реєстрація команди
Ви можете зареєструвати команду, додавши до неї атрибут AsCommand
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
// src/Command/CreateUserCommand.php
namespace App\Command;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
#[AsCommand(
name: 'app:create-user',
description: 'Creates a new user.',
hidden: false,
aliases: ['app:add-user']
)]
class CreateUserCommand extends Command
{
// ...
}
Якщо ви не можете використати PHP атрибути, зареєструйте команду як сервіс та
тегуйте її тегом console.command
. Якщо ви
використовуєте конфігурацію services.yaml за замовчуванням ,
це вже зроблено за вас, завдяки автоконфігурації .
Виконання команди
Після конфігурації та реєстрації команди ви можете виконати її в терміналі:
1
$ php bin/console app:create-user
Як ви могли очікувати, ця команда нічого не робить, так як ви поки не прописали ніякої логіки.
Додайте свою логіку в метод execute()
.
Виведення консолі
Метод execute()
має доступ до потоку виведення для того, щоб писати повідомлення
в консоль:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
// ...
protected function execute(InputInterface $input, OutputInterface $output)
{
// виводить багато рядків в консоль (додаючи "\n" наприкінці кожного рядку)
$output->writeln([
'User Creator',
'============',
'',
]);
// значення, повернене someMethod() може бути ітератором (https://secure.php.net/iterator),
// який генерує та повертає повідомлення за допомогою ключового слова PHP 'yield'
$output->writeln($this->someMethod());
// виводить повідомлення з наступним "\n"
$output->writeln('Ух ти!');
// виводить повідомлення, не додаючи "\n" наприкінці рядку
$output->write('Ви вже майже');
$output->write('створили користувача.');
}
Тепер, спробуйте виконати команду:
1 2 3 4 5 6
$ php bin/console app:create-user
User Creator
============
Ух ти!
Ви вже майже створили користувача.
Розділи виведення
Звичайне виведення консолі може бути розділене на декілька незалежних регіонів під назвою "секції виведення". Створіть одну або декілька таких секцій, коли вам потрібно очистити та перезаписати інформацію, що виводиться.
Секції створюються методом ConsoleOutput::section(), який повертає екземпляр ConsoleSectionOutput:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
// ...
use Symfony\Component\Console\Output\ConsoleOutputInterface;
class MyCommand extends Command
{
protected function execute(InputInterface $input, OutputInterface $output): int
{
if (!$output instanceof ConsoleOutputInterface) {
throw new \LogicException('This command accepts only an instance of "ConsoleOutputInterface".');
}
$section1 = $output->section();
$section2 = $output->section();
$section1->writeln('Hello');
$section2->writeln('World!');
sleep(1);
// Виведення відображає "Hello\nWorld!\n"
// overwrite() замінює весь існуючий зміст секції заданим змістом
$section1->overwrite('Goodbye');
// Тепер виведення відображає "Goodbye\nWorld!\n"
// clear() видаляє весь зміст розділу...
$section2->clear();
// Тепер виведення відображає "Goodbye\n"
// ...але ви також можете видалити задану кількість рядків
// (цей приклад видаляє два останні рядки секції)
$section1->clear(2);
// Тепер виведення абсолютно пусте!
// встановлення максимальної висоти розділу змусить нові рядки замінити старі
$section1->setMaxHeight(2);
$section1->writeln('Line1');
$section1->writeln('Line2');
$section1->writeln('Line3');
return Command::SUCCESS;
}
}
Note
Новий рядок додається автоматично при відображенні інформації в секції.
Секції виведення дозволяють вам маніпулювати виведенням консолі складними способами, наприклад, відображення декількох прогресбарів , які оновлюються незалежно одне від одного, та додавання рядків в таблиці , які вже були виведені.
Caution
Термінали дозволяють перезаписувати лише видимий зміст, тому ви повинні враховувати висоту консолі при спробі запису/перезапису змісту розділу.
Введення консолі
Використовуйте опції або аргументи введення, щоб передати інформацію в команду:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
use Symfony\Component\Console\Input\InputArgument;
// ...
protected function configure(): void
{
$this
// configure an argument
->addArgument('username', InputArgument::REQUIRED, 'The username of the user.')
// ...
;
}
// ...
public function execute(InputInterface $input, OutputInterface $output): int
{
$output->writeln([
'User Creator',
'============',
'',
]);
// отримати значення аргументу, використовуючи getArgument()
$output->writeln('Username: '.$input->getArgument('username'));
return Command::SUCCESS;
}
Тепер ви можете передати ім'я користувача в команду:
1 2 3 4 5
$ php bin/console app:create-user Wouter
User Creator
============
Username: Wouter
See also
Дивіться Введення консолі (аргументи та опції), щоб дізнатися більше інформації про опції та аргументи консолі.
Отримання сервісів з сервіс-контейнера
Щоб дійсно створити нового користувача, команда має отримати доступ до деяких
сервісів. Так як ваша команда вже зареєстрована як
сервіс, ви можете використовувати нормальне впровадження залежності. Уявіть, що
у вас є сервіс App\Service\UserManager
, до якого ви хочете отримати доступ:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
// ...
use App\Service\UserManager;
use Symfony\Component\Console\Command\Command;
class CreateUserCommand extends Command
{
public function __construct(
private UserManager $userManager,
){
parent::__construct();
}
// ...
protected function execute(InputInterface $input, OutputInterface $output): int
{
// ...
$this->userManager->create($input->getArgument('username'));
$output->writeln('User successfully generated!');
return Command::SUCCESS;
}
}
Життєвий цикл команди
Команди мають три методи життєвого циклу, які активуються при виконанні команди:
- initialize() (необов'язковий)
-
Цей метод виконується до методів
interact()
таexecute()
. Його головна ціль - ініціалізувати змінні, які використовуються в інших методах команди. - interact() (необов'язковий)
-
Цей метод виконується після
initialize()
і доexecute()
. Його ціль - перевірка наявності всіх опцій/аргументів, та запитати у користувача значення в діалоговому режимі. Це останнє місце, де ви можете запитати відсутні опції/аргументи. Після цієї команди, відсутні опції/аргументи будуть призводити до помилки. Зауважте, що його не буде викликано, якщо команду буде запущено без взаємодії (наприклад, при передачі прапорця глобальної опції--no-interaction
). - execute() (обов'язковий)
-
Цей метод виконується після
interact()
таinitialize()
. Він містить логіку, яку ви хочете виконати за допомогою команди і він повинен повертати ціле число, яке буде використано в якості коду повернення команди .
Тестування команд
Symfony надає декілька інструментів, щоб допомогти вам тестувати ваші команди. Найкорисніший - це клас CommandTester. Він використовує спеціальні класи введення та виведення, щоб полегшити тестування без справжньої консолі:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
// tests/Command/CreateUserCommandTest.php
namespace App\Tests\Command;
use Symfony\Bundle\FrameworkBundle\Console\Application;
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
use Symfony\Component\Console\Tester\CommandTester;
class CreateUserCommandTest extends KernelTestCase
{
public function testExecute(): void
{
self::bootKernel();
$application = new Application(self::$kernel);
$command = $application->find('app:create-user');
$commandTester = new CommandTester($command);
$commandTester->execute([
// передати аргументи хелперу
'username' => 'Wouter',
// додати до ключа префікс з двома дефісами при передаванні опцій,
// наприклад: '--some-option' => 'option_value',
// використати дужки для тестування значення масиву,
// наприклад: '--some-option' => ['option_value'],
]);
$commandTester->assertCommandIsSuccessful();
// виведення команди в консолі
$output = $commandTester->getDisplay();
$this->assertStringContainsString('Username: Wouter', $output);
// ...
}
}
Якщо ви використовуєте застосунок однієї команди,
викличте setAutoExit(false)
, щоб отримати результат комнади в CommandTester
.
Tip
Ви також можете тестувати всю консоль додатку, використовуючи ApplicationTester.
Caution
При тестуванні команд з використанням класу CommandTester
, події консолі не
запускаються. Якщо вам потрібно протестувати ці події, використовуйте замість цього
ApplicationTester.
Caution
При тестуванні команд з використанням класу ApplicationTester, не забудьте відключити автоматичний вихід:
1 2 3 4
$application = new Application();
$application->setAutoExit(false);
$tester = new ApplicationTester($application);
Caution
При тестуванні опцій команди InputOption::VALUE_NONE
, ви повинні передати їм порожнє
значення:
1 2
$commandTester = new CommandTester($command);
$commandTester->execute(['--some-option' => '']);
Note
При використанні компонента Console в окремому проекті, використовуйте
Symfony\\Component\\Console\\Application
та розширте звичайний \PHPUnit\Framework\TestCase
.
Під час тестування ваших команд може бути корисно зрозуміти, як ваша команда реагує на різні налаштування, такі як ширина і висота терміналу, або навіть на режим кольору, який використовується. Ви маєте доступ до такої інформації завдяки класу Terminal:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
use Symfony\Component\Console\Terminal;
$terminal = new Terminal();
// отримує кількість доступних рядків
$height = $terminal->getHeight();
// отримує кількість доступних стовпців
$width = $terminal->getWidth();
// отримує режим кольору
$colorMode = $terminal->getColorMode();
// змінює режим кольору
$colorMode = $terminal->setColorMode(AnsiColorMode::Ansi24);
Ведення логів помилок команди
Кожен раз, коли під час виконання команди викликається виключення, Symfony додає
для нього повідомлення логу, включно з усією командою, що не працює. Крім того,
Symfony реєструє підписника подій, щоб слухати
подію ConsoleEvents::TERMINATE , і додає повідомлення
логу кожний раз, коли команда не закінчується кодом повернення 0
.
Використання подій та обробка сигналів
Під час виконання команди розгортається багато подій, одна з яких дозволяє реагувати на сигнали, докладніше читайте у цьому розділі.
Команди профілювання
Symfony дозволяє профілювати виконання будь-якої команди, в тому числі і вашої. По-перше,
переконайтеся, що увімкнено режим налагодження і
профілювальник. Потім додайте опцію --profile
під час запуску команди:
1
$ php bin/console --profile app:my-command
Symfony тепер збиратиме дані про виконання команд, що може бути корисним для налагодження помилок або перевірки інших проблем. Після завершення виконання команди, профіль буде доступний через веб-сторінку профілювальника.
Tip
Якщо ви запустите команду в багатослівному режимі (додавши опцію -v
), Symfony
покаже у виведенні посилання на профіль команди, на який можна клікнути (якщо ваш
термінал підтримує посилання). Якщо ви запустите її у багатослівному режимі
налагодження (-vvv
), ви також побачите час і пам'ять, витрачені командою.
Caution
Під час профілювання команди messenger:consume
з :doc:586f93526d8bcf76cb393383fcc345b8e4038b0f--no-resetfc2fd411fe89e208dce9027b46e3c29bcb38c447--limit`` для обробки лише декількох
повідомлень, щоб зробити профіль більш читабельним у профілювальнику.
Дізнайтеся більше
- Як викликати інші команди
- Як розфарбовувати та стилізувати виведення консолі
- Як викликати команду з контролера
- Як визначати команди, як сервіси
- Як приховувати консольні команди
- Введення консолі (аргументи та опції)
- Як зробити команди лінивого завантаження
- Запобігання багаторазовому виконанню консольної команди
- Як генерувати URL з консолі
- Як оформити консольну команду
- Рівні деталізації
Компонент Console також містить набір "помічників" - різних маленьких інструментів, здатних допомогти вам з різними завданнями:
- Помічник Question: дізнатися у користувача інформацію в діалоговому режимі
- Помічник Formatter: налаштувати розцвічування виведення
- Індикатор виконання: показати прогресбар
- Індикатор прогресу: відображає індикатор прогресу
- Таблиця: відобразити дані в табличній формі
- Помічник Debug Formatter: надає функції для виведення інформаціі
налагоджування при запуску зовнішньої програми
Помічник Process: дозволяє запускати процеси з використанням DebugFormatterHelper
Помічник Cursor: дозволяє маніпулювати курсором в терміналі