README

Данная библиотека предназначена для выполнения команд на удаленном сервере через протокол ssh2. Библиотека позволяет выполнять подключение к серверу, исполнять команды на сервере, создавать сложные сценарии исполнения с условными операторами, циклами, функциями.

Требования к установке

1. установленное расширение SSH2
2. минимальная версия PHP - 8.4

Установка

composer require yaroslam/ssh2

Документация

Подключение

Что бы инициализировать подключение к удаленному серверу необходимо создать экземпляр ConnectionInterface и обратиться к методу connect, передав в него $connectProperties и $connection, являющийся результатом выполнения функции ssh2_connect() модуля SSH2.

$connector = new UserPasswordConnection();
$connector->connect(ssh2_connect($_ENV['host'], 22), ['user' => $_ENV['host'], 'password' =>$_ENV['host']])

Список экземпляров и формата $connectProperties:

1. UserPasswordConnection ["user" => string, "password" => string]

Сессии

Для создания сессии необходимо создать экземпляр AbstractSession, передав в конструктор экземпляр ConnectionInterface и $connectProperties формата ['port' => port, 'host' => ip, 'properties' => формат $connectProperties для выбранного подтипа ConnectionInterface]
Типы сессий

1. Session - не сохраняет контекст выполнения между командами и позволяет использовать только exec() метод

$session = new Session(new UserPasswordConnection(), 
                        ['port' => 22, 
                        'host' => $_ENV['host'], 
                        'properties' => ['user' => $_ENV['host'], 'password' => $_ENV['host']]
                      ]);

1. ChainSession - сохраняет контекст выполнения между командами и позволяет конструировать сложные сценарии с использованием if, for, switch case конструкций

$chainSession = new ChainSession(new UserPasswordConnection(), 
                        ['port' => 22, 
                        'host' => $_ENV['host'], 
                        'properties' => ['user' => $_ENV['host'], 'password' => $_ENV['host']]
                      ]);

ChainSession необходимо инициализировать методом initChain() перед началом использования команд

$chainSession->initChain();

При использовании любой сессии для получения результата необходимо в конце вызвать метод apply()

$session->exec("ls -la")->apply();
$chainSession->initChain()->exec('ls -la')->apply();

Команды

Типы команд:

1. Single - одиночная команда, единственные представитель exec()
2. Operator - команды, которые управляют потоком выполнения цепочки команд представители: if(), switch()
3. Block - команды, которые внутри себя хранят другие команды представители: then(), else(), for(), case()
4. None - команды заглушки, представители - все команды с префиксом end

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

1. exec($cmd) - выполняет переданную в параметре $cmd команду

   $session->exec('ls -la');
   

2. if($cmd, $ifStatement) - выполняет переданную в $cmd команду и в дальнейшем проверяет вхождение $ifStatement в результате выполнения команды, если проверка завершилась успехом, будет выполнена ветка then, иначе ветка else

   $session->if('ls -la', 'opt')
              ->then()
                ->exec('cd opt')
              ->endThen()
              ->else()
                ->exec('cd ..')
              ->endElse()
            ->endIf()
   

3. for($start, $stop, $step) - команда выполняющая все команды внутри своего тела пока внутренний счетчик, стартовое значение которого равно значению $start, каждый шаг увеличивающийся на значение $step не станет больше или равен значению $stop
4. switch($cmd) - команда множественного ветвления, выполняет переданную в $cmd команду, после чего проверяет каждую внутреннюю case() команду на вхождение их условий в текст вывода выполненной команды, после чего выполняет первую case() команду с которой было найдено совпадение

Функции

ChainSession поддерживает создание функций в рамках одного экземпляра. Для этого необходимо вызвать метод declareFunction($name), где $name - имя функции. Описать используемые в функции команды и завершить функцию методом endFunction(). Для вызова функции необходимо использовать метод useFunction($name), где $name имя используемой функции. Функции можно использовать между вызовами команд.

Замечания к командам

Команды if() и case() проверяют вхождение в вывод используя функцию preg_match(), переданное условие будет использоваться в качестве регулярного выражения
Все end команды имеют тип None и не имеют привязки к начинающим командам, проверка правильности составления цепочки команд пока что не умеет сопоставлять начало команды с ее концом и руководствуется правилами зависимостей типов команд друг от друга, это означает что соблюдение того, какая закрывающая команда используется, остается за пользователем

Тестирование

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

Лицензия

Лицензии нет, используйте как хотите.