Skip to content

Commit 64d4bb5

Browse files
clueclue
authored
Merge pull request #39 from clue-labs/readme
Improve code examples and documentation
2 parents ba57d6b + d5ceb3f commit 64d4bb5

9 files changed

+145
-95
lines changed

‎README.md

Lines changed: 84 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -72,16 +72,19 @@ secure HTTPS request to google.com through a local HTTP proxy server:
7272
```php
7373
$loop = React\EventLoop\Factory::create();
7474

75-
$proxy = new ProxyConnector('127.0.0.1:8080', new Connector($loop));
76-
$connector = new Connector($loop, array(
75+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
76+
'127.0.0.1:8080',
77+
new React\Socket\Connector($loop)
78+
);
79+
$connector = new React\Socket\Connector($loop, array(
7780
'tcp' => $proxy,
7881
'timeout' => 3.0,
7982
'dns' => false
8083
));
8184

82-
$connector->connect('tls://google.com:443')->then(function (ConnectionInterface $stream) {
83-
$stream->write("GET / HTTP/1.1\r\nHost: google.com\r\nConnection: close\r\n\r\n");
84-
$stream->on('data', function ($chunk) {
85+
$connector->connect('tls://google.com:443')->then(function (React\Socket\ConnectionInterface $connection) {
86+
$connection->write("GET / HTTP/1.1\r\nHost: google.com\r\nConnection: close\r\n\r\n");
87+
$connection->on('data', function ($chunk) {
8588
echo $chunk;
8689
});
8790
}, 'printf');
@@ -106,8 +109,8 @@ Its constructor simply accepts an HTTP proxy URL and a connector used to connect
106109
to the proxy server address:
107110

108111
```php
109-
$connector = new Connector($loop);
110-
$proxy = new ProxyConnector('http://127.0.0.1:8080', $connector);
112+
$connector = new React\Socket\Connector($loop);
113+
$proxy = new Clue\React\HttpProxy\ProxyConnector('http://127.0.0.1:8080', $connector);
111114
```
112115

113116
The proxy URL may or may not contain a scheme and port definition. The default
@@ -133,9 +136,9 @@ This makes it fairly simple to add HTTP CONNECT proxy support to pretty much any
133136
higher-level component:
134137

135138
```diff
136-
- $client = new SomeClient($connector);
137-
+ $proxy = new ProxyConnector('http://127.0.0.1:8080', $connector);
138-
+ $client = new SomeClient($proxy);
139+
- $acme = new AcmeApi($connector);
140+
+ $proxy = new Clue\React\HttpProxy\ProxyConnector('http://127.0.0.1:8080', $connector);
141+
+ $acme = new AcmeApi($proxy);
139142
```
140143

141144
#### Plain TCP connections
@@ -147,11 +150,14 @@ As documented above, you can simply invoke its `connect()` method to establish
147150
a streaming plain TCP/IP connection and use any higher level protocol like so:
148151

149152
```php
150-
$proxy = new ProxyConnector('http://127.0.0.1:8080', $connector);
153+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
154+
'127.0.0.1:8080',
155+
new React\Socket\Connector($loop)
156+
);
151157

152-
$proxy->connect('tcp://smtp.googlemail.com:587')->then(function (ConnectionInterface $stream) {
153-
$stream->write("EHLO local\r\n");
154-
$stream->on('data', function ($chunk) use ($stream) {
158+
$proxy->connect('tcp://smtp.googlemail.com:587')->then(function (React\Socket\ConnectionInterface $connection) {
159+
$connection->write("EHLO local\r\n");
160+
$connection->on('data', function ($chunk) use ($connection) {
155161
echo $chunk;
156162
});
157163
});
@@ -161,14 +167,19 @@ You can either use the `ProxyConnector` directly or you may want to wrap this co
161167
in ReactPHP's [`Connector`](https://github.com/reactphp/socket#connector):
162168

163169
```php
164-
$connector = new Connector($loop, array(
170+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
171+
'127.0.0.1:8080',
172+
new React\Socket\Connector($loop)
173+
);
174+
175+
$connector = new React\Socket\Connector($loop, array(
165176
'tcp' => $proxy,
166177
'dns' => false
167178
));
168179

169-
$connector->connect('tcp://smtp.googlemail.com:587')->then(function (ConnectionInterface $stream) {
170-
$stream->write("EHLO local\r\n");
171-
$stream->on('data', function ($chunk) use ($stream) {
180+
$connector->connect('tcp://smtp.googlemail.com:587')->then(function (React\Socket\ConnectionInterface $connection) {
181+
$connection->write("EHLO local\r\n");
182+
$connection->on('data', function ($chunk) use ($connection) {
172183
echo $chunk;
173184
});
174185
});
@@ -186,15 +197,19 @@ ReactPHP's [`Connector`](https://github.com/reactphp/socket#connector) or the
186197
low-level [`SecureConnector`](https://github.com/reactphp/socket#secureconnector):
187198

188199
```php
189-
$proxy = new ProxyConnector('http://127.0.0.1:8080', $connector);
190-
$connector = new Connector($loop, array(
200+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
201+
'127.0.0.1:8080',
202+
new React\Socket\Connector($loop)
203+
);
204+
205+
$connector = new React\Socket\Connector($loop, array(
191206
'tcp' => $proxy,
192207
'dns' => false
193208
));
194209

195-
$connector->connect('tls://smtp.googlemail.com:465')->then(function (ConnectionInterface $stream) {
196-
$stream->write("EHLO local\r\n");
197-
$stream->on('data', function ($chunk) use ($stream) {
210+
$connector->connect('tls://smtp.googlemail.com:465')->then(function (React\Socket\ConnectionInterface $connection) {
211+
$connection->write("EHLO local\r\n");
212+
$connection->on('data', function ($chunk) use ($connection) {
198213
echo $chunk;
199214
});
200215
});
@@ -213,7 +228,7 @@ This allows you to send both plain HTTP and TLS-encrypted HTTPS requests like th
213228

214229
```php
215230
$proxy = new Clue\React\HttpProxy\ProxyConnector(
216-
'http://127.0.0.1:8080',
231+
'127.0.0.1:8080',
217232
new React\Socket\Connector($loop)
218233
);
219234

@@ -252,13 +267,18 @@ It provides the same `connect()` method, but will automatically reject the
252267
underlying connection attempt if it takes too long:
253268

254269
```php
255-
$connector = new Connector($loop, array(
270+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
271+
'127.0.0.1:8080',
272+
new React\Socket\Connector($loop)
273+
);
274+
275+
$connector = new React\Socket\Connector($loop, array(
256276
'tcp' => $proxy,
257277
'dns' => false,
258278
'timeout' => 3.0
259279
));
260280

261-
$connector->connect('tcp://google.com:80')->then(function ($stream) {
281+
$connector->connect('tcp://google.com:80')->then(function ($connection) {
262282
// connection succeeded within 3.0 seconds
263283
});
264284
```
@@ -294,7 +314,12 @@ Given that remote DNS resolution is assumed to be the preferred mode, all
294314
other examples explicitly disable DNS resolution like this:
295315

296316
```php
297-
$connector = new Connector($loop, array(
317+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
318+
'127.0.0.1:8080',
319+
new React\Socket\Connector($loop)
320+
);
321+
322+
$connector = new React\Socket\Connector($loop, array(
298323
'tcp' => $proxy,
299324
'dns' => false
300325
));
@@ -303,8 +328,13 @@ $connector = new Connector($loop, array(
303328
If you want to explicitly use *local DNS resolution*, you can use the following code:
304329

305330
```php
331+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
332+
'127.0.0.1:8080',
333+
new React\Socket\Connector($loop)
334+
);
335+
306336
// set up Connector which uses Google's public DNS (8.8.8.8)
307-
$connector = new Connector($loop, array(
337+
$connector = new React\Socket\Connector($loop, array(
308338
'tcp' => $proxy,
309339
'dns' => '8.8.8.8'
310340
));
@@ -319,7 +349,10 @@ If your HTTP proxy server requires authentication, you may pass the username and
319349
password as part of the HTTP proxy URL like this:
320350

321351
```php
322-
$proxy = new ProxyConnector('http://user:pass@127.0.0.1:8080', $connector);
352+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
353+
'http://user:pass@127.0.0.1:8080',
354+
new React\Socket\Connector($loop)
355+
);
323356
```
324357

325358
Note that both the username and password must be percent-encoded if they contain
@@ -329,7 +362,7 @@ special characters:
329362
$user = 'he:llo';
330363
$pass = 'p@ss';
331364

332-
$proxy = new ProxyConnector(
365+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
333366
rawurlencode($user) . ':' . rawurlencode($pass) . '@127.0.0.1:8080',
334367
$connector
335368
);
@@ -353,10 +386,14 @@ in practice, but may be useful for some more advanced use cases. In this case,
353386
you may simply pass an assoc array of additional request headers like this:
354387

355388
```php
356-
$proxy = new ProxyConnector('127.0.0.1:8080', $connector, array(
357-
'Proxy-Authorization' => 'Bearer abc123',
358-
'User-Agent' => 'ReactPHP'
359-
));
389+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
390+
'127.0.0.1:8080',
391+
$connector,
392+
array(
393+
'Proxy-Authorization' => 'Bearer abc123',
394+
'User-Agent' => 'ReactPHP'
395+
)
396+
);
360397
```
361398

362399
#### Advanced secure proxy connections
@@ -373,8 +410,10 @@ If you want to connect to a (rather rare) HTTPS proxy, you may want use the
373410
instance to create a secure connection to the proxy:
374411

375412
```php
376-
$connector = new Connector($loop);
377-
$proxy = new ProxyConnector('https://127.0.0.1:443', $connector);
413+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
414+
'https://127.0.0.1:443',
415+
new React\Socket\Connector($loop)
416+
);
378417

379418
$proxy->connect('tcp://smtp.googlemail.com:587');
380419
```
@@ -391,9 +430,12 @@ having to rely on explicit [authentication](#authentication).
391430
You can simply use the `http+unix://` URI scheme like this:
392431

393432
```php
394-
$proxy = new ProxyConnector('http+unix:///tmp/proxy.sock', $connector);
433+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
434+
'http+unix:///tmp/proxy.sock',
435+
new React\Socket\Connector($loop)
436+
);
395437

396-
$proxy->connect('tcp://google.com:80')->then(function (ConnectionInterface $stream) {
438+
$proxy->connect('tcp://google.com:80')->then(function (React\Socket\ConnectionInterface $connection) {
397439
// connected…
398440
});
399441
```
@@ -402,7 +444,10 @@ Similarly, you can also combine this with [authentication](#authentication)
402444
like this:
403445

404446
```php
405-
$proxy = new ProxyConnector('http+unix://user:pass@/tmp/proxy.sock', $connector);
447+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
448+
'http+unix://user:pass@/tmp/proxy.sock',
449+
new React\Socket\Connector($loop)
450+
);
406451
```
407452

408453
> Note that Unix domain sockets (UDS) are considered advanced usage and PHP only

‎examples/01-http-request.php

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,10 @@
2222
}
2323

2424
$loop = React\EventLoop\Factory::create();
25-
$proxy = new Clue\React\HttpProxy\ProxyConnector($url, new React\Socket\Connector($loop));
25+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
26+
$url,
27+
new React\Socket\Connector($loop)
28+
);
2629

2730
$connector = new React\Socket\Connector($loop, array(
2831
'tcp' => $proxy,

‎examples/02-optional-proxy-http-request.php

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,10 @@
2020
$connector = null;
2121
$url = getenv('http_proxy');
2222
if ($url !== false) {
23-
$connector = new React\Socket\Connector($loop);
24-
$proxy = new Clue\React\HttpProxy\ProxyConnector($url, $connector);
23+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
24+
$url,
25+
new React\Socket\Connector($loop)
26+
);
2527
$connector = new React\Socket\Connector($loop, array(
2628
'tcp' => $proxy,
2729
'timeout' => 3.0,

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

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,6 @@
1717
// For illustration purposes only. If you want to send HTTP requests in a real
1818
// world project, take a look at example #01, example #02 and https://github.com/reactphp/http#client-usage.
1919

20-
use Clue\React\HttpProxy\ProxyConnector;
21-
use React\Socket\Connector;
22-
use React\Socket\ConnectionInterface;
23-
2420
require __DIR__ . '/../vendor/autoload.php';
2521

2622
$url = getenv('http_proxy');
@@ -30,16 +26,20 @@
3026

3127
$loop = React\EventLoop\Factory::create();
3228

33-
$proxy = new ProxyConnector($url, new Connector($loop));
34-
$connector = new Connector($loop, array(
29+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
30+
$url,
31+
new React\Socket\Connector($loop)
32+
);
33+
34+
$connector = new React\Socket\Connector($loop, array(
3535
'tcp' => $proxy,
3636
'timeout' => 3.0,
3737
'dns' => false
3838
));
3939

40-
$connector->connect('tls://google.com:443')->then(function (ConnectionInterface $stream) {
41-
$stream->write("GET / HTTP/1.1\r\nHost: google.com\r\nConnection: close\r\n\r\n");
42-
$stream->on('data', function ($chunk) {
40+
$connector->connect('tls://google.com:443')->then(function (React\Socket\ConnectionInterface $connection) {
41+
$connection->write("GET / HTTP/1.1\r\nHost: google.com\r\nConnection: close\r\n\r\n");
42+
$connection->on('data', function ($chunk) {
4343
echo $chunk;
4444
});
4545
}, function (Exception $e) {

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

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -20,29 +20,28 @@
2020
// For illustration purposes only. If you want to send HTTP requests in a real
2121
// world project, take a look at example #01, example #02 and https://github.com/reactphp/http#client-usage.
2222

23-
use Clue\React\HttpProxy\ProxyConnector;
24-
use React\Socket\Connector;
25-
use React\Socket\ConnectionInterface;
26-
2723
require __DIR__ . '/../vendor/autoload.php';
2824

2925
$loop = React\EventLoop\Factory::create();
3026

31-
$connector = new Connector($loop);
27+
$connector = new React\Socket\Connector($loop);
3228

3329
$url = getenv('http_proxy');
3430
if ($url !== false) {
35-
$proxy = new ProxyConnector($url, $connector);
36-
$connector = new Connector($loop, array(
31+
$proxy = new Clue\React\HttpProxy\ProxyConnector(
32+
$url,
33+
$connector
34+
);
35+
$connector = new React\Socket\Connector($loop, array(
3736
'tcp' => $proxy,
3837
'timeout' => 3.0,
3938
'dns' => false
4039
));
4140
}
4241

43-
$connector->connect('tls://google.com:443')->then(function (ConnectionInterface $stream) {
44-
$stream->write("GET / HTTP/1.1\r\nHost: google.com\r\nConnection: close\r\n\r\n");
45-
$stream->on('data', function ($chunk) {
42+
$connector->connect('tls://google.com:443')->then(function (React\Socket\ConnectionInterface $connection) {
43+
$connection->write("GET / HTTP/1.1\r\nHost: google.com\r\nConnection: close\r\n\r\n");
44+
$connection->on('data', function ($chunk) {
4645
echo $chunk;
4746
});
4847
}, function (Exception $e) {

0 commit comments

Comments
 (0)