Download the PHP package fi1a/console without Composer

Консольные команды на PHP. Аргументы, опции и форматирование

Библиотека PHP для реализации команд и красивого форматирования текста в консоли.

Возможности:

• Команды получают автоматическую поддержку --help для вывода справки;
• Поддержка одной или нескольких команд;
• Возможность валидации (проверки) значений передаваемых в качестве аргументов и опций в команду;
• Цветовое оформление в консоли;
• Компоненты реализующие таблицы, списки, деревья и т.д.

Установка

Установить этот пакет можно как зависимость, используя Composer.

Dependency injection

Контейнер dependency injection из пакета fi1a/dependency-injection

Для интерфейсов, в контейнере dependency injection, доступны следующие определения:

• Fi1a\Console\IO\InputArgumentsInterface;
• Fi1a\Console\IO\FormatterInterface;
• Fi1a\Console\IO\ConsoleOutputInterface;
• Fi1a\Console\IO\InputInterface;
• Fi1a\Console\IO\InteractiveInputInterface;
• Fi1a\Console\Component\GroupComponent\GroupStyleInterface;
• Fi1a\Console\Component\GroupComponent\GroupComponentInterface;
• Fi1a\Console\Component\ListComponent\ListStyleInterface;
• Fi1a\Console\Component\ListComponent\ListComponentInterface;
• Fi1a\Console\Component\PaginationComponent\PaginationStyleInterface;
• Fi1a\Console\Component\PaginationComponent\PaginationComponentInterface;
• Fi1a\Console\Component\PanelComponent\PanelStyleInterface;
• Fi1a\Console\Component\PanelComponent\PanelComponentInterface;
• Fi1a\Console\Component\ProgressbarComponent\ProgressbarStyleInterface;
• Fi1a\Console\Component\ProgressbarComponent\ProgressbarComponentInterface;
• Fi1a\Console\Component\SpinnerComponent\SpinnerStyleInterface;
• Fi1a\Console\Component\SpinnerComponent\SpinnerComponentInterface;
• Fi1a\Console\Component\TableComponent\TableStyleInterface;
• Fi1a\Console\Component\TableComponent\TableComponentInterface;
• Fi1a\Console\Component\TreeComponent\TreeStyleInterface;
• Fi1a\Console\Component\TreeComponent\TreeComponentInterface;

Использование

Команды, аргументы и опции в консоли

Класс предоставляет удобный интерфейс для добавления команд и запуска приложения.

Команды

Команда должна реализовывать интерфейс . Вот пример простой команды.

В этом примере добавляется опция и аргумент в конструкторе команды. После запуска команды проверяется передана ли опция и если передана, выводит серверное время с указанным форматом . Если формат не передан, метод вернет значение указанное по умолчанию с помощью метода .

В метод вызываемый при запуске команды в качестве аргументов передается:

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

Использование опций и аргументов

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

• Опции передаются с помощью --name=value полного имени или -s value короткого кода;
• Аргументы передаются как строки, разделенные пробелами.

Запуск консольного приложения

Чтобы использовать приложение, нужно вызвать метод . Метод делает следующее:

• Анализирует параметр $argv для определения команды;
• Валидирует опции и аргументы;
• Осуществляет конфигурацию команды;
• Запускает команду на выполнение.

Запуск одной конкретной команды. Данный код запустит команду на выполнение:

Запуск нескольких команд, указанных в первом аргументе. Если передать в качестве первого аргумента название команды , будет запущена команда .

Список команд

Вызов скрипта, который имеет несколько команд без параметров или только с аргументом info, отобразит список доступных команд. Пример:

или

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

Отображение справки

Если вызвать команду с параметром --help (), можно увидеть следующую справку по команде:

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

Отображение ошибок

Допустим, вы вызываете пример :

Увидете следующее сообщение об ошибке:

Валидация осуществляется с помощью пакета fi1a/validation. Доступны все правила валидации.

• метод - правила валидации одного значения;
• метод - правила валидации множества значений.

Оформление

Цветовые схемы (палитра цветов консоли):

Доступны три цветовые схемы:

• ANSI (4-bit color);
• Extended (8-bit color);
• TrueColor (16.7 million).

Запустить пример с отображением палитры цветов

Вывод в консоль

Используя цвета в выводе консоли, вы можете оформить разные типы вывода (ошибки, заголовки, комментарии и т. д.).

Использование цветовых стилей

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

Пример с использованием контейнера:

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

• error;
• success;
• info;
• comment;
• question;
• notice.

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

Любой шестнадцатеричный цвет поддерживается для цветов схемы TrueColor. Кроме того, поддерживаются названные цвета, опредяемых константами интерфейса (, , ...).

Если терминал не поддерживает TrueColor или Extended, используется ближайший ANSI цвет.

Доступны параметры оформления: blink, bold, conceal, reverse, underscore. Вы можете установить цвет, фон и параметры непосредственно внутри тега. Поддерживается вложенность стилей.

Запустить пример с отображением форматированного вывода

Потоковый ввод из консоли

Чтение (ввод) из консоли осуществляется методом объекта класса .

Пример с использованием контейнера:

Интерактивный ввод из консоли

С помощью класса , можно добавить значения для чтения из консоли и получить последующий доступ к введенным значениям. С помощью метода добавляем значение для чтения из консоли. Также как для аргументов и опций, доступны валидаторы значений из пакета fi1a/validation

Пример с использованием контейнера:

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

Компоненты

Компонент панели

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

Пример с использованием контейнера:

Запустить пример с отображением панелей

Вы можете изменить стиль границы панели, задав одно из следующих значений:

• ascii;
• double;
• heavy;
• horizontals;
• rounded.

Запустить пример со стилями границ панели

Можно определить свои собственные стили границ, используя метод класса . Класс стиля границ должен реализовать интерфейс :

Компонент группы

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

Пример с использованием контейнера:

Запустить пример с группой панелей

Компонент списка

Для отображения списка служит компонент . Поддерживаются вложенные списки.

Пример с использованием контейнера:

Задать тип маркера можно с помощью метода класса стиля списка .

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

• upper-alpha - алфавитный список заглавных букв (A, B, C, D, E, …);
• square - в качестве маркера выступает квадрат;
• lower-alpha - алфавитный список (a, b, c, d, e, …);
• decimal-leading-zero - порядковый номер с лидирующим нулем (01, 02, 03, 04, 05, …);
• decimal - порядковый номер (1, 2, 3, 4, 5, …);
• circle - в качестве маркера выступает незакрашенный кружок;
• disc - в качестве маркера элементов списка выступает закрашенный кружок.

Запустить пример со списками

Можно определить свои собственные типы маркеров списков, используя метод класса . Класс типа маркера списка должен реализовать интерфейс :

Компонент постраничной навигации

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

Пример:

Пример с использованием контейнера:

Запустить пример c постраничной навигацией

Компонент Progressbar

При выполнении длительных команд, полезно отображать информацию о ходе выполнения.

Чтобы отобразить сведения о ходе выполнения, используйте :

Пример с использованием контейнера:

Используя метод , можно задать один из предустановленных шаблонов:

• short ();
• normal ();
• time ();
• memory ();
• full ().

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

Запустить пример c progressbar'ом

Компонент Spinner

Возможности:

• заголовок во время вращения;
• поддержка шаблона ();
• имеет метод ;
• различный внешний вид и возможность добавить свой spinner.

Внешний вид spinner'а:

• dots;
• line;
• growVertical;
• growHorizontal;
• bar.

Вы можете добавить свой spinner, используя метод класса . Добавляемый spinner должен реализовать интерфейс :

Пример:

Пример с использованием контейнера:

Запустить пример

Компонент таблицы

Класс предназначен для вывода табличных данных на терминал.

Чтобы отобразить таблицу, создайте объект , добавьте заголовоки с помощью и строки с помощью , а затем выведите на консоль методом :

Пример с использованием контейнера:

Если ширина таблицы не задана, то ширина колонок рассчитывается исходя из содержимого ячеек.

Свойства ячейки:

• value - значение;
• colspan - кол-во столбцов ячейки;
• style - стиль .

Вы можете установить стиль границы таблицы, задав одно из следующих значений c помощью метода объекта стиля :

• none;
• ascii;
• ascii_compact;
• double;
• double_compact;
• heavy;
• heavy_compact;
• horizontals;
• rounded;
• rounded_compact.

Запустить пример

Можно определить свои собственные стили границ, используя метод класса . Класс стиля границ должен реализовать интерфейс :

Компонент отображения дерева

Класс может генерировать древовидное представление в терминале. Дерево — отличный способ представления содержимого файловой системы или любых других иерархических данных.

Пример с использованием контейнера:

Вы можете установить стиль линии, задав одно из следующих значений c помощью метода объекта стиля :

• normal;
• double;
• heavy;
• ascii.

Запустить пример

Можно определить свои собственные стили линий, используя метод класса . Класс стиля линии должен реализовать интерфейс :