diff --git a/README.md b/README.md index a4ffe14..980fc50 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![installs on Packagist](https://img.shields.io/packagist/dt/clue/http-proxy-react?color=blue&label=installs%20on%20Packagist)](https://packagist.org/packages/clue/http-proxy-react) Async HTTP proxy connector, tunnel any TCP/IP-based protocol through an HTTP -CONNECT proxy server, built on top of [ReactPHP](https://reactphp.org). +CONNECT proxy server, built on top of [ReactPHP](https://reactphp.org/). HTTP CONNECT proxy servers (also commonly known as "HTTPS proxy" or "SSL proxy") are commonly used to tunnel HTTPS traffic through an intermediary ("proxy"), to @@ -71,20 +71,24 @@ The following example code demonstrates how this library can be used to send a secure HTTPS request to google.com through a local HTTP proxy server: ```php + $proxy, - 'timeout' => 3.0, 'dns' => false )); -$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'); +$browser = new React\Http\Browser($connector); + +$browser->get('https://google.com/')->then(function (Psr\Http\Message\ResponseInterface $response) { + var_dump($response->getHeaders(), (string) $response->getBody()); +}, function (Exception $e) { + echo 'Error: ' . $e->getMessage() . PHP_EOL; +}); ``` See also the [examples](examples). @@ -334,7 +338,7 @@ 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 Clue\React\HttpProxy\ProxyConnector('user:pass@127.0.0.1:8080'); +$proxy = new Clue\React\HttpProxy\ProxyConnector('alice:password@127.0.0.1:8080'); ``` Note that both the username and password must be percent-encoded if they contain @@ -415,7 +419,7 @@ Similarly, you can also combine this with [authentication](#authentication) like this: ```php -$proxy = new Clue\React\HttpProxy\ProxyConnector('http+unix://user:pass@/tmp/proxy.sock'); +$proxy = new Clue\React\HttpProxy\ProxyConnector('http+unix://alice:password@/tmp/proxy.sock'); ``` > Note that Unix domain sockets (UDS) are considered advanced usage and PHP only @@ -430,7 +434,7 @@ $proxy = new Clue\React\HttpProxy\ProxyConnector('http+unix://user:pass@/tmp/pro ## Install -The recommended way to install this library is [through Composer](https://getcomposer.org). +The recommended way to install this library is [through Composer](https://getcomposer.org/). [New to Composer?](https://getcomposer.org/doc/00-intro.md) This project follows [SemVer](https://semver.org/). @@ -445,12 +449,12 @@ See also the [CHANGELOG](CHANGELOG.md) for details about version upgrades. This project aims to run on any platform and thus does not require any PHP extensions and supports running on legacy PHP 5.3 through current PHP 8+ and HHVM. -It's *highly recommended to use PHP 7+* for this project. +It's *highly recommended to use the latest supported PHP version* for this project. ## Tests To run the test suite, you first need to clone this repo and then install all -dependencies [through Composer](https://getcomposer.org): +dependencies [through Composer](https://getcomposer.org/): ```bash $ composer install @@ -459,14 +463,14 @@ $ composer install To run the test suite, go to the project root and run: ```bash -$ php vendor/bin/phpunit +$ vendor/bin/phpunit ``` The test suite contains tests that rely on a working internet connection, alternatively you can also run it like this: ```bash -$ php vendor/bin/phpunit --exclude-group internet +$ vendor/bin/phpunit --exclude-group internet ``` ## License diff --git a/composer.json b/composer.json index 13f6e0e..9840cf0 100644 --- a/composer.json +++ b/composer.json @@ -10,12 +10,6 @@ "email": "christian@clue.engineering" } ], - "autoload": { - "psr-4": { "Clue\\React\\HttpProxy\\": "src/" } - }, - "autoload-dev": { - "psr-4": { "Clue\\Tests\\React\\HttpProxy\\": "tests/" } - }, "require": { "php": ">=5.3", "react/promise": " ^2.1 || ^1.2.1", @@ -27,5 +21,11 @@ "phpunit/phpunit": "^9.3 || ^5.7 || ^4.8", "react/event-loop": "^1.2", "react/http": "^1.5" + }, + "autoload": { + "psr-4": { "Clue\\React\\HttpProxy\\": "src/" } + }, + "autoload-dev": { + "psr-4": { "Clue\\Tests\\React\\HttpProxy\\": "tests/" } } } diff --git a/examples/01-http-request.php b/examples/01-http-request.php index 4bbbbf4..f6741d9 100644 --- a/examples/01-http-request.php +++ b/examples/01-http-request.php @@ -5,20 +5,20 @@ // // $ php leproxy.php // -// The proxy defaults to localhost:8080. +// The proxy defaults to 127.0.0.1:8080. // To run the example go to the project root and run: // // $ php examples/01-http-request.php // // To run the same example with your proxy, the proxy URL can be given as an environment variable: // -// $ http_proxy=127.0.0.2:8080 php examples/01-http-request.php +// $ http_proxy=127.0.0.1:8080 php examples/01-http-request.php require __DIR__ . '/../vendor/autoload.php'; $url = getenv('http_proxy'); if ($url === false) { - $url = 'localhost:8080'; + $url = '127.0.0.1:8080'; } $proxy = new Clue\React\HttpProxy\ProxyConnector($url); diff --git a/examples/02-optional-proxy-http-request.php b/examples/02-optional-proxy-http-request.php index be340c3..820aa4c 100644 --- a/examples/02-optional-proxy-http-request.php +++ b/examples/02-optional-proxy-http-request.php @@ -11,7 +11,7 @@ // // To run the same example with your proxy, the proxy URL can be given as an environment variable: // -// $ http_proxy=127.0.0.2:8080 php examples/02-optional-proxy-http-request.php +// $ http_proxy=127.0.0.1:8080 php examples/02-optional-proxy-http-request.php require __DIR__ . '/../vendor/autoload.php'; @@ -22,7 +22,6 @@ $connector = new React\Socket\Connector(array( 'tcp' => $proxy, - 'timeout' => 3.0, 'dns' => false )); } diff --git a/examples/11-proxy-raw-https-protocol.php b/examples/11-proxy-raw-https-protocol.php index 1764e99..dcfc7c5 100644 --- a/examples/11-proxy-raw-https-protocol.php +++ b/examples/11-proxy-raw-https-protocol.php @@ -5,14 +5,14 @@ // // $ php leproxy.php // -// The proxy defaults to localhost:8080. +// The proxy defaults to 127.0.0.1:8080. // To run the example, go to the project root and run: // // $ php examples/11-proxy-raw-https-protocol.php // // To run the same example with your proxy, the proxy URL can be given as an environment variable: // -// $ http_proxy=127.0.0.2:8080 php examples/11-proxy-raw-https-protocol.php +// $ http_proxy=127.0.0.1:8080 php examples/11-proxy-raw-https-protocol.php // // 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. @@ -21,7 +21,7 @@ $url = getenv('http_proxy'); if ($url === false) { - $url = 'localhost:8080'; + $url = '127.0.0.1:8080'; } $proxy = new Clue\React\HttpProxy\ProxyConnector($url); diff --git a/examples/12-optional-proxy-raw-https-protocol.php b/examples/12-optional-proxy-raw-https-protocol.php index b41246f..1aac199 100644 --- a/examples/12-optional-proxy-raw-https-protocol.php +++ b/examples/12-optional-proxy-raw-https-protocol.php @@ -11,7 +11,7 @@ // // To run the same example with your proxy, the proxy URL can be given as an environment variable: // -// $ http_proxy=127.0.0.2:8080 php examples/12-optional-proxy-raw-https-protocol.php +// $ http_proxy=127.0.0.1:8080 php examples/12-optional-proxy-raw-https-protocol.php // // This example highlights how changing from direct connection to using a proxy // actually adds very little complexity and does not mess with your actual diff --git a/examples/13-custom-proxy-headers.php b/examples/13-custom-proxy-headers.php index 56d3622..d4248f5 100644 --- a/examples/13-custom-proxy-headers.php +++ b/examples/13-custom-proxy-headers.php @@ -5,14 +5,14 @@ // // $ php leproxy.php // -// The proxy defaults to localhost:8080. +// The proxy defaults to 127.0.0.1:8080. // To run the example, go to the project root and run: // // $ php examples/13-custom-proxy-headers.php // // To run the same example with your proxy, the proxy URL can be given as an environment variable: // -// $ http_proxy=127.0.0.2:8080 php examples/13-custom-proxy-headers.php +// $ http_proxy=127.0.0.1:8080 php examples/13-custom-proxy-headers.php // // 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. @@ -21,7 +21,7 @@ $url = getenv('http_proxy'); if ($url === false) { - $url = 'localhost:8080'; + $url = '127.0.0.1:8080'; } $proxy = new Clue\React\HttpProxy\ProxyConnector( diff --git a/examples/21-proxy-raw-smtp-protocol.php b/examples/21-proxy-raw-smtp-protocol.php index 98e262a..a491d8b 100644 --- a/examples/21-proxy-raw-smtp-protocol.php +++ b/examples/21-proxy-raw-smtp-protocol.php @@ -5,14 +5,14 @@ // // $ php leproxy.php // -// The proxy defaults to localhost:8080. +// The proxy defaults to 127.0.0.1:8080. // To run the example, go to the project root and run: // // $ php examples/21-proxy-raw-smtp-protocol.php // // To run the same example with your proxy, the proxy URL can be given as an environment variable: // -// $ http_proxy=127.0.0.2:8080 php examples/21-proxy-raw-smtp-protocol.php +// $ http_proxy=127.0.0.1:8080 php examples/21-proxy-raw-smtp-protocol.php // // Please note that MANY public proxies do not allow SMTP connections, YMMV. @@ -20,7 +20,7 @@ $url = getenv('http_proxy'); if ($url === false) { - $url = 'localhost:8080'; + $url = '127.0.0.1:8080'; } $proxy = new Clue\React\HttpProxy\ProxyConnector($url); diff --git a/examples/22-proxy-raw-smtps-protocol.php b/examples/22-proxy-raw-smtps-protocol.php index 321507a..519464f 100644 --- a/examples/22-proxy-raw-smtps-protocol.php +++ b/examples/22-proxy-raw-smtps-protocol.php @@ -5,14 +5,14 @@ // // $ php leproxy.php // -// The proxy defaults to localhost:8080. +// The proxy defaults to 127.0.0.1:8080. // To run the example, go to the project root and run: // // $ php examples/22-proxy-raw-smtps-protocol.php // // To run the same example with your proxy, the proxy URL can be given as an environment variable: // -// $ http_proxy=127.0.0.2:8080 php examples/22-proxy-raw-smtps-protocol.php +// $ http_proxy=127.0.0.1:8080 php examples/22-proxy-raw-smtps-protocol.php // // This example highlights how changing from plain connections (see previous // example) to using a secure connection actually adds very little complexity @@ -23,7 +23,7 @@ $url = getenv('http_proxy'); if ($url === false) { - $url = 'localhost:8080'; + $url = '127.0.0.1:8080'; } $proxy = new Clue\React\HttpProxy\ProxyConnector($url);