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
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
$commandResponse = $facade->executeCommand(
    new SshCommandRequest(
        command: 'ls -la /var/www',
        sessionToken: $loginResponse->sessionToken
    )
);

echo $commandResponse->stdout;

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

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.

adachsoft / ssh-gate

Maintainers

Package info

Statistics

Security