Improve documentation for examples and link to other projects

README.md

@@ -237,8 +237,8 @@ HTTP operates on a higher layer than this low-level SOCKS implementation.
 If you want to issue HTTP requests, you can add a dependency for
 [clue/reactphp-buzz](https://github.com/clue/reactphp-buzz).
 It can interact with this library by issuing all
-[http requests through a SOCKS server](https://github.com/clue/reactphp-buzz#socks-proxy).
-This works for both plain HTTP and SSL encrypted HTTPS requests.
+[HTTP requests through a SOCKS proxy server](https://github.com/clue/reactphp-buzz#socks-proxy).
+This works for both plain HTTP and TLS-encrypted HTTPS requests.
 
 #### Protocol version
 

examples/01-http.php

@@ -1,5 +1,13 @@
 <?php
 
+// A simple example which requests http://www.google.com/ through a SOCKS proxy.
+// The proxy can be given as first argument and defaults to localhost:1080 otherwise.
+//
+// Not already running a SOCKS proxy server? See also example #11 or try this: `ssh -D 1080 localhost`
+//
+// For illustration purposes only. If you want to send HTTP requests in a real
+// world project, take a look at https://github.com/clue/reactphp-buzz#socks-proxy
+
 use Clue\React\Socks\Client;
 use React\Socket\Connector;
 use React\Socket\ConnectionInterface;

examples/02-https.php

@@ -1,5 +1,13 @@
 <?php
 
+// A simple example which requests https://www.google.com/ through a SOCKS proxy.
+// The proxy can be given as first argument and defaults to localhost:1080 otherwise.
+//
+// Not already running a SOCKS proxy server? See also example #11 or try this: `ssh -D 1080 localhost`
+//
+// For illustration purposes only. If you want to send HTTP requests in a real
+// world project, take a look at https://github.com/clue/reactphp-buzz#socks-proxy
+
 use Clue\React\Socks\Client;
 use React\Socket\Connector;
 use React\Socket\ConnectionInterface;

examples/03-proxy-chaining.php

@@ -1,5 +1,13 @@
 <?php
 
+// A more advanced example which requests http://www.google.com/ through a chain of SOCKS proxy servers.
+// The proxy servers can be given as arguments.
+//
+// Not already running a SOCKS proxy server? See also example #11 or try this: `ssh -D 1080 localhost`
+//
+// For illustration purposes only. If you want to send HTTP requests in a real
+// world project, take a look at https://github.com/clue/reactphp-buzz#socks-proxy
+
 use Clue\React\Socks\Client;
 use React\Socket\Connector;
 use React\Socket\ConnectionInterface;

examples/04-local-dns.php

@@ -1,5 +1,13 @@
 <?php
 
+// A simple example which requests https://www.google.com/ through a SOCKS proxy with local DNS resolution.
+// The proxy can be given as first argument and defaults to localhost:1080 otherwise.
+//
+// Not already running a SOCKS proxy server? See also example #11 or try this: `ssh -D 1080 localhost`
+//
+// For illustration purposes only. If you want to send HTTP requests in a real
+// world project, take a look at https://github.com/clue/reactphp-buzz#socks-proxy
+
 use Clue\React\Socks\Client;
 use React\Socket\Connector;
 use React\Socket\ConnectionInterface;

examples/11-server.php

@@ -1,5 +1,10 @@
 <?php
 
+// A simple example which runs a SOCKS proxy server.
+// The listen address can be given as first argument and defaults to localhost:1080 otherwise.
+//
+// See also examples #01 and #02 for the client side.
+
 use Clue\React\Socks\Server;
 use React\Socket\Server as Socket;
 

examples/12-server-with-password.php

@@ -1,5 +1,16 @@
 <?php
 
+// A simple example which runs a SOCKS proxy server with hard-coded authentication details.
+// The listen address can be given as first argument and defaults to localhost:1080 otherwise.
+//
+// See also examples #01 and #02 for the client side.
+//
+// Note that the client examples do not pass any authentication details by default
+// and as such will fail to authenticate against this example server. You can
+// explicitly pass authentication details to the client example like this:
+//
+// $ php examples/01-http.php tom:god@localhost:1080
+
 use Clue\React\Socks\Server;
 use React\Socket\Server as Socket;
 

examples/13-server-blacklist.php

@@ -1,6 +1,12 @@
 <?php
 
-// A SOCKS server that rejects connections to some domains (blacklist / filtering)
+// A more advanced example which runs a SOCKS proxy server that rejects connections
+// to some domains (blacklist /filtering).
+// The listen address can be given as first argument and defaults to localhost:1080 otherwise.
+//
+// See also examples #01 and #02 for the client side.
+// Client example #01 is expected to fail because port 80 is blocked in this server example.
+// Client example #02 is expected to succceed because it is not blacklisted.
 
 use React\EventLoop\Factory as LoopFactory;
 use ConnectionManager\Extra\Multiple\ConnectionManagerSelective;

examples/21-server-proxy-chaining.php

@@ -1,6 +1,11 @@
 <?php
 
-// A SOCKS server that forwards (proxy chaining) to other SOCKS servers
+// A more advanced example which runs a SOCKS proxy server that forwards to
+// other SOCKS servers (proxy chaining).
+// The listen address can be given as first argument.
+// The upstream proxy servers can be given as additional arguments.
+//
+// See also examples #01 and #02 for the client side.
 
 use Clue\React\Socks\Client;
 use Clue\React\Socks\Server;

examples/22-server-proxy-chaining-from-random-pool.php

@@ -1,6 +1,11 @@
 <?php
 
-// A SOCKS server that randomly forwards (proxy chaining) to a pool of SOCKS servers
+// A more advanced example which runs a SOCKS proxy server that randomly forwards
+// to a pool of SOCKS servers (random proxy chaining).
+// The listen address can be given as first argument.
+// The upstream proxy servers can be given as additional arguments.
+//
+// See also examples #01 and #02 for the client side.
 
 use React\EventLoop\Factory as LoopFactory;
 use ConnectionManager\Extra\Multiple\ConnectionManagerRandom;

examples/31-server-secure.php

@@ -1,5 +1,10 @@
 <?php
 
+// A more advanced example which runs a secure SOCKS over TLS proxy server.
+// The listen address can be given as first argument and defaults to localhost:1080 otherwise.
+//
+// See also example #32 for the client side.
+
 use Clue\React\Socks\Server;
 use React\Socket\Server as Socket;
 

examples/32-http-secure.php

@@ -1,5 +1,13 @@
 <?php
 
+// A more advanced example which requests http://google.com/ through a secure SOCKS over TLS proxy.
+// The proxy can be given as first argument and defaults to localhost:1080 otherwise.
+//
+// See also example #31 for the server side.
+//
+// For illustration purposes only. If you want to send HTTP requests in a real
+// world project, take a look at https://github.com/clue/reactphp-buzz#socks-proxy
+
 use Clue\React\Socks\Client;
 use React\Socket\Connector;
 use React\Socket\ConnectionInterface;