README

概述

Frampt 是一个简单、轻量级的 SSH 客户端，旨在通过 SSH 连接提供一个优雅且易于使用的 API，以完成常见任务。其前提很简单；它允许用户连接到远程服务器，运行命令，以及发送或接收文件。就是这样。没有花哨的功能。最初是一个帮助自主管理远程服务器的想法，因此创建并共享一个包，以便其他人也能从中受益。

要求

Frampt 轻量级，唯一的要求是 PHP 7.1.0 或更高版本。

安装

Frampt 可以通过 composer 简单安装。

composer require defrostedtuna/frampt

用法

使用 Frampt 很简单。以下是一个示例，以展示基础知识。

use DefrostedTuna\Frampt\Client;

$frampt = new Client('www.example.com');

$frampt->authenticateWithPassword(
    'username',
    'password'
);

// Or with an ssh key.
$frampt->authenticateWithPublicKey(
    'username',
    '/path/to/public/key/id_rsa.pub',
    '/path/to/private/key/id_rsa',
    'optional-passphrase'
);

// Run a command on the remote server.
$frampt->runCommand('mkdir /some-directory');

// Retreive the output from the commands that have been run.
$streamOutput = $frampt->getStreamOutput();

// Clear the stream output.
$frampt->clearStreamOutput();

// Retreive the output from the commands that have been run for the entire session.
$sessionOutput = $frampt->getSessionOutput();

// Send receive a file.
$frampt->sendFile(
    '/path/to/local/file.txt',
    '/path/to/remote/file.txt',
    0644 // Optional permissions.
);

// Receive receive a file.
$frampt->receiveFile(
    '/path/to/remote/file.txt',
    '/path/to/local/file.txt'
);

// Disconnect manually, or when the class is destroyed.
$frampt->disconnect():

命令也可以链式调用。

use DefrostedTuna\Frampt\Client;

$frampt = new Client('www.example.com');

// Connect, run commands, and get the output.
$streamOutput = $frampt->authenticateWithPublicKey(
    'username',
    '/path/to/public/key/id_rsa.pub',
    '/path/to/private/key/id_rsa',
    'optional-passphrase'
)->runCommand('touch file.txt')
    ->runCommand('cp file.txt /some-directory/file.txt')
    ->getStreamOutput();

// Connect, run a command, and disconnect.
$frampt->authenticateWithPassword(
    'username',
    'password'
)->runCommand("echo 'Some text.' >> /some-directory/file.txt")->disconnect();

// Run a command, clear the output, run another command,
// and get the output of the second command only.
$frampt->runCommand("echo 'Some more text.' >> /some-directory/file.txt")
    ->clearStreamOutput()
    ->runCommand('cat /some-directory/file.txt')
    ->getStreamOutput();

// Run a command, disconnect from the server, and get the session output.
$frampt->runCommand('rm -rf /some-directory/file.txt')
    ->disconnect()
    ->getSessionOutput();
    
// Send a file and receive a file.
$frampt->sendFile(
    '/path/to/local/file.txt',
    '/path/to/remote/file.txt',
    0644
)->receiveFile(
    '/path/to/remote/file.txt',
    '/path/to/local/file.txt',
);

API

/**
 * Authenticate over SSH using a plain password.
 *
 * @param string $username
 * @param string $password
 *
 * @return \DefrostedTuna\Frampt\ClientInterface
 *
 * @throws \DefrostedTuna\Frampt\Exceptions\AuthenticationException
 */
public function authenticateWithPassword(
    string $username,
    string $password
) : ClientInterface;

/**
 * Authenticate over SSH using a public key.
 *
 * @param string $username
 * @param string $publicKeyFile,
 * @param string $privateKeyFile,
 * @param string $passphrase = null
 *
 * @return \DefrostedTuna\Frampt\ClientInterface
 *
 * @throws \DefrostedTuna\Frampt\Exceptions\AuthenticationException
 */
public function authenticateWithPublicKey(
    string $username,
    string $publicKeyFile,
    string $privateKeyFile,
    string $passphrase = null
) : ClientInterface;

/**
 * Disconnects from the remote server passed to the class instance.
 *
 * @return \DefrostedTuna\Frampt\ClientInterface
 *
 * @throws \DefrostedTuna\Frampt\Exceptions\ConnectionException
 */
public function disconnect() : ClientInterface;

/**
 * Retrieves the server property.
 *
 * @return string
 */
public function getServer() : string;

/**
 * Retrieves the authenticated property.
 *
 * @return bool
 */
public function getAuthenticated() : bool;

/**
 * Retrieves the output from each command run.
 *
 * @return string
 */
public function getStreamOutput() : string;

/**
 * Retrieves the output from each command run during the session.
 *
 * @return string
 */
public function getSessionOutput() : string;

/**
 * Clears the stream output for all previously run commands.
 *
 * @return ClientInterface
 */
public function clearStreamOutput() : ClientInterface;

/**
 * Sets the command to be run on the given remote server instance.
 *
 * @param string $command
 *
 * @return \DefrostedTuna\Frampt\ClientInterface
 *
 * @throws \DefrostedTuna\Frampt\Exceptions\CommandException
 */
public function runCommand(string $command) : ClientInterface;

/**
 * Sends a file to the remote server.
 *
 * @param string $localFile
 * @param string $remoteFile
 * @param int|null $permissions
 *
 * @return \DefrostedTuna\Frampt\ClientInterface
 *
 * @throws \DefrostedTuna\Frampt\Exceptions\CommandException
 */
public function sendFile(
    string $localFile,
    string $remoteFile,
    int $permissions = null
) : ClientInterface;

/**
 * Receives a file from the remote server.
 *
 * @param string $remoteFile
 * @param string $localFile
 *
 * @return \DefrostedTuna\Frampt\ClientInterface
 *
 * @throws \DefrostedTuna\Frampt\Exceptions\CommandException
 */
public function receiveFile(
    string $remoteFile,
    string $localFile
) : ClientInterface;

测试

已包含测试，可以使用 PHPUnit 运行。

vendor/bin/phpunit

为了方便起见，Frampt 包含一个 Docker 容器，可以在其中运行测试。这为开发人员节省了在本地计算机上安装任何依赖项的麻烦。

要使用 Docker 运行测试套件，可以通过 composer:latest Docker 镜像安装依赖项。

docker run --rm -v $(pwd):/app composer:latest install --no-interaction --no-suggest

一旦安装了 Composer 依赖项，就可以创建 Docker 容器并运行测试。

docker-compose up -d
docker-compose exec package vendor/bin/phpunit --coverage-text