a72 / telnet-client

☎️ A telnet client written in PHP

telnet-client

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 preceeded 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:

Or if the server responded with an 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:

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:

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

Socket settings

For timouts 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 [email protected] instead of using the issue tracker.

Inspired by

Based on bestnetwork/Telnet.

Credits

• John Smith
• Bestnetwork [email protected]
• Dalibor Andzakovic [email protected]
• Marc Ennaji
• Matthias Blaser [email protected]
• Christian Hammers [email protected]
• All Contributors

License

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