Telnet client written in PHP

v2.3.0 2020-12-11 10:09 UTC


Latest Version on Packagist Software License Build Status Coverage Status Quality Score Total Downloads

A telnet client written in PHP


Via Composer

composer require graze/telnet-client


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 = '';

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);


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 = '';
$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 = '';
$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 = '';
$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


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

Change log

Please see CHANGELOG for more information what has changed recently.


make test


Please see CONTRIBUTING for details.


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

Inspired by

Based on bestnetwork/Telnet.



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