Fluent CLI в PHP: Создаём консольные команды с __call и никаких танцев с бубном

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

Именно для таких случаев была разработана библиотека PhpFluentConsole — простое и гибкое решение для работы с командной строкой, с поддержкой кодировок и множеством полезных фич для работы с выводом команд.

Зачем нужна эта библиотека?

PhpFluentConsole не заменяет существующие библиотеки, а выступает как легковесная основа для гибкого построения CLI-запросов. Её цель — упростить интеграцию системных команд без необходимости изучать объёмную документацию или вникать в сложный API.

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

Преимущества использования

Гибкость и удобство:

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

$cli = new ConsoleRunner()      ->setCommand('echo')      ->addKey('Hello, World!') 

Поддержка кодировок:

Для работы с кириллицей и другими символами, библиотека включает поддержку различных кодировок, таких как CP866, UTF-8, CP1251, и других. Это особенно важно при работе в windows-среде, где часто возникают проблемы с выводом текста в стандартных кодировках, что так же может затруднить обработку вывода с помощью регулярных выражений.
Пример:

$cli = new ConsoleRunner()      ->setCommand('dir')      ->encoding('866') 

Обработка ошибок и кодов возврата:

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

if (!$cli->run()) {     echo "Ошибка выполнения команды!" . $cli->getReturnCode(); } 

Поиск совпадений по паттернам:

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

if ($cli->run()) {    $matches = $cli->getMatches('/Error/');    print_r($matches); } 

Стандартный вывод:

Если нам просто нужно получить массив строк.
Пример:

if ($cli->run()) {    print_r($cli->getOutput()); } 

Установка

composer require mikhailovlab/php-fluent-console 

Описание методов

Устанавливает команду для выполнения.

public function setCommand(string $cmd): self 

Добавляет аргумент или часть команды.

public function addKey(string $key): self 

Устанавливает кодировку для вывода. Например, ‘866’ для отображения кириллицы в Windows.

public function encoding(?string $encoding = null): self 

Устанавливает флаг, что нужно выполнить обратную конвертацию кодировки. Метод полезен для возврата вывода в исходной кодировке для работы с cmd.

public function decoding(): self 

Возвращает текущую команду.

public function getCommand(): string 

Выполняет команду и возвращает true, если код возврата равен 0.

public function run(): bool 

Возвращает вывод после выполнения команды.

public function getOutput(): array 

Возвращает код возврата выполнения команды.

public function getReturnCode(): int 

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

public function hasError(string $pattern): bool 

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

public function getMatches(string|array $patterns): array 

Примеры

Проверять функционал будем на примере фреймворка Laravel 11, но так же можно использовать любой другой, это непринципиально:

Пример 1: Получаем IP адрес в операционной системе windows

$cli = new ConsoleRunner()      ->setCommand('ipconfig')      ->addKey('/all')      ->encoding('866'); //ожидаем вывод с кириллицей  if ($cli->run()) {    dd($cli->getOutput()); } 

Вывод:

array:59 [▼ // app\Http\Controllers\TestController.php:21   0 => ""   1 => "Настройка протокола IP для Windows"   2 => ""   3 => "   Имя компьютера  . . . . . . . . . : DESKTOP-HRTB4N9"   4 => "   Основной DNS-суффикс  . . . . . . :"   5 => "   Тип узла. . . . . . . . . . . . . : Гибридный"   6 => "   IP-маршрутизация включена . . . . : Нет"   7 => "   WINS-прокси включен . . . . . . . : Нет"   8 => "   Порядок просмотра суффиксов DNS . : lan"   9 => ""   10 => "Адаптер Ethernet Ethernet 2:" ... 

Кириллица отображается корректно, можно двигаться дальше.

Пример 2: Получаем список контейнеров с электронными подписями

$cli = new ConsoleRunner()      ->setCommand('csptest')      ->addKey('-keyset')      ->addKey('-enum_cont')      ->addKey('-verifycontext')      ->addKey('-fqcn');  if ($cli->run()) {     dd($cli->getMatches('#\\\\.*#')); }  $pattern = '/\[ErrorCode:\s*(0x[0-9A-Fa-f]+)\]/'; dd('Error code: ' . $cli->getMatches($pattern)[0]); 

Вывод:

array:1 [▼ // app\Http\Controllers\TestController.php:23   0 => "\\.\REGISTRY\d58fe6c13-d917-2a53-8e9c-8c4b8158220-test" ] 

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

Пример 3: Расширяем базовый класс

Мы можем наследоваться от базового класса ConsoleRunner и вместо указания методов через addKey, вызывать их динамически, используя магический метод __call. Как правило, в консольных утилитах мы можем получить список всех доступных методов и аргументов используя ключ -help и добавить их в массив, что бы исключить ошибки, т.к. при несовпадении будет выброшено исключение.

class customRunner extends ConsoleRunner {     private $methods = [         'keyset',         'enum_cont',         'verifycontext',         'fqcn'     ];      public function __call(string $name, array $arguments): self     {         if (in_array($name, $this->methods)) {             $this->addKey('-' . $name);             if (!empty($arguments)) {                 foreach ($arguments as $arg) {                     $this->addKey((string) $arg);                 }             }             return $this;         }         throw new \BadMethodCallException("Method $name is not supported");     } }  try{     $cli = new customRunner()          ->setCommand('csptest')          ->keyset()          ->enum_cont()           ->verifycontext()          ->fqcn();      if ($cli->run()) {         dd($cli->getMatches('#\\\\.*#'));     }     $pattern = '/\[ErrorCode:\s*(0x[0-9A-Fa-f]+)\]/';    dd('Error code: ' . $cli->getMatches($pattern)[0]);  }catch (Exception $e){     dd($e->getMessage()); } 

Вывод:

array:1 [▼ // app\Http\Controllers\TestController.php:23   0 => "\\.\REGISTRY\d58fe6c13-d917-2a53-8e9c-8c4b8158220-test" ] 

Мы можем перенести логику и обработку вывода в отдельные методы, что бы сделать код еще более лаконичным.

try{     $containers = new customRunner()                 ->getContainers()                 ->run();      dd($containers);      }catch (Exception $e){     dd($e->getMessage()); } 

Таким образом мы можем наследоваться от базового класса и создавать свои классы-обертки, в которых будем описывать методы и обрабатывать вывод.

Заключение

PhpFluentConsole — это удобный и гибкий инструмент для работы с командной строкой. Он позволяет строить команды через простой и понятный интерфейс, поддерживает работу с кодировками, предоставляет возможности для обработки ошибок и извлечения данных из вывода команд. Библиотека является отличной основой для создания более сложных решений или даже для разработки других библиотек на её основе, таких как CryptoProBuilder, о которой я расскажу в следующей статье.

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

Ссылка на GitHub
Ссылка на Packagist