graze / telnet-client
Telnet client written in PHP
Installs: 162 773
Dependents: 8
Suggesters: 0
Security: 0
Stars: 48
Watchers: 17
Forks: 10
Open Issues: 7
Requires
- php: >5.5.0
- clue/socket-raw: ^1.3
Requires (Dev)
- graze/standards: ^2.0
- mockery/mockery: ^0.9.4
- phpunit/phpunit: ^5.0
- squizlabs/php_codesniffer: ^3.5.0
- symfony/var-dumper: ^3.0
This package is auto-updated.
Last update: 2024-10-17 04:37:55 UTC
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.