Настраиваемые команды CLI

Хотя возможность использования команд CLI, как и любых других маршрутов, удобна, вы можете столкнуться с ситуациями, когда вам нужно немного иное. Именно для таких случаев предназначены команды CLI. Они представляют собой простые классы, для которых не нужно определять маршруты, что делает их идеальными для создания инструментов, которые разработчики могут использовать для упрощения своей работы, будь то обработка миграций или заполнение баз данных, проверка статуса cron-заданий или даже создание настраиваемых генераторов кода для вашей компании.

• Выполнение команд
  • Вызов команд
• Использование команды справки
• Создание новых команд
  • Расположение файлов
  • Пример команды
• BaseCommand

Выполнение команд

Команды выполняются из командной строки в корневом каталоге. В том же, где находятся каталоги /app и /system. Предоставлен настраиваемый скрипт spark, который используется для запуска любых команд CLI:

> php spark

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

> php spark migrate

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

> php spark db:seed DevUserSeeder

Вы всегда можете передать --no-header для подавления вывода заголовка, что полезно для анализа результатов:

> php spark cache:clear --no-header

Для всех команд, предоставляемых CodeIgniter, если вы не предоставите необходимые аргументы, вам будет предложено ввести информацию, необходимую для их корректного выполнения:

> php spark migrate:version
> Version?

Вызов команд

Команды также могут быть запущены из вашего собственного кода. Это чаще всего делается внутри контроллера для задач cron, но они могут быть использованы в любое время. Для этого используется функция command(). Эта функция всегда доступна.

echo command('migrate:create TestMigration');

Единственным аргументом является строка с вызываемой командой и её параметрами. Она выглядит точно так же, как при вызове из командной строки.

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

Использование команды справки

Получить справку по любой команде CLI можно, используя команду справки следующим образом:

> php spark help db:seed

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

Создание новых команд

Вы можете очень легко создать новые команды для использования в своём собственном разработке. Каждый класс должен находиться в отдельном файле, должен расширять CodeIgniter\CLI\BaseCommand, и реализовывать метод run().

Следующие свойства должны быть использованы для включения в список команд CLI и для добавления функциональности справки к вашей команде:

• $group: строка, описывающая группу, к которой относится команда при перечислении команд. Например: Database
• $name: строка, описывающая имя команды. Например: migrate:create
• $description: строка, описывающая команду. Например: Creates a new migration file.
• $usage: строка, описывающая использование команды. Например: migrate:create [name] [options]
• $arguments: массив строк, описывающих каждый аргумент команды. Например: 'name' => 'The migration file name'
• $options: массив строк, описывающих каждый параметр команды. Например: '-n' => 'Set migration namespace'

Описание справки будет автоматически сгенерировано в соответствии с вышеуказанными параметрами.

Расположение файлов

Команды должны храниться в каталоге с именем Commands. Однако этот каталог может находиться в любом месте, которое может найти Автозагрузчик. Это может быть /app/Commands или каталог, в котором вы храните команды для использования во всех проектах, например, Acme/Commands.

Пример команды

Давайте рассмотрим пример команды, единственной функцией которой является предоставление основной информации о самом приложении в демонстрационных целях. Начните с создания нового файла в /app/Commands/AppInfo.php. Он должен содержать следующий код:

<?php

namespace App\Commands;

use CodeIgniter\CLI\BaseCommand;
use CodeIgniter\CLI\CLI;

class AppInfo extends BaseCommand
{
    protected $group       = 'demo';
    protected $name        = 'app:info';
    protected $description = 'Displays basic application information.';

    public function run(array $params)
    {
        // ...
    }
}

Если вы выполните команду list, вы увидите новую команду, перечисленную в своей собственной demo группе. Если вы внимательно посмотрите, вы увидите, как это работает довольно легко. Свойство $group просто указывает, как организовать эту команду со всеми другими существующими командами, указывая, под каким заголовком ее отображать.

Свойство $name – это имя, по которому эту команду можно вызывать. Единственное требование состоит в том, что оно не должно содержать пробелов, и все символы должны быть допустимыми в самой командной строке. Однако по соглашению команды пишутся строчными буквами, а дальнейшая группировка команд осуществляется с использованием двоеточия с самим именем команды. Это помогает предотвратить столкновения имен между несколькими командами.

И последнее свойство, $description, – это короткая строка, отображаемая в команде list и описывающая, что делает команда.

run()

Метод run() — это метод, который вызывается при выполнении команды. Массив $params – это список любых аргументов CLI после имени команды, доступных вам. Если строка CLI была:

> php spark foo bar baz

Тогда foo — это имя команды, и массив $params будет:

$params = ['bar', 'baz'];

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

Наша демонстрационная команда может иметь метод run примерно такой:

public function run(array $params)
{
    CLI::write('PHP Version: '. CLI::color(phpversion(), 'yellow'));
    CLI::write('CI Version: '. CLI::color(\CodeIgniter\CodeIgniter::CI_VERSION, 'yellow'));
    CLI::write('APPPATH: '. CLI::color(APPPATH, 'yellow'));
    CLI::write('SYSTEMPATH: '. CLI::color(SYSTEMPATH, 'yellow'));
    CLI::write('ROOTPATH: '. CLI::color(ROOTPATH, 'yellow'));
    CLI::write('Included files: '. CLI::color(count(get_included_files()), 'yellow'));
}

BaseCommand

Класс BaseCommand, который должны расширять все команды, имеет несколько полезных вспомогательных методов, с которыми вам следует ознакомиться при создании собственных команд. Также в нем доступен Журнал в $this->logger.

CodeIgniter\CLI\BaseCommand

call(string $command[, array $params = []])

Параметры:	$command (string) – Имя другой команды для вызова. $params (array) – Дополнительные аргументы командной строки, доступные для этой команды.

Этот метод позволяет запускать другие команды во время выполнения текущей команды:

$this->call('command_one');
$this->call('command_two', $params);

showError(Throwable $e)

Параметры:	$e (Throwable) – Исключение для использования в сообщениях об ошибках.

Вспомогательный метод для поддержания согласованного и понятного вывода ошибок в командной строке:

try {
    . . .
} catch (\Exception $e) {
    $this->showError($e);
}

showHelp()

Метод для показа справки по команде: (использование, аргументы, описание, параметры)

getPad($array, $pad)

Параметры:	$array (array) – Массив $key => $value. $pad (integer) – Отступы.

Метод для расчета отступов для вывода массива $key => $value. Отступы могут быть использованы для вывода отформатированной таблицы в командной строке:

$pad = $this->getPad($this->options, 6);

foreach ($this->options as $option => $description) {
    CLI::write($tab . CLI::color(str_pad($option, $pad), 'green') . $description, 'yellow');
}

// Output will be
-n                  Set migration namespace
-r                  override file