Support explicitly passing connectors

Author: clue

README.md

@@ -340,6 +340,44 @@ $connector->connect('tls://localhost:443')->then(function (ConnectionInterface $
   about [socket context options](http://php.net/manual/en/context.socket.php)
   and [SSL context options](http://php.net/manual/en/context.ssl.php).
 
+Advanced: By default, the `Connector` supports the `tcp://`, `tls://` and
+`unix://` URI schemes.
+For this, it sets up the required connector classes automatically.
+If you want to explicitly pass custom connectors for any of these, you can simply
+pass an instance implementing the `ConnectorInterface` like this:
+
+```php
+$dnsResolverFactory = new React\Dns\Resolver\Factory();
+$resolver = $dnsResolverFactory->createCached('127.0.1.1', $loop);
+$tcp = new DnsConnector(new TcpConnector($loop), $resolver);
+
+$tls = new SecureConnector($tcp, $loop);
+
+$unix = new UnixConnector($loop);
+
+$connector = new Connector($loop, array(
+    'tcp' => $tcp,
+    'dns' => false,
+    'tls' => $tls,
+    'unix' => $unix,
+));
+
+$connector->connect('google.com:80')->then(function (ConnectionInterface $connection) {
+    $connection->write('...');
+    $connection->end();
+});
+```
+
+> Internally, the `tcp://` connector will always be wrapped by the DNS resolver,
+  unless you disable DNS like in the above example. In this case, the `tcp://`
+  connector receives the actual hostname instead of only the resolved IP address
+  and is thus responsible for performing the lookup.
+  Internally, the automatically created `tls://` connector will always wrap the
+  underlying `tcp://` connector for establishing the underlying plaintext
+  TCP/IP connection before enabling secure TLS mode. If you want to use a custom
+  underlying `tcp://` connector for secure TLS connections only, you may
+  explicitly pass a `tls://` connector like above instead.
+
 ## Advanced Usage
 
 ### TcpConnector

src/Connector.php

@@ -37,10 +37,15 @@ public function __construct(LoopInterface $loop, array $options = array())
             'unix' => true,
         );
 
-        $tcp = new TcpConnector(
-            $loop,
-            is_array($options['tcp']) ? $options['tcp'] : array()
-        );
+        if ($options['tcp'] instanceof ConnectorInterface) {
+            $tcp = $options['tcp'];
+        } else {
+            $tcp = new TcpConnector(
+                $loop,
+                is_array($options['tcp']) ? $options['tcp'] : array()
+            );
+        }
+
         if ($options['dns'] !== false) {
             if ($options['dns'] instanceof Resolver) {
                 $resolver = $options['dns'];
@@ -60,17 +65,21 @@ public function __construct(LoopInterface $loop, array $options = array())
         }
 
         if ($options['tls'] !== false) {
-            $tls = new SecureConnector(
-                $tcp,
-                $loop,
-                is_array($options['tls']) ? $options['tls'] : array()
-            );
-            $this->connectors['tls'] = $tls;
+            if (!$options['tls'] instanceof ConnectorInterface) {
+                $options['tls'] = new SecureConnector(
+                    $tcp,
+                    $loop,
+                    is_array($options['tls']) ? $options['tls'] : array()
+                );
+            }
+            $this->connectors['tls'] = $options['tls'];
         }
 
         if ($options['unix'] !== false) {
-            $unix = new UnixConnector($loop);
-            $this->connectors['unix'] = $unix;
+            if (!$options['unix'] instanceof ConnectorInterface) {
+                $options['unix'] = new UnixConnector($loop);
+            }
+            $this->connectors['unix'] = $options['unix'];
         }
     }
 

tests/ConnectorTest.php

@@ -7,6 +7,35 @@
 
 class ConnectorTest extends TestCase
 {
+    public function testConnectorUsesTcpAsDefaultScheme()
+    {
+        $loop = $this->getMockBuilder('React\EventLoop\LoopInterface')->getMock();
+
+        $tcp = $this->getMockBuilder('React\SocketClient\ConnectorInterface')->getMock();
+        $tcp->expects($this->once())->method('connect')->with('127.0.0.1:80');
+
+        $connector = new Connector($loop, array(
+            'tcp' => $tcp
+        ));
+
+        $connector->connect('127.0.0.1:80');
+    }
+
+    public function testConnectorPassedThroughHostnameIfDnsIsDisabled()
+    {
+        $loop = $this->getMockBuilder('React\EventLoop\LoopInterface')->getMock();
+
+        $tcp = $this->getMockBuilder('React\SocketClient\ConnectorInterface')->getMock();
+        $tcp->expects($this->once())->method('connect')->with('tcp://google.com:80');
+
+        $connector = new Connector($loop, array(
+            'tcp' => $tcp,
+            'dns' => false
+        ));
+
+        $connector->connect('tcp://google.com:80');
+    }
+
     public function testConnectorWithUnknownSchemeAlwaysFails()
     {
         $loop = $this->getMockBuilder('React\EventLoop\LoopInterface')->getMock();
@@ -74,4 +103,23 @@ public function testConnectorUsesGivenResolverInstance()
 
         $connector->connect('google.com:80');
     }
+
+    public function testConnectorUsesResolvedHostnameIfDnsIsUsed()
+    {
+        $loop = $this->getMockBuilder('React\EventLoop\LoopInterface')->getMock();
+
+        $promise = new Promise(function ($resolve) { $resolve('127.0.0.1'); });
+        $resolver = $this->getMockBuilder('React\Dns\Resolver\Resolver')->disableOriginalConstructor()->getMock();
+        $resolver->expects($this->once())->method('resolve')->with('google.com')->willReturn($promise);
+
+        $tcp = $this->getMockBuilder('React\SocketClient\ConnectorInterface')->getMock();
+        $tcp->expects($this->once())->method('connect')->with('tcp://127.0.0.1:80?hostname=google.com');
+
+        $connector = new Connector($loop, array(
+            'tcp' => $tcp,
+            'dns' => $resolver
+        ));
+
+        $connector->connect('tcp://google.com:80');
+    }
 }