Библиотека CLI

Библиотека CLI CodeIgniter упрощает создание интерактивных скриптов командной строки, включая:

• Запрос дополнительной информации у пользователя
• Вывод текста с разными цветами в терминал
• Звуковые сигналы (будьте любезны!)
• Отображение полос прогресса во время длительных задач
• Перенос длинных строк текста для отображения в окне.

• Инициализация класса
• Получение ввода от пользователя
• Вывод обратной связи

Инициализация класса

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

<?php

namespace App\Controllers;

use CodeIgniter\CLI\CLI;

class MyController extends \CodeIgniter\Controller
{
    // ...
}

Класс автоматически инициализируется при первом загрузке файла.

Получение ввода от пользователя

Иногда вам нужно запросить у пользователя дополнительную информацию. Возможно, они не предоставили необязательные аргументы командной строки, или скрипт обнаружил существующий файл и требует подтверждения перед перезаписью. Это обрабатывается с помощью метода prompt() или promptByKey().

Вы можете задать вопрос, передав его в качестве первого параметра:

$color = CLI::prompt('What is your favorite color?');

Вы можете указать значение по умолчанию, которое будет использоваться, если пользователь просто нажмет Enter, передав значение по умолчанию во втором параметре:

$color = CLI::prompt('What is your favorite color?', 'blue');

Вы можете ограничить допустимые ответы, передав массив разрешенных ответов в качестве второго параметра:

$overwrite = CLI::prompt('File exists. Overwrite?', ['y','n']);

Наконец, вы можете передать правила валидации для ввода ответа в качестве третьего параметра:

$email = CLI::prompt('What is your email?', null, 'required|valid_email');

Правила валидации также можно записать в формате массива:

$email = CLI::prompt('What is your email?', null, ['required', 'valid_email']);

promptByKey()

Предварительно определенные ответы (варианты) для prompt иногда требуют описания или слишком сложны для выбора по их значению. promptByKey() позволяет пользователю выбирать вариант по его ключу, а не по его значению:

$fruit = CLI::promptByKey('These are your choices:', ['The red apple', 'The plump orange', 'The ripe banana']);

//These are your choices:
//  [0]  The red apple
//  [1]  The plump orange
//  [2]  The ripe banana
//
//[0, 1, 2]:

Также возможны именованные ключи:

$fruit = CLI::promptByKey(['These are your choices:', 'Which would you like?'], [
    'apple' => 'The red apple',
    'orange' => 'The plump orange',
    'banana' => 'The ripe banana'
]);

//These are your choices:
//  [apple]   The red apple
//  [orange]  The plump orange
//  [banana]  The ripe banana
//
//Which would you like? [apple, orange, banana]:

Наконец, вы можете передать правила валидации для ввода ответа в качестве третьего параметра, при этом допустимые ответы автоматически ограничиваются предоставленными вариантами.

Вывод обратной связи

write()

Для предоставления обратной связи пользователю предоставляется несколько методов. Это может быть как простая обновление состояния, так и сложная таблица информации, которая отображается в окне терминала пользователя. В основе этого лежит метод write(), который принимает строку для вывода в качестве первого параметра:

CLI::write('The rain in Spain falls mainly on the plains.');

Вы можете изменить цвет текста, передав имя цвета в качестве второго параметра:

CLI::write('File created.', 'green');

Это можно использовать для различения сообщений по состоянию или создания «заголовков» с использованием другого цвета. Вы даже можете задать цвета фона, передав имя цвета в качестве третьего параметра:

CLI::write('File overwritten.', 'light_red', 'dark_gray');

Доступны следующие цвета переднего плана:

• черный
• темно-серый
• синий
• темно-синий
• светло-синий
• зеленый
• светло-зеленый
• голубой
• светло-голубой
• красный
• светло-красный
• фиолетовый
• светло-фиолетовый
• светло-желтый
• желтый
• светло-серый
• белый

И меньшее количество доступно в качестве цветов фона:

• черный
• синий
• зеленый
• голубой
• красный
• желтый
• светло-серый
• пурпурный

print()

Функция print идентична методу write(), за исключением того, что она не форсирует перевод строки ни перед, ни после. Вместо этого она выводит его на экран в текущей позиции курсора. Это позволяет выводить несколько элементов в одной строке из разных вызовов. Это особенно полезно, когда вы хотите показать статус, выполнить действие, а затем вывести «Готово» в одной строке:

for ($i = 0; $i <= 10; $i++) {
    CLI::print($i);
}

color()

В то время как команда write() запишет одну строку в терминал, завершив её символом EOL, вы можете использовать метод color() для создания фрагмента строки, который можно использовать аналогичным образом, но который не будет форсировать EOL после вывода. Это позволяет создавать несколько выводов в одной строке. Или, чаще, вы можете использовать его внутри метода write() для создания строки другого цвета внутри:

CLI::write("fileA \t". CLI::color('/path/to/file', 'white'), 'yellow');

В этом примере в окно будет выведена строка с fileA жёлтым цветом, за которым следует табуляция, а затем /path/to/file белым текстом.

error()

Если вам нужно вывести ошибки, используйте соответствующий метод error(). Это записывает текст светло-красного цвета в STDERR, а не в STDOUT, как write() и color(). Это может быть полезно, если у вас есть скрипты, отслеживающие ошибки, чтобы они не должны были просматривать всю информацию, только фактические сообщения об ошибках. Вы используете его так же, как и метод write().

CLI::error('Cannot write to file: ' . $file);

wrap()

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

CLI::color("task1\t", 'yellow');
CLI::wrap("Some long description goes here that might be longer than the current window.");

По умолчанию строка будет переноситься на новую строку в соответствии с шириной терминала. В настоящее время Windows не предоставляет способ определить размер окна, поэтому мы используем значение по умолчанию в 80 символов. Если вы хотите ограничить ширину чем-то более коротким, что вы можете быть уверены, что оно поместится в окне, передайте максимальную длину строки в качестве второго параметра. Это позволит разбить строку на ближайшие границы слов, чтобы слова не разрывались.

// Wrap the text at max 20 characters wide
CLI::wrap($description, 20);

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

$titles = [
    'task1a',
    'task1abc',
];
$descriptions = [
    'Lorem Ipsum is simply dummy text of the printing and typesetting industry.',
    "Lorem Ipsum has been the industry's standard dummy text ever since the",
];

// Determine the maximum length of all titles
// to determine the width of the left column
$maxlen = max(array_map('strlen', $titles));

for ($i = 0; $i < count($titles); $i++) {
    CLI::write(
        // Display the title on the left of the row
        substr(
            $titles[$i] . str_repeat(' ', $maxlen + 3),
            0,
            $maxlen + 3
        ) .
        // Wrap the descriptions in a right-hand column
        // with its left side 3 characters wider than
        // the longest item on the left.
        CLI::wrap($descriptions[$i], 40, $maxlen + 3)
    );
}

Это создаст нечто подобное:

task1a     Lorem Ipsum is simply dummy
           text of the printing and
           typesetting industry.
task1abc   Lorem Ipsum has been the
           industry's standard dummy
           text ever since the

newLine()

Метод newLine() отображает пустую строку пользователю. Он не принимает никаких параметров:

CLI::newLine();

clearScreen()

Вы можете очистить текущее окно терминала с помощью метода clearScreen(). В большинстве версий Windows это просто вставит 40 пустых строк, так как Windows не поддерживает эту функцию. Интеграция bash в Windows 10 должна изменить это:

CLI::clearScreen();

showProgress()

Если у вас есть длительная задача, с которой вы хотите держать пользователя в курсе прогресса, вы можете использовать метод showProgress(), который отображает что-то вроде следующего:

[####......] 40% Complete

Этот блок анимирован на месте для очень приятного эффекта.

Для его использования передайте текущий шаг в качестве первого параметра, а общее количество шагов – в качестве второго. Процент выполнения и длина отображения будут определены на основе этого числа. Когда вы закончите, передайте false в качестве первого параметра, и полоса прогресса будет удалена.

$totalSteps = count($tasks);
$currStep   = 1;

foreach ($tasks as $task) {
    CLI::showProgress($currStep++, $totalSteps);
    $task->run();
}

// Done, so erase it...
CLI::showProgress(false);

table()

$thead = ['ID', 'Title', 'Updated At', 'Active'];
$tbody = [
    [7, 'A great item title', '2017-11-15 10:35:02', 1],
    [8, 'Another great item title', '2017-11-16 13:46:54', 0]
];

CLI::table($tbody, $thead);

+----+--------------------------+---------------------+--------+
| ID | Title                    | Updated At          | Active |
+----+--------------------------+---------------------+--------+
| 7  | A great item title       | 2017-11-16 10:35:02 | 1      |
| 8  | Another great item title | 2017-11-16 13:46:54 | 0      |
+----+--------------------------+---------------------+--------+

wait()

Ожидает определённое количество секунд, при желании показывая сообщение ожидания и ожидая нажатия клавиши.

// wait for specified interval, with countdown displayed
CLI::wait($seconds, true);

// show continuation message and wait for input
CLI::wait(0, false);

// wait for specified interval
CLI::wait($seconds, false);