README

A clean, type-safe PHP library for SSH account management, sessions and remote command execution.

adachsoft/ssh-gate provides a high-level Facade + Builder pattern with strongly typed collections powered by adachsoft/collection.

Features

• Full SSH account CRUD operations
• Login / logout session management
• Remote SSH command execution via dedicated API
• Optional per-command timeout (in milliseconds) for remote execution
• Strongly typed immutable collections (SshAccountCollection, SshSessionCollection)
• Easy configuration via SshModuleFacadeBuilder
• Interactive CLI with colored output and icons
• Comprehensive exception handling (SshModuleException, SshAccountNotFoundException)
• Fully tested with PHPUnit + PHPStan ready

Requirements

• PHP 8.3+
• adachsoft/collection:^3.0
• guzzlehttp/guzzle:^7.8
• adachsoft/console-io:^0.2 (for CLI)
• adachsoft/console-internal:^0.1 (for CLI)

Installation

composer require adachsoft/ssh-gate

After installation the CLI binary will be available via Composer.

Quick Start - Public API

Creating the Facade

use AdachSoft\SshGate\PublicApi\Builder\SshModuleFacadeBuilder;

$facade = (new SshModuleFacadeBuilder())
    ->useJsonAccountRepository(__DIR__ . '/ssh-accounts.json')
    ->withSshApiBaseUrl('https://ssh-api.yourproject.com')
    ->build();

Basic Usage

// Add account
$facade->addAccount(new AddSshAccountRequest(
    name: 'Production Server',
    host: 'prod.example.com',
    port: 22,
    username: 'deploy',
    password: 'super-secret-pass',
));

// Login
$loginResponse = $facade->login(new SshLoginRequest(accountId: 'abc123'));

// Execute command with optional timeout (in milliseconds)
$commandResponse = $facade->executeCommand(
    new SshCommandRequest(
        command: 'ls -la /var/www',
        sessionToken: $loginResponse->sessionToken,
        timeout: 5000, // 5 seconds
    ),
);

echo $commandResponse->stdout;

// List accounts
$accountsResponse = $facade->listAccounts();
foreach ($accountsResponse->accounts as $account) {
    echo $account->name . ' @ ' . $account->host . PHP_EOL;
}

Command timeouts

SshCommandRequest accepts an optional timeout parameter (in milliseconds). When provided, it is forwarded to the underlying HTTP SSH API (/execute-remote). When omitted (null), the server-side default timeout is used.

CLI Usage

The library includes an interactive CLI powered by adachsoft/console-internal and adachsoft/console-io (colored output with icons).

Running the CLI

# After composer install
php bin/ssh-gate

# Or via Composer bin (if configured in your project)
vendor/bin/ssh-gate

Available Commands

All commands are prefixed with \:

• \help – List all available commands
• \add or \add account – Interactively add a new SSH account (prompts for name, host, port, username, password)
• \list or \ls – List all configured SSH accounts
• \exit – Exit the interactive session

Example Session

$ php bin/ssh-gate
🚀 SSH Gate CLI started. Type \help for available commands.
> \add
Enter account name: prod-server
Enter host (e.g., example.com or IP): prod.example.com
Enter port (default 22): [22] 
Enter username: deploy
Enter password (leave empty if none or using key): 
✅ SSH account 'prod-server' added successfully.

> \ls
Configured SSH Accounts:
  - ID: abc123, Name: prod-server, Host: prod.example.com, User: deploy, Port: 22

> \exit

The CLI uses ColoredCliOutput + IconCliOutput for nice terminal output with colors and Unicode icons.

Main Components

SshModuleFacadeInterface

The main entry point of the library. See detailed documentation directly in: src/PublicApi/Facade/SshModuleFacadeInterface.php

Builder

SshModuleFacadeBuilder allows you to configure:

• useJsonAccountRepository(string $path) – recommended JSON storage
• withSshApiBaseUrl(string $baseUrl) – base URL of your SSH API
• Custom implementations via with*Api() and withAccountRepository()

Collections

Both collections extend AdachSoft\Collection\AbstractImmutableCollection and use isValidItem() for strict type validation.

• SshAccountCollection
• SshSessionCollection

DTOs, Requests & Responses

All value objects, requests and responses are located in the AdachSoft\SshGate\PublicApi\* namespace.

Testing

composer test
# or
vendor/bin/phpunit

Static Analysis & Coding Style

composer phpstan
composer csfix

License

MIT License – see the LICENSE file for details.

Author

Arkadiusz Adach – AdachSoft

Development Notes:

• listSessions() currently returns an empty collection (placeholder for future API integration).
• The library is fully tested (91 tests, 324 assertions).
• PHPDoc is written in English as per project standards.