Skip to content

Commit b324e5b

Browse files
john-n-smithjohn-n-smith
committed
Merge pull request #1 from graze/initialCommit
Initial commit for review before tagging for release
2 parents 8b14cce + 9973600 commit b324e5b

23 files changed

+1476
-1
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
/vendor/
2+
composer.lock
3+
/tests/report/

‎.scrutinizer.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# .scrutinizer.yml
2+
build:
3+
environment:
4+
php: '5.5.25'
5+
6+
tools:
7+
external_code_coverage: true
8+
php_mess_detector: true
9+
php_code_sniffer: true
10+
sensiolabs_security_checker: true

‎.travis.yml

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
language: php
2+
3+
php:
4+
- '5.5'
5+
- '5.6'
6+
- '7.0'
7+
- hhvm
8+
9+
matrix:
10+
allow_failures:
11+
- php: '7.0'
12+
13+
before_script:
14+
- travis_retry composer self-update
15+
- travis_retry composer update --no-interaction --prefer-source
16+
17+
script: make test-coverage-clover
18+
19+
after_script:
20+
- wget https://scrutinizer-ci.com/ocular.phar
21+
- php ocular.phar code-coverage:upload --format=php-clover ./tests/report/coverage.clover

‎CHANGELOG.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Change Log
2+
3+
All Notable changes to `telnet-client` will be documented in this file
4+
5+
## v1.0.0 - 2016-02-16
6+
7+
### Added
8+
- Everything
9+
10+
### Changed
11+
- Everything
12+
13+
### Fixed
14+
- Nothing
15+
16+
### Deprecated
17+
- Nothing
18+
19+
### Removed
20+
- Nothing
21+
22+
### Security
23+
- Nothing

‎CONTRIBUTING.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Contributing
2+
3+
Contributions are **welcome**!
4+
5+
We accept contributions via Pull Requests on [Github](https://github.com/graze/:package-name). We also recommend reading [How to write the perfect Pull Request](https://github.com/blog/1943-how-to-write-the-perfect-pull-request) which has some great tips and advice.
6+
7+
## Reporting an Issue
8+
9+
Please report issues via the issue tracker on GitHub. For security-related issues, please email the maintainer directly.
10+
11+
## Pull Requests
12+
13+
Contributions are accepted via Pull Requests. In order for your Pull Request to be merged, please ensure it meets
14+
the following criteria:
15+
16+
- **PSR-2 & PSR-4 Coding Standards**.
17+
- **Tests** - your contribution will not be merged unless it has tests covering the changes.
18+
- **Documentation** - please ensure that README.md and any other documentation relevant to your change is up-to-date.
19+
- **Description** - please provide a description of your pull request that details the changes you've made, why you've
20+
made them including any relevant information or justifications that will aid the person reviewing you changes.
21+
22+
## Development Environment
23+
24+
If you need a vagrant box for development, we recommend using [adlawson/vagrantfiles](https://github.com/adlawson/vagrantfiles), for PHP:
25+
26+
```shell
27+
$ curl -O https://raw.githubusercontent.com/adlawson/vagrantfiles/master/php/Vagrantfile
28+
$ vagrant up
29+
$ vagrant ssh
30+
$ cd /srv
31+
```
32+
33+
## Running Tests
34+
35+
You can run all of the test suites in the project using:
36+
37+
```shell
38+
$ make test
39+
```
40+
41+
Or run individual suites using:
42+
43+
```shell
44+
$ make test-unit
45+
$ make test-functional
46+
```
47+
48+
You can get a coverage report in text:
49+
50+
```shell
51+
$ make test-coverage
52+
$ make test-unit-coverage
53+
$ make test-functional-coverage
54+
```
55+
56+
An HTML coverage report can be written to `tests/report` using:
57+
58+
```shell
59+
$ make test-coverage-html
60+
$ make test-unit-coverage-html
61+
$ make test-functional-coverage-html
62+
```
63+
64+
For a coverage report in clover XML format use:
65+
66+
```shell
67+
$ make test-coverage-clover
68+
$ make test-unit-coverage-clover
69+
$ make test-functional-coverage-clover
70+
```

‎LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License (MIT)
2+
3+
Copyright (c) 2016 Nature Delivered Ltd.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎Makefile

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
.PHONY: test test-coverage test-coverage-html test-coverage-clover test-unit test-unit-coverage test-unit-coverage-html test-unit-coverage-clover install
2+
3+
test:
4+
@./vendor/bin/phpunit
5+
6+
test-coverage:
7+
@./vendor/bin/phpunit --coverage-text
8+
9+
test-coverage-html:
10+
@./vendor/bin/phpunit --coverage-html ./tests/report/html
11+
12+
test-coverage-clover:
13+
@./vendor/bin/phpunit --coverage-clover=./tests/report/coverage.clover
14+
15+
test-unit:
16+
@./vendor/bin/phpunit --testsuite unit
17+
18+
test-unit-coverage:
19+
@./vendor/bin/phpunit --testsuite unit --coverage-text
20+
21+
test-unit-coverage-html:
22+
@./vendor/bin/phpunit --testsuite unit --coverage-html ./tests/report/unit/html
23+
24+
test-unit-coverage-clover:
25+
@./vendor/bin/phpunit --testsuite unit --coverage-clover=./tests/report/unit/coverage.clover
26+
27+
install:
28+
@composer install

‎README.md

Lines changed: 174 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,175 @@
11
# telnet-client
2-
☎️ A telnet client written in PHP
2+
3+
[![Latest Version on Packagist](https://img.shields.io/packagist/v/graze/telnet-client.svg?style=flat-square)](https://packagist.org/packages/graze/telnet-client)
4+
[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.md)
5+
[![Build Status](https://img.shields.io/travis/graze/telnet-client/master.svg?style=flat-square)](https://travis-ci.org/graze/telnet-client)
6+
[![Coverage Status](https://img.shields.io/scrutinizer/coverage/g/graze/telnet-client.svg?style=flat-square)](https://scrutinizer-ci.com/g/graze/telnet-client/code-structure)
7+
[![Quality Score](https://img.shields.io/scrutinizer/g/graze/telnet-client.svg?style=flat-square)](https://scrutinizer-ci.com/g/graze/telnet-client)
8+
[![Total Downloads](https://img.shields.io/packagist/dt/graze/telnet-client.svg?style=flat-square)](https://packagist.org/packages/graze/telnet-client)
9+
10+
A telnet clinet written in PHP
11+
12+
## Install
13+
14+
Via Composer
15+
16+
``` bash
17+
$ composer require graze/telnet-client
18+
```
19+
20+
## Usage
21+
22+
### Instantiating a client
23+
24+
Use the `build` method to return a `TelnetClientInterface` instance. This will hold an open socket to the remote sever identified by `$dsn`.
25+
``` php
26+
$dsn = '127.0.0.1:23';
27+
$client = Graze\TelnetClient\TelnetClient::build($dsn);
28+
...
29+
```
30+
31+
### Issuing commands
32+
33+
With the client instantiated, the `execute` method can be used to write `$command` to the socket:
34+
35+
``` php
36+
...
37+
$command = 'Open the pod bay doors, HAL';
38+
$resp = $client->execute($command);
39+
...
40+
```
41+
42+
### Responses
43+
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.
44+
At this point the `execute` method returns a `TelnetResponseInterface` object:
45+
46+
```php
47+
/**
48+
* Whether an error prompt was encountered.
49+
*
50+
* @return bool
51+
*/
52+
public function isError();
53+
54+
/**
55+
* Any response from the server up until a prompt is encountered.
56+
*
57+
* @return string
58+
*/
59+
public function getResponseText();
60+
61+
/**
62+
* The portion of the server's response that caused execute() to return.
63+
*
64+
* @return array
65+
*/
66+
public function getPromptMatches();
67+
```
68+
69+
A success response object might look like:
70+
71+
![screen shot 2016-02-15 at 15 36 39](https://cloud.githubusercontent.com/assets/1314694/13053030/315e5952-d3fa-11e5-8d13-a61ccb135a49.png)
72+
73+
Or if the server responded with an error:
74+
75+
![screen shot 2016-02-15 at 15 37 55](https://cloud.githubusercontent.com/assets/1314694/13053054/400869ac-d3fa-11e5-8bc2-2c0335eaecde.png)
76+
77+
**Note:** `responseText` and `promptMatches` are trimmed of line endings.
78+
### Client configuration
79+
The client uses the following defaults:
80+
* standard prompt `$`
81+
* error prompt `ERROR`
82+
* line endings `\n`
83+
84+
Custom configuration can be passed to the `build` method like so:
85+
``` php
86+
$dsn = '127.0.0.1:23';
87+
$prompt = 'OK';
88+
$promptError = 'ERR';
89+
$lineEnding = "\r\n";
90+
$client = Graze\TelnetClient\TelnetClient::build($dsn, $prompt, $promptError, $lineEnding);
91+
...
92+
```
93+
94+
The client's global `$prompt` can be temporarily overridden on a per-execute basis:
95+
``` php
96+
...
97+
$command = 'login';
98+
$prompt = 'Username:';
99+
$resp = $client->execute($command, $prompt);
100+
...
101+
```
102+
103+
### Complex prompts
104+
Some operations may respond with a more complex prompt. These instances can be handled by using a [regular expression](http://www.regular-expressions.info) to match the prompt.
105+
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:
106+
107+
``` php
108+
$dsn = '127.0.0.1:23';
109+
$promptError = 'ERROR [0-9]';
110+
$client = Graze\TelnetClient\TelnetClient::build($dsn, null, $promptError);
111+
...
112+
```
113+
114+
An error response would look like:
115+
116+
![screen shot 2016-02-15 at 15 51 16](https://cloud.githubusercontent.com/assets/1314694/13053378/1d929210-d3fc-11e5-9479-25cfcfc50fec.png)
117+
118+
We can take the regex one further by using a [named capturing group](http://www.regular-expressions.info/named.html), this makes the error code easily available to us in the `$promptMatches` array.
119+
120+
```php
121+
$dsn = '127.0.0.1:23';
122+
$promptError = 'ERROR (?<errorNum>[0-9])';
123+
$client = Graze\TelnetClient\TelnetClient::build($dsn, null, $promptError);
124+
...
125+
```
126+
127+
which gives us:
128+
129+
![screen shot 2016-02-15 at 15 57 29](https://cloud.githubusercontent.com/assets/1314694/13053525/e04e8656-d3fc-11e5-873a-0d5df92701ae.png)
130+
131+
**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).
132+
### Socket settings
133+
For timouts and more, PHP's `socket_set_option` is exposed via
134+
```php
135+
...
136+
$client->getSocket()->setOption()
137+
```
138+
139+
See [clue/php-socket-raw](https://github.com/clue/php-socket-raw) and [socket_set_option](http://php.net/manual/en/function.socket-set-option.php) for more info.
140+
141+
## Change log
142+
143+
Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.
144+
145+
## Testing
146+
147+
``` bash
148+
$ make test
149+
```
150+
151+
## Contributing
152+
153+
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
154+
155+
## Security
156+
157+
If you discover any security related issues, please email john@graze.com instead of using the issue tracker.
158+
159+
## Inspired by
160+
161+
Based on [bestnetwork/Telnet](https://github.com/bestnetwork/Telnet).
162+
163+
## Credits
164+
165+
- [John Smith](https://github.com/john-n-smith)
166+
- Bestnetwork <reparto.sviluppo@bestnetwork.it>
167+
- Dalibor Andzakovic <dali@swerve.co.nz>
168+
- Marc Ennaji
169+
- Matthias Blaser <mb@adfinis.ch>
170+
- Christian Hammers <chammers@netcologne.de>
171+
- [All Contributors](../../contributors)
172+
173+
## License
174+
175+
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

0 commit comments

Comments
 (0)