10000 Improve code examples and documentation by clue · Pull Request #39 · clue/reactphp-http-proxy · GitHub
[go: up one dir, main page]
Skip to content

Improve code examples and documentation #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up 8000 for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 22, 2021
Merged

Improve code examples and documentation #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fd7e5e0
Improve documentation, use fully qualified class names in all examples
clue Apr 22, 2021
d5ceb3f
Skip legacy HHVM test failure regarding secure TLS connections
clue Apr 22, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 84 additions & 39 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,16 +72,19 @@ secure HTTPS request to google.com through a local HTTP proxy server:
```php
$loop = React\EventLoop\Factory::create();

$proxy = new ProxyConnector('127.0.0.1:8080', new Connector($loop));
$connector = new Connector($loop, array(
$proxy = new Clue\React\HttpProxy\ProxyConnector(
10000 '127.0.0.1:8080',
new React\Socket\Connector($loop)
);
$connector = new React\Socket\Connector($loop, array(
'tcp' => $proxy,
'timeout' => 3.0,
'dns' => false
));

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

```php
$connector = new Connector($loop);
$proxy = new ProxyConnector('http://127.0.0.1:8080', $connector);
$connector = new React\Socket\Connector($loop);
$proxy = new Clue\React\HttpProxy\ProxyConnector('http://127.0.0.1:8080', $connector);
```

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

```diff
- $client = new SomeClient($connector);
+ $proxy = new ProxyConnector('http://127.0.0.1:8080', $connector);
+ $client = new SomeClient($proxy);
- $acme = new AcmeApi($connector);
+ $proxy = new Clue\React\HttpProxy\ProxyConnector('http://127.0.0.1:8080', $connector);
+ $acme = new AcmeApi($proxy);
```

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

```php
$proxy = new ProxyConnector('http://127.0.0.1:8080', $connector);
$proxy = new Clue\React\HttpProxy\ProxyConnector(
'127.0.0.1:8080',
new React\Socket\Connector($loop)
);

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

```php
$connector = new Connector($loop, array(
$proxy = new Clue\React\HttpProxy\ProxyConnector(
'127.0.0.1:8080',
new React\Socket\Connector($loop)
);

$connector = new React\Socket\Connector($loop, array(
'tcp' => $proxy,
'dns' => false
));

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

```php
$proxy = new ProxyConnector('http://127.0.0.1:8080', $connector);
$connector = new Connector($loop, array(
$proxy = new Clue\React\HttpProxy\ProxyConnector(
'127.0.0.1:8080',
new React\Socket\Connector($loop)
);

$connector = new React\Socket\Connector($loop, array(
'tcp' => $proxy,
'dns' => false
));

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

```php
$proxy = new Clue\React\HttpProxy\ProxyConnector(
'http://127.0.0.1:8080',
'127.0.0.1:8080',
new React\Socket\Connector($loop)
);

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

```php
$connector = new Connector($loop, array(
$proxy = new Clue\React\HttpProxy\ProxyConnector(
'127.0.0.1:8080',
new React\Socket\Connector($loop)
);

$connector = new React\Socket\Connector($loop, array(
'tcp' => $proxy,
'dns' => false,
'timeout' => 3.0
));

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

```php
$connector = new Connector($loop, array(
$proxy = new Clue\React\HttpProxy\ProxyConnector(
'127.0.0.1:8080',
new React\Socket\Connector($loop)
);

$connector = new React\Socket\Connector($loop, array(
'tcp' => $proxy,
'dns' => false
));
Expand All @@ -303,8 +328,13 @@ $connector = new Connector($loop, array(
If you want to explicitly use *local DNS resolution*, you can use the following code:

```php
$proxy = new Clue\React\HttpProxy\ProxyConnector(
'127.0.0.1:8080',
new React\Socket\Connector($loop)
);

// set up Connector which uses Google's public DNS (8.8.8.8)
$connector = new Connector($loop, array(
$connector = new React\Socket\Connector($loop, array(
'tcp' => $proxy,
'dns' => '8.8.8.8'
));
Expand All @@ -319,7 +349,10 @@ If your HTTP proxy server requires authentication, you may pass the username and
password as part of the HTTP proxy URL like this:

```php
$proxy = new ProxyConnector('http://user:pass@127.0.0.1:8080', $connector);
$proxy = new Clue\React\HttpProxy\ProxyConnector(
'http://user:pass@127.0.0.1:8080',
new React\Socket\Connector($loop)
);
```

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

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

```php
$proxy = new ProxyConnector('127.0.0.1:8080', $connector, array(
'Proxy-Authorization' => 'Bearer abc123',
'User-Agent' => 'ReactPHP'
));
$proxy = new Clue\React\HttpProxy\ProxyConnector(
'127.0.0.1:8080',
$connector,
array(
'Proxy-Authorization' => 'Bearer abc123',
'User-Agent' => 'ReactPHP'
)
);
```

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

```php
$connector = new Connector($loop);
$proxy = new ProxyConnector('https://127.0.0.1:443', $connector);
$proxy = new Clue\React\HttpProxy\ProxyConnector(
'https://127.0.0.1:443',
new React\Socket\Connector($loop)
);

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

```php
$proxy = new ProxyConnector('http+unix:///tmp/proxy.sock', $connector);
$proxy = new Clue\React\HttpProxy\ProxyConnector(
'http+unix:///tmp/proxy.sock',
new React\Socket\Connector($loop)
);

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

```php
$proxy = new ProxyConnector('http+unix://user:pass@/tmp/proxy.sock', $connector);
$proxy = new Clue\React\HttpProxy\ProxyConnector(
'http+unix://user:pass@/tmp/proxy.sock',
new React\Socket\Connector($loop)
);
```

> Note that Unix domain sockets (UDS) are considered advanced usage and PHP only
Expand Down
5 changes: 4 additions & 1 deletion examples/01-http-request.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,10 @@
}

$loop = React\EventLoop\Factory::create();
$proxy = new Clue\React\HttpProxy\ProxyConnector($url, new React\Socket\Connector($loop));
$proxy = new Clue\React\HttpProxy\ProxyConnector(
$url,
new React\Socket\Connector($loop)
);

$connector = new React\Socket\Connector($loop, array(
'tcp' => $proxy,
Expand Down
6 changes: 4 additions & 2 deletions examples/02-optional-proxy-http-request.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,10 @@
$connector = null;
$url = getenv('http_proxy');
if ($url !== false) {
$connector = new React\Socket\Connector($loop);
$proxy = new Clue\React\HttpProxy\ProxyConnector($url, $connector);
$proxy = new Clue\React\HttpProxy\ProxyConnector(
$url,
new React\Socket\Connector($loop)
);
$connector = new React\Socket\Connector($loop, array(
'tcp' => $proxy,
'timeout' => 3.0,
Expand Down
18 changes: 9 additions & 9 deletions examples/11-proxy-raw-https-protocol.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,6 @@
// For illustration purposes only. If you want to send HTTP requests in a real
// world project, take a look at example #01, example #02 and https://github.com/reactphp/http#client-usage.

use Clue\React\HttpProxy\ProxyConnector;
use React\Socket\Connector;
use React\Socket\ConnectionInterface;

require __DIR__ . '/../vendor/autoload.php';

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

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

$proxy = new ProxyConnector($url, new Connector($loop));
$connector = new Connector($loop, array(
$proxy = new Clue\React\HttpProxy\ProxyConnector(
$url,
new React\Socket\Connector($loop)
);

$connector = new React\Socket\Connector($loop, array(
'tcp' => $proxy,
'timeout' => 3.0,
'dns' => false
));

$connector->connect('tls://google.com:443')->then(function (ConnectionInterface $stream) {
$stream->write("GET / HTTP/1.1\r\nHost: google.com\r\nConnection: close\r\n\r\n");
$stream->on('data', function ($chunk) {
$connector->connect('tls://google.com:443')->then(function (React\Socket\ConnectionInterface $connection) {
$connection->write("GET / HTTP/1.1\r\nHost: google.com\r\nConnection: close\r\n\r\n");
$connection->on('data', function ($chunk) {
echo $chunk;
});
}, function (Exception $e) {
Expand Down
19 changes: 9 additions & 10 deletions examples/12-optional-proxy-raw-https-protocol.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,29 +20,28 @@
// For illustration purposes only. If you want to send HTTP requests in a real
// world project, take a look at example #01, example #02 and https://github.com/reactphp/http#client-usage.

use Clue\React\HttpProxy\ProxyConnector;
use React\Socket\Connector;
use React\Socket\ConnectionInterface;

require __DIR__ . '/../vendor/autoload.php';

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

$connector = new Connector($loop);
$connector = new React\Socket\Connector($loop);

$url = getenv('http_proxy');
if ($url !== false) {
$proxy = new ProxyConnector($url, $connector);
$connector = new Connector($loop, array(
$proxy = new Clue\React\HttpProxy\ProxyConnector(
$url,
$connector
);
$connector = new React\Socket\Connector($loop, array(
'tcp' => $proxy,
'timeout' => 3.0,
'dns' => false
));
}

$connector->connect('tls://google.com:443')->then(function (ConnectionInterface $stream) {
$stream->write("GET / HTTP/1.1\r\nHost: google.com\r\nConnection: close\r\n\r\n");
$stream->on('data', function ($chunk) {
$connector->connect('tls://google.com:443')->then(function (React\Socket\ConnectionInterface $connection) {
$connection->write("GET / HTTP/1.1\r\nHost: google.com\r\nConnection: close\r\n\r\n");
$connection->on('data', function ($chunk) {
echo $chunk;
});
}, function (Exception $e) {
Expand Down
Loading
0