Skip to content

Commit 9d0e726

Browse files
clueclue
committed
Improve documentation, use fully qualified class names in all examples
1 parent d2d8744 commit 9d0e726

8 files changed

Lines changed: 94 additions & 57 deletions

‎README.md‎

Lines changed: 73 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -86,8 +86,12 @@ $loop = React\EventLoop\Factory::create();
8686
$connector = new React\Socket\Connector($loop);
8787
$client = new Clue\React\Socks\Client('127.0.0.1:1080', $connector);
8888

89-
$client->connect('tcp://www.google.com:80')->then(function (ConnectionInterface $stream) {
90-
$stream->write("GET / HTTP/1.0\r\n\r\n");
89+
$client->connect('tcp://www.google.com:80')->then(function (React\Socket\ConnectionInterface $connection) {
90+
$connection->write("GET / HTTP/1.0\r\n\r\n");
91+
92+
$connection->on('data', function ($chunk) {
93+
echo $chunk;
94+
});
9195
});
9296

9397
$loop->run();
@@ -126,13 +130,13 @@ like this:
126130

127131
```php
128132
$connector = new React\Socket\Connector($loop);
129-
$client = new Client('127.0.0.1:1080', $connector);
133+
$client = new Clue\React\Socks\Client('127.0.0.1:1080', $connector);
130134
```
131135

132136
You can omit the port if you're using the default SOCKS port 1080:
133137

134138
```php
135-
$client = new Client('127.0.0.1', $connector);
139+
$client = new Clue\React\Socks\Client('127.0.0.1', $connector);
136140
```
137141

138142
If you need custom connector settings (DNS resolution, TLS parameters, timeouts,
@@ -147,7 +151,7 @@ $connector = new React\Socket\Connector($loop, array(
147151
)
148152
));
149153

150-
$client = new Client('my-socks-server.local:1080', $connector);
154+
$client = new Clue\React\Socks\Client('my-socks-server.local:1080', $connector);
151155
```
152156

153157
This is one of the two main classes in this package.
@@ -166,7 +170,7 @@ higher-level component:
166170

167171
```diff
168172
- $client = new SomeClient($connector);
169-
+ $proxy = new Client('127.0.0.1:1080', $connector);
173+
+ $proxy = new Clue\React\Socks\Client('127.0.0.1:1080', $connector);
170174
+ $client = new SomeClient($proxy);
171175
```
172176

@@ -179,10 +183,13 @@ As documented above, you can simply invoke its `connect()` method to establish
179183
a streaming plain TCP/IP connection and use any higher level protocol like so:
180184

181185
```php
182-
$client->connect('tcp://www.google.com:80')->then(function (ConnectonInterface $stream) {
186+
$client->connect('tcp://www.google.com:80')->then(function (React\Socket\ConnectionInterface $connection) {
183187
echo 'connected to www.google.com:80';
184-
$stream->write("GET / HTTP/1.0\r\n\r\n");
185-
// ...
188+
$connection->write("GET / HTTP/1.0\r\n\r\n");
189+
190+
$connection->on('data', function ($chunk) {
191+
echo $chunk;
192+
});
186193
});
187194
```
188195

@@ -195,10 +202,13 @@ $connector = new React\Socket\Connector($loop, array(
195202
'dns' => false
196203
));
197204

198-
$connector->connect('tcp://www.google.com:80')->then(function (ConnectonInterface $stream) {
205+
$connector->connect('tcp://www.google.com:80')->then(function (React\Socket\ConnectionInterface $connection) {
199206
echo 'connected to www.google.com:80';
200-
$stream->write("GET / HTTP/1.0\r\n\r\n");
201-
// ...
207+
$connection->write("GET / HTTP/1.0\r\n\r\n");
208+
209+
$connection->on('data', function ($chunk) {
210+
echo $chunk;
211+
});
202212
});
203213
```
204214

@@ -234,12 +244,15 @@ $connector = new React\Socket\Connector($loop, array(
234244
));
235245

236246
// now create an SSL encrypted connection (notice the $ssl instead of $tcp)
237-
$connector->connect('tls://www.google.com:443')->then(function (ConnectionInterface $stream) {
247+
$connector->connect('tls://www.google.com:443')->then(function (React\Socket\ConnectionInterface $connection) {
238248
// proceed with just the plain text data
239249
// everything is encrypted/decrypted automatically
240250
echo 'connected to SSL encrypted www.google.com';
241-
$stream->write("GET / HTTP/1.0\r\n\r\n");
242-
// ...
251+
$connection->write("GET / HTTP/1.0\r\n\r\n");
252+
253+
$connection->on('data', function ($chunk) {
254+
echo $chunk;
255+
});
243256
});
244257
```
245258

@@ -378,16 +391,16 @@ URI scheme acts as an alias for the default `socks://` URI scheme.
378391

379392
```php
380393
// all three forms are equivalent
381-
$client = new Client('127.0.0.1', $connector);
382-
$client = new Client('socks://127.0.0.1', $connector);
383-
$client = new Client('socks5://127.0.0.1', $connector);
394+
$client = new Clue\React\Socks\Client('127.0.0.1', $connector);
395+
$client = new Clue\React\Socks\Client('socks://127.0.0.1', $connector);
396+
$client = new Clue\React\Socks\Client('socks5://127.0.0.1', $connector);
384397
```
385398

386399
If want to explicitly set the protocol version to SOCKS4(a), you can use the URI
387400
scheme `socks4://` as part of the SOCKS URI:
388401

389402
```php
390-
$client = new Client('socks4://127.0.0.1', $connector);
403+
$client = new Clue\React\Socks\Client('socks4://127.0.0.1', $connector);
391404
```
392405

393406
#### DNS resolution
@@ -462,7 +475,7 @@ so this methods should not be used on a network where you have to worry about ea
462475
You can simply pass the authentication information as part of the SOCKS URI:
463476

464477
```php
465-
$client = new Client('username:password@127.0.0.1', $connector);
478+
$client = new Clue\React\Socks\Client('username:password@127.0.0.1', $connector);
466479
```
467480

468481
Note that both the username and password must be percent-encoded if they contain
@@ -472,7 +485,7 @@ special characters:
472485
$user = 'he:llo';
473486
$pass = 'p@ss';
474487

475-
$client = new Client(
488+
$client = new Clue\React\Socks\Client(
476489
rawurlencode($user) . ':' . rawurlencode($pass) . '@127.0.0.1',
477490
$connector
478491
);
@@ -490,7 +503,7 @@ version 5 and complains if you have explicitly set anything else:
490503

491504
```php
492505
// throws InvalidArgumentException
493-
new Client('socks4://user:pass@127.0.0.1', $connector);
506+
new Clue\React\Socks\Client('socks4://user:pass@127.0.0.1', $connector);
494507
```
495508

496509
#### Proxy chaining
@@ -521,15 +534,21 @@ SOCKS connector from another SOCKS client like this:
521534
// which in turn then uses MiddlemanSocksServer.
522535
// this creates a TCP/IP connection to MiddlemanSocksServer, which then connects
523536
// to TargetSocksServer, which then connects to the TargetHost
524-
$middle = new Client('127.0.0.1:1080', new Connector($loop));
525-
$target = new Client('example.com:1080', $middle);
537+
$middle = new Clue\React\Socks\Client(
538+
'127.0.0.1:1080',
539+
new React\Socket\Connector($loop)
540+
);
541+
$target = new Clue\React\Socks\Client(
542+
'example.com:1080',
543+
$middle
544+
);
526545

527546
$connector = new React\Socket\Connector($loop, array(
528547
'tcp' => $target,
529548
'dns' => false
530549
));
531550

532-
$connector->connect('tls://www.google.com:443')->then(function ($stream) {
551+
$connector->connect('tls://www.google.com:443')->then(function (React\Socket\ConnectionInterface $connection) {
533552
// …
534553
});
535554
```
@@ -570,13 +589,13 @@ It provides the same `connect()` method, but will automatically reject the
570589
underlying connection attempt if it takes too long:
571590

572591
```php
573-
$connector = new Connector($loop, array(
592+
$connector = new React\Socket\Connector($loop, array(
574593
'tcp' => $client,
575594
'dns' => false,
576595
'timeout' => 3.0
577596
));
578597

579-
$connector->connect('tcp://google.com:80')->then(function ($stream) {
598+
$connector->connect('tcp://google.com:80')->then(function (React\Socket\ConnectionInterface $connection) {
580599
// connection succeeded within 3.0 seconds
581600
});
582601
```
@@ -613,9 +632,15 @@ You can use the `sockss://` URI scheme or use an explicit
613632
[SOCKS protocol version](#protocol-version) like this:
614633

615634
```php
616-
$client = new Client('sockss://127.0.0.1:1080', new Connector($loop));
635+
$client = new Clue\React\Socks\Client(
636+
'sockss://127.0.0.1:1080',
637+
new React\Socket\Connector($loop)
638+
);
617639

618-
$client = new Client('socks4s://127.0.0.1:1080', new Connector($loop));
640+
$client = new Clue\React\Socks\Client(
641+
'socks4s://127.0.0.1:1080',
642+
new React\Socket\Connector($loop)
643+
);
619644
```
620645

621646
See also [example 32](examples).
@@ -624,7 +649,10 @@ Similarly, you can also combine this with [authentication](#authentication)
624649
like this:
625650

626651
```php
627-
$client = new Client('sockss://user:pass@127.0.0.1:1080', new Connector($loop));
652+
$client = new Clue\React\Socks\Client(
653+
'sockss://user:pass@127.0.0.1:1080',
654+
new React\Socket\Connector($loop)
655+
);
628656
```
629657

630658
> Note that for most use cases, [secure TLS connections](#secure-tls-connections)
@@ -656,16 +684,25 @@ You can use the `socks+unix://` URI scheme or use an explicit
656684
[SOCKS protocol version](#protocol-version) like this:
657685

658686
```php
659-
$client = new Client('socks+unix:///tmp/proxy.sock', new Connector($loop));
687+
$client = new Clue\React\Socks\Client(
688+
'socks+unix:///tmp/proxy.sock'
689+
new React\Socket\Connector($loop)
690+
);
660691

661-
$client = new Client('socks4+unix:///tmp/proxy.sock', new Connector($loop));
692+
$client = new Clue\React\Socks\Client(
693+
'socks4+unix:///tmp/proxy.sock',
694+
new React\Socket\Connector($loop)
695+
);
662696
```
663697

664698
Similarly, you can also combine this with [authentication](#authentication)
665699
like this:
666700

667701
```php
668-
$client = new Client('socks+unix://user:pass@/tmp/proxy.sock', new Connector($loop));
702+
$client = new Clue\React\Socks\Client(
703+
'socks+unix://user:pass@/tmp/proxy.sock',
704+
new React\Socket\Connector($loop)
705+
);
669706
```
670707

671708
> Note that Unix domain sockets (UDS) are considered advanced usage and PHP only
@@ -968,7 +1005,7 @@ $ ssh -D 1080 example.com
9681005
Now you can simply use this SSH SOCKS server like this:
9691006

9701007
```PHP
971-
$client = new Client('127.0.0.1:1080', $connector);
1008+
$client = new Clue\React\Socks\Client('127.0.0.1:1080', $connector);
9721009
```
9731010

9741011
Note that the above will allow all users on the local system to connect over
@@ -984,7 +1021,7 @@ $ ssh -D/tmp/proxy.sock example.com
9841021
Now you can simply use this SSH SOCKS server like this:
9851022

9861023
```PHP
987-
$client = new Client('socks+unix:///tmp/proxy.sock', $connector);
1024+
$client = new Clue\React\Socks\Client('socks+unix:///tmp/proxy.sock', $connector);
9881025
```
9891026

9901027
> As an alternative to requiring this manual setup, you may also want to look
@@ -1001,7 +1038,7 @@ It presents a SOCKS5 and SOCKS4(a) interface on TCP port 9050 by default
10011038
which allows you to tunnel any traffic through the anonymity network:
10021039

10031040
```php
1004-
$client = new Client('127.0.0.1:9050', $connector);
1041+
$client = new Clue\React\Socks\Client('127.0.0.1:9050', $connector);
10051042
```
10061043

10071044
In most common scenarios you probably want to stick to default

‎examples/11-proxy-raw-http-protocol.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,10 +35,10 @@
3535

3636
echo 'Demo SOCKS client connecting to SOCKS server ' . $url . PHP_EOL;
3737

38-
$connector->connect('tcp://www.google.com:80')->then(function (React\Socket\ConnectionInterface $stream) {
38+
$connector->connect('tcp://www.google.com:80')->then(function (React\Socket\ConnectionInterface $connection) {
3939
echo 'connected' . PHP_EOL;
40-
$stream->write("GET / HTTP/1.0\r\n\r\n");
41-
$stream->on('data', function ($data) {
40+
$connection->write("GET / HTTP/1.0\r\n\r\n");
41+
$connection->on('data', function ($data) {
4242
echo $data;
4343
});
4444
}, function (Exception $e) {

‎examples/12-optional-proxy-raw-http-protocol.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,10 +38,10 @@
3838

3939
echo 'Demo SOCKS client connecting to SOCKS server ' . $url . PHP_EOL;
4040

41-
$connector->connect('tcp://www.google.com:80')->then(function (React\Socket\ConnectionInterface $stream) {
41+
$connector->connect('tcp://www.google.com:80')->then(function (React\Socket\ConnectionInterface $connection) {
4242
echo 'connected' . PHP_EOL;
43-
$stream->write("GET / HTTP/1.0\r\n\r\n");
44-
$stream->on('data', function ($data) {
43+
$connection->write("GET / HTTP/1.0\r\n\r\n");
44+
$connection->on('data', function ($data) {
4545
echo $data;
4646
});
4747
}, function (Exception $e) {

‎examples/13-proxy-raw-https-protocol.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,10 +35,10 @@
3535

3636
echo 'Demo SOCKS client connecting to SOCKS server ' . $url . PHP_EOL;
3737

38-
$connector->connect('tls://www.google.com:443')->then(function (React\Socket\ConnectionInterface $stream) {
38+
$connector->connect('tls://www.google.com:443')->then(function (React\Socket\ConnectionInterface $connection) {
3939
echo 'connected' . PHP_EOL;
40-
$stream->write("GET / HTTP/1.0\r\n\r\n");
41-
$stream->on('data', function ($data) {
40+
$connection->write("GET / HTTP/1.0\r\n\r\n");
41+
$connection->on('data', function ($data) {
4242
echo $data;
4343
});
4444
}, function (Exception $e) {

‎examples/14-optional-proxy-raw-https-protocol.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,10 +38,10 @@
3838

3939
echo 'Demo SOCKS client connecting to SOCKS server ' . $url . PHP_EOL;
4040

41-
$connector->connect('tls://www.google.com:443')->then(function (React\Socket\ConnectionInterface $stream) {
41+
$connector->connect('tls://www.google.com:443')->then(function (React\Socket\ConnectionInterface $connection) {
4242
echo 'connected' . PHP_EOL;
43-
$stream->write("GET / HTTP/1.0\r\n\r\n");
44-
$stream->on('data', function ($data) {
43+
$connection->write("GET / HTTP/1.0\r\n\r\n");
44+
$connection->on('data', function ($data) {
4545
echo $data;
4646
});
4747
}, function (Exception $e) {

‎examples/15-proxy-chaining.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,10 @@
4040

4141
echo 'Demo SOCKS client connecting to SOCKS proxy server chain ' . implode(' -> ', $path) . PHP_EOL;
4242

43-
$connector->connect('tls://www.google.com:443')->then(function (React\Socket\ConnectionInterface $stream) {
43+
$connector->connect('tls://www.google.com:443')->then(function (React\Socket\ConnectionInterface $connection) {
4444
echo 'connected' . PHP_EOL;
45-
$stream->write("GET / HTTP/1.0\r\n\r\n");
46-
$stream->on('data', function ($data) {
45+
$connection->write("GET / HTTP/1.0\r\n\r\n");
46+
$connection->on('data', function ($data) {
4747
echo $data;
4848
});
4949
}, function (Exception $e) {

‎examples/16-local-dns.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,10 @@
2525

2626
echo 'Demo SOCKS client connecting to SOCKS server ' . $proxy . PHP_EOL;
2727

28-
$connector->connect('tls://www.google.com:443')->then(function (React\Socket\ConnectionInterface $stream) {
28+
$connector->connect('tls://www.google.com:443')->then(function (React\Socket\ConnectionInterface $connection) {
2929
echo 'connected' . PHP_EOL;
30-
$stream->write("GET / HTTP/1.0\r\n\r\n");
31-
$stream->on('data', function ($data) {
30+
$connection->write("GET / HTTP/1.0\r\n\r\n");
31+
$connection->on('data', function ($data) {
3232
echo $data;
3333
});
3434
}, function (Exception $e) {

‎examples/42-http-secure.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,10 +26,10 @@
2626

2727
echo 'Demo SOCKS over TLS client connecting to secure SOCKS server ' . $proxy . PHP_EOL;
2828

29-
$connector->connect('tcp://www.google.com:80')->then(function (React\Socket\ConnectionInterface $stream) {
29+
$connector->connect('tcp://www.google.com:80')->then(function (React\Socket\ConnectionInterface $connection) {
3030
echo 'connected' . PHP_EOL;
31-
$stream->write("GET / HTTP/1.0\r\n\r\n");
32-
$stream->on('data', function ($data) {
31+
$connection->write("GET / HTTP/1.0\r\n\r\n");
32+
$connection->on('data', function ($data) {
3333
echo $data;
3434
});
3535
}, function (Exception $e) {

0 commit comments

Comments
 (0)