graze/telnet-client

Telnet client written in PHP

telnet-client

, _(*1)

A telnet client written in PHP, _(*2)

Install

Via Composer, _(*3)

``` bash composer require graze/telnet-client, <sub>(*4)</sub>

## Usage

### Instantiating a client

Use the `factory` method to return a `TelnetClientInterface` instance:

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

Issuing commands

Connect to the remote endpoint using the connect method:, <sub>(*5)</sub>

``` php $dsn = '127.0.0.1:23'; $client->connect($dsn);, <sub>(*6)</sub>

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

``` php
$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:, <sub>(*7)</sub>

/**
 * 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:, <sub>(*8)</sub>

``` php Graze\TelnetClient\TelnetResponse {#2 #isError: false #responseText: "Affirmative, Dave" #promptMatches: array:1 [ 0 => "$" ] }, <sub>(*9)</sub>

Or if the server responded with an error:

``` php
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., <sub>(*10)</sub>

Client configuration

The client uses the following defaults:, <sub>(*11)</sub>

• standard prompt $
• error prompt ERROR
• line endings \n

Custom configuration can be passed to the connect method like so:, <sub>(*12)</sub>

``` php $dsn = '127.0.0.1:23'; $prompt = 'OK'; $promptError = 'ERR'; $lineEnding = "\r\n"; $client->connect($dsn, $prompt, $promptError, $lineEnding);, <sub>(*13)</sub>

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

``` php
$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:, <sub>(*14)</sub>

``` php $dsn = '127.0.0.1:23'; $promptError = 'ERROR [0-9]'; $client->connect($dsn, null, $promptError);, <sub>(*15)</sub>

An error response would look like:

``` php
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., <sub>(*16)</sub>

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

which gives us:, <sub>(*17)</sub>

``` php Graze\TelnetClient\TelnetResponse {#2 #isError: true #responseText: "unknown command" #promptMatches: array:3 [ 0 => "ERROR 6", "errorNum" => "6", 1 => "6" ] }, <sub>(*18)</sub>

**Note:** it's important to escape any characters in your regex that may have special meaning when interpreted by [preg_match](http://php.net/manual/en/function.preg-match.php).

### Socket settings

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

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

See clue/php-socket-raw and socket_set_option for more info., <sub>(*19)</sub>

Change log

Please see CHANGELOG for more information what has changed recently., <sub>(*20)</sub>

Testing

bash make test, <sub>(*21)</sub>

Contributing

Please see CONTRIBUTING for details., <sub>(*22)</sub>

Security

If you discover any security related issues, please email security@graze.com instead of using the issue tracker., <sub>(*23)</sub>

Inspired by

Based on bestnetwork/Telnet., <sub>(*24)</sub>

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., <sub>(*25)</sub>