README

A telnet client written in PHP

Install

Via Composer

composer require graze/telnet-client

Usage

Instantiating a client

Use the factory method to return a TelnetClientInterface instance:

$client = Graze\TelnetClient\TelnetClient::factory();

Issuing commands

Connect to the remote endpoint using the connect method:

$dsn = '127.0.0.1:23';
$client->connect($dsn);

Once connected, the execute method can be used to write $command to the socket:

$command = 'Open the pod bay doors, HAL';
$resp = $client->execute($command);

Responses

Once a command has been sent, the socket is read until a specific sequence is encountered. This is a line ending immediately preceded by either a prompt, or an error prompt. At this point the execute method returns a TelnetResponseInterface object:

/**
 * Whether an error prompt was encountered.
 *
 * @return bool
 */
public function isError();

/**
 * Any response from the server up until a prompt is encountered.
 *
 * @return string
 */
public function getResponseText();

/**
 * The portion of the server's response that caused execute() to return.
 *
 * @return array
 */
public function getPromptMatches();

A success response object might look like:

Graze\TelnetClient\TelnetResponse {#2
  #isError: false
  #responseText: "Affirmative, Dave"
  #promptMatches: array:1 [
    0 => "$"
  ]
}

Or if the server responded with an error:

Graze\TelnetClient\TelnetResponse {#2
  #isError: true
  #responseText: " I'm sorry, Dave. I'm afraid I can't do that"
  #promptMatches: array:1 [
    0 => "ERROR"
  ]
}

Note: responseText and promptMatches are trimmed of line endings.

Client configuration

The client uses the following defaults:

standard prompt $
error prompt ERROR
line endings \n

Custom configuration can be passed to the connect method like so:

$dsn = '127.0.0.1:23';
$prompt = 'OK';
$promptError = 'ERR';
$lineEnding = "\r\n";
$client->connect($dsn, $prompt, $promptError, $lineEnding);

The client's global $prompt can be temporarily overridden on a per-execute basis:

$command = 'login';
$prompt = 'Username:';
$resp = $client->execute($command, $prompt);

Complex prompts

Some operations may respond with a more complex prompt. These instances can be handled by using a regular expression to match the prompt. For instance, a server may respond with ERROR n (where n is an integer) when an error condition is encountered. The client could be configured as such:

$dsn = '127.0.0.1:23';
$promptError = 'ERROR [0-9]';
$client->connect($dsn, null, $promptError);

An error response would look like:

Graze\TelnetClient\TelnetResponse {#2
  #isError: true
  #responseText: "unknown command"
  #promptMatches: array:1 [
    0 => "ERROR 6"
  ]
}

We can take the regex one further by using a named capturing group, this makes the error code easily available to us in the $promptMatches array.

$dsn = '127.0.0.1:23';
$promptError = 'ERROR (?<errorNum>[0-9])';
$client->connect($dsn, null, $promptError);

which gives us:

Graze\TelnetClient\TelnetResponse {#2
  #isError: true
  #responseText: "unknown command"
  #promptMatches: array:3 [
    0 => "ERROR 6",
    "errorNum" => "6",
    1 => "6"
  ]
}

Note: it's important to escape any characters in your regex that may have special meaning when interpreted by preg_match.

Socket settings

For timeouts and more, PHP's socket_set_option is exposed via

$client->getSocket()->setOption();

See clue/php-socket-raw and socket_set_option for more info.

Change log

Please see CHANGELOG for more information what has changed recently.

Testing

make test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email security@graze.com instead of using the issue tracker.

Inspired by

Based on bestnetwork/Telnet.

Credits

John Smith
Bestnetwork reparto.sviluppo@bestnetwork.it
Dalibor Andzakovic dali@swerve.co.nz
Marc Ennaji
Matthias Blaser mb@adfinis.ch
Christian Hammers chammers@netcologne.de
All Contributors

License

The MIT License (MIT). Please see License File for more information.

graze / telnet-client

Maintainers

Details