Merge pull request #375 from clue-labs/docs

Improve documentation and use fully-qualified class names throughout the documentation

src/Browser.php

@@ -2,16 +2,15 @@
 
 namespace React\Http;
 
+use Psr\Http\Message\ResponseInterface;
+use React\EventLoop\LoopInterface;
+use React\Http\Io\MessageFactory;
 use React\Http\Io\Sender;
 use React\Http\Io\Transaction;
-use React\Http\Message\MessageFactory;
-use InvalidArgumentException;
-use Psr\Http\Message\RequestInterface;
-use Psr\Http\Message\UriInterface;
-use React\EventLoop\LoopInterface;
 use React\Promise\PromiseInterface;
 use React\Socket\ConnectorInterface;
 use React\Stream\ReadableStreamInterface;
+use InvalidArgumentException;
 
 /**
  * @final This class is final and shouldn't be extended as it is likely to be marked final in a future relase.
@@ -719,7 +718,7 @@ private function withOptions(array $options)
 
     /**
      * @param string                         $method
-     * @param string|UriInterface            $url
+     * @param string                         $url
      * @param array                          $headers
      * @param string|ReadableStreamInterface $contents
      * @return PromiseInterface<ResponseInterface,Exception>

src/Message/MessageFactory.php → src/Io/MessageFactory.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace React\Http\Message;
+namespace React\Http\Io;
 
 use Psr\Http\Message\StreamInterface;
 use Psr\Http\Message\UriInterface;

src/Message/ReadableBodyStream.php → src/Io/ReadableBodyStream.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace React\Http\Message;
+namespace React\Http\Io;
 
 use Evenement\EventEmitter;
 use Psr\Http\Message\StreamInterface;

src/Io/Sender.php

@@ -2,7 +2,6 @@
 
 namespace React\Http\Io;
 
-use React\Http\Message\MessageFactory;
 use Psr\Http\Message\RequestInterface;
 use React\EventLoop\LoopInterface;
 use React\Http\Client\Client as HttpClient;

src/Io/Transaction.php

@@ -2,12 +2,11 @@
 
 namespace React\Http\Io;
 
-use React\Http\Message\ResponseException;
-use React\Http\Message\MessageFactory;
 use Psr\Http\Message\RequestInterface;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\UriInterface;
 use React\EventLoop\LoopInterface;
+use React\Http\Message\ResponseException;
 use React\Promise\Deferred;
 use React\Promise\PromiseInterface;
 use React\Stream\ReadableStreamInterface;

src/Message/Response.php

@@ -25,10 +25,9 @@
  * which in turn extends the
  * [PSR-7 `MessageInterface`](https://www.php-fig.org/psr/psr-7/#31-psrhttpmessagemessageinterface).
  *
- * > Internally, this class extends the underlying `\RingCentral\Psr7\Response`
- *   class. The only difference is that this class will accept implemenations
- *   of ReactPHPs `ReadableStreamInterface` for the `$body` argument. This base
- *   class is considered an implementation detail that may change in the future.
+ * > Internally, this implementation builds on top of an existing incoming
+ *   response message and only adds required streaming support. This base class is
+ *   considered an implementation detail that may change in the future.
  *
  * @see \Psr\Http\Message\ResponseInterface
  */

src/Message/ResponseException.php

@@ -6,7 +6,7 @@
 use Psr\Http\Message\ResponseInterface;
 
 /**
- * The `ResponseException` is an `Exception` sub-class that will be used to reject
+ * The `React\Http\Message\ResponseException` is an `Exception` sub-class that will be used to reject
  * a request promise if the remote server returns a non-success status code
  * (anything but 2xx or 3xx).
  * You can control this behavior via the [`withRejectErrorResponse()` method](#withrejecterrorresponse).
@@ -32,7 +32,7 @@ public function __construct(ResponseInterface $response, $message = null, $code
     }
 
     /**
-     * Access its underlying [`ResponseInterface`](#responseinterface) object.
+     * Access its underlying response object.
      *
      * @return ResponseInterface
      */

src/Middleware/LimitConcurrentRequestsMiddleware.php

@@ -29,10 +29,10 @@
  * than 10 handlers will be invoked at once:
  *
  * ```php
- * $server = new Server(
+ * $server = new React\Http\Server(
  *     $loop,
- *     new StreamingRequestMiddleware(),
- *     new LimitConcurrentRequestsMiddleware(10),
+ *     new React\Http\Middleware\StreamingRequestMiddleware(),
+ *     new React\Http\Middleware\LimitConcurrentRequestsMiddleware(10),
  *     $handler
  * );
  * ```
@@ -42,12 +42,12 @@
  * to limit the total number of requests that can be buffered at once:
  *
  * ```php
- * $server = new Server(
+ * $server = new React\Http\Server(
  *     $loop,
- *     new StreamingRequestMiddleware(),
- *     new LimitConcurrentRequestsMiddleware(100), // 100 concurrent buffering handlers
- *     new RequestBodyBufferMiddleware(2 * 1024 * 1024), // 2 MiB per request
- *     new RequestBodyParserMiddleware(),
+ *     new React\Http\Middleware\StreamingRequestMiddleware(),
+ *     new React\Http\Middleware\LimitConcurrentRequestsMiddleware(100), // 100 concurrent buffering handlers
+ *     new React\Http\Middleware\RequestBodyBufferMiddleware(2 * 1024 * 1024), // 2 MiB per request
+ *     new React\Http\Middleware\RequestBodyParserMiddleware(),
  *     $handler
  * );
  * ```
@@ -57,13 +57,13 @@
  * processes one request after another without any concurrency:
  *
  * ```php
- * $server = new Server(
+ * $server = new React\Http\Server(
  *     $loop,
- *     new StreamingRequestMiddleware(),
- *     new LimitConcurrentRequestsMiddleware(100), // 100 concurrent buffering handlers
- *     new RequestBodyBufferMiddleware(2 * 1024 * 1024), // 2 MiB per request
- *     new RequestBodyParserMiddleware(),
- *     new LimitConcurrentRequestsMiddleware(1), // only execute 1 handler (no concurrency)
+ *     new React\Http\Middleware\StreamingRequestMiddleware(),
+ *     new React\Http\Middleware\LimitConcurrentRequestsMiddleware(100), // 100 concurrent buffering handlers
+ *     new React\Http\Middleware\RequestBodyBufferMiddleware(2 * 1024 * 1024), // 2 MiB per request
+ *     new React\Http\Middleware\RequestBodyParserMiddleware(),
+ *     new React\Http\Middleware\LimitConcurrentRequestsMiddleware(1), // only execute 1 handler (no concurrency)
  *     $handler
  * );
  * ```

src/Server.php

@@ -14,7 +14,7 @@
 use React\Socket\ServerInterface;
 
 /**
- * The `Server` class is responsible for handling incoming connections and then
+ * The `React\Http\Server` class is responsible for handling incoming connections and then
  * processing each incoming HTTP request.
  *
  * When a complete HTTP request has been received, it will invoke the given
@@ -292,9 +292,9 @@ public function __construct(LoopInterface $loop)
      *
      * @param ServerInterface $socket
      */
-    public function listen(ServerInterface $server)
+    public function listen(ServerInterface $socket)
     {
-        $this->streamingServer->listen($server);
+        $this->streamingServer->listen($socket);
     }
 
     /**

tests/Message/MessageFactoryTest.php → tests/Io/MessageFactoryTest.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace React\Tests\Http\Message;
+namespace React\Tests\Http\Io;
 
-use React\Http\Message\MessageFactory;
+use React\Http\Io\MessageFactory;
 use PHPUnit\Framework\TestCase;
 
 class MessageFactoryTest extends TestCase

tests/Message/ReadableBodyStreamTest.php → tests/Io/ReadableBodyStreamTest.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace React\Tests\Http\Message;
+namespace React\Tests\Http\Io;
 
-use React\Http\Message\ReadableBodyStream;
+use React\Http\Io\ReadableBodyStream;
 use React\Tests\Http\TestCase;
 use React\Stream\ThroughStream;
 

tests/Io/SenderTest.php

@@ -5,8 +5,8 @@
 use Clue\React\Block;
 use React\Http\Client\Client as HttpClient;
 use React\Http\Client\RequestData;
+use React\Http\Io\ReadableBodyStream;
 use React\Http\Io\Sender;
-use React\Http\Message\ReadableBodyStream;
 use React\Promise;
 use React\Stream\ThroughStream;
 use React\Tests\Http\TestCase;
@@ -26,7 +26,7 @@ public function setUpLoop()
 
     public function testCreateFromLoop()
     {
-        $sender = Sender::createFromLoop($this->loop, null, $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = Sender::createFromLoop($this->loop, null, $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $this->assertInstanceOf('React\Http\Io\Sender', $sender);
     }
@@ -36,7 +36,7 @@ public function testSenderRejectsInvalidUri()
         $connector = $this->getMockBuilder('React\Socket\ConnectorInterface')->getMock();
         $connector->expects($this->never())->method('connect');
 
-        $sender = new Sender(new HttpClient($this->loop, $connector), $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender(new HttpClient($this->loop, $connector), $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $request = new Request('GET', 'www.google.com');
 
@@ -51,7 +51,7 @@ public function testSenderConnectorRejection()
         $connector = $this->getMockBuilder('React\Socket\ConnectorInterface')->getMock();
         $connector->expects($this->once())->method('connect')->willReturn(Promise\reject(new \RuntimeException('Rejected')));
 
-        $sender = new Sender(new HttpClient($this->loop, $connector), $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender(new HttpClient($this->loop, $connector), $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $request = new Request('GET', 'http://www.google.com/');
 
@@ -71,7 +71,7 @@ public function testSendPostWillAutomaticallySendContentLengthHeader()
             '1.1'
         )->willReturn($this->getMockBuilder('React\Http\Client\Request')->disableOriginalConstructor()->getMock());
 
-        $sender = new Sender($client, $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender($client, $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $request = new Request('POST', 'http://www.google.com/', array(), 'hello');
         $sender->send($request);
@@ -87,7 +87,7 @@ public function testSendPostWillAutomaticallySendContentLengthZeroHeaderForEmpty
             '1.1'
         )->willReturn($this->getMockBuilder('React\Http\Client\Request')->disableOriginalConstructor()->getMock());
 
-        $sender = new Sender($client, $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender($client, $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $request = new Request('POST', 'http://www.google.com/', array(), '');
         $sender->send($request);
@@ -106,7 +106,7 @@ public function testSendPostStreamWillAutomaticallySendTransferEncodingChunked()
             '1.1'
         )->willReturn($outgoing);
 
-        $sender = new Sender($client, $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender($client, $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $stream = new ThroughStream();
         $request = new Request('POST', 'http://www.google.com/', array(), new ReadableBodyStream($stream));
@@ -122,7 +122,7 @@ public function testSendPostStreamWillAutomaticallyPipeChunkEncodeBodyForWriteAn
         $client = $this->getMockBuilder('React\Http\Client\Client')->disableOriginalConstructor()->getMock();
         $client->expects($this->once())->method('request')->willReturn($outgoing);
 
-        $sender = new Sender($client, $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender($client, $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $stream = new ThroughStream();
         $request = new Request('POST', 'http://www.google.com/', array(), new ReadableBodyStream($stream));
@@ -142,7 +142,7 @@ public function testSendPostStreamWillAutomaticallyPipeChunkEncodeBodyForEnd()
         $client = $this->getMockBuilder('React\Http\Client\Client')->disableOriginalConstructor()->getMock();
         $client->expects($this->once())->method('request')->willReturn($outgoing);
 
-        $sender = new Sender($client, $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender($client, $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $stream = new ThroughStream();
         $request = new Request('POST', 'http://www.google.com/', array(), new ReadableBodyStream($stream));
@@ -162,7 +162,7 @@ public function testSendPostStreamWillRejectWhenRequestBodyEmitsErrorEvent()
         $client = $this->getMockBuilder('React\Http\Client\Client')->disableOriginalConstructor()->getMock();
         $client->expects($this->once())->method('request')->willReturn($outgoing);
 
-        $sender = new Sender($client, $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender($client, $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $expected = new \RuntimeException();
         $stream = new ThroughStream();
@@ -192,7 +192,7 @@ public function testSendPostStreamWillRejectWhenRequestBodyClosesWithoutEnd()
         $client = $this->getMockBuilder('React\Http\Client\Client')->disableOriginalConstructor()->getMock();
         $client->expects($this->once())->method('request')->willReturn($outgoing);
 
-        $sender = new Sender($client, $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender($client, $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $stream = new ThroughStream();
         $request = new Request('POST', 'http://www.google.com/', array(), new ReadableBodyStream($stream));
@@ -220,7 +220,7 @@ public function testSendPostStreamWillNotRejectWhenRequestBodyClosesAfterEnd()
         $client = $this->getMockBuilder('React\Http\Client\Client')->disableOriginalConstructor()->getMock();
         $client->expects($this->once())->method('request')->willReturn($outgoing);
 
-        $sender = new Sender($client, $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender($client, $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $stream = new ThroughStream();
         $request = new Request('POST', 'http://www.google.com/', array(), new ReadableBodyStream($stream));
@@ -247,7 +247,7 @@ public function testSendPostStreamWithExplicitContentLengthWillSendHeaderAsIs()
             '1.1'
         )->willReturn($this->getMockBuilder('React\Http\Client\Request')->disableOriginalConstructor()->getMock());
 
-        $sender = new Sender($client, $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender($client, $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $stream = new ThroughStream();
         $request = new Request('POST', 'http://www.google.com/', array('Content-Length' => '100'), new ReadableBodyStream($stream));
@@ -264,7 +264,7 @@ public function testSendGetWillNotPassContentLengthHeaderForEmptyRequestBody()
             '1.1'
         )->willReturn($this->getMockBuilder('React\Http\Client\Request')->disableOriginalConstructor()->getMock());
 
-        $sender = new Sender($client, $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender($client, $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $request = new Request('GET', 'http://www.google.com/');
         $sender->send($request);
@@ -280,7 +280,7 @@ public function testSendCustomMethodWillNotPassContentLengthHeaderForEmptyReques
             '1.1'
         )->willReturn($this->getMockBuilder('React\Http\Client\Request')->disableOriginalConstructor()->getMock());
 
-        $sender = new Sender($client, $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender($client, $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $request = new Request('CUSTOM', 'http://www.google.com/');
         $sender->send($request);
@@ -296,7 +296,7 @@ public function testSendCustomMethodWithExplicitContentLengthZeroWillBePassedAsI
             '1.1'
         )->willReturn($this->getMockBuilder('React\Http\Client\Request')->disableOriginalConstructor()->getMock());
 
-        $sender = new Sender($client, $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender($client, $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $request = new Request('CUSTOM', 'http://www.google.com/', array('Content-Length' => '0'));
         $sender->send($request);
@@ -311,7 +311,7 @@ public function testCancelRequestWillCancelConnector()
         $connector = $this->getMockBuilder('React\Socket\ConnectorInterface')->getMock();
         $connector->expects($this->once())->method('connect')->willReturn($promise);
 
-        $sender = new Sender(new HttpClient($this->loop, $connector), $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender(new HttpClient($this->loop, $connector), $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $request = new Request('GET', 'http://www.google.com/');
 
@@ -330,7 +330,7 @@ public function testCancelRequestWillCloseConnection()
         $connector = $this->getMockBuilder('React\Socket\ConnectorInterface')->getMock();
         $connector->expects($this->once())->method('connect')->willReturn(Promise\resolve($connection));
 
-        $sender = new Sender(new HttpClient($this->loop, $connector), $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender(new HttpClient($this->loop, $connector), $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
 
         $request = new Request('GET', 'http://www.google.com/');
 
@@ -387,7 +387,7 @@ public function testRequestProtocolVersion(Request $Request, $method, $uri, $hea
 
         $http->expects($this->once())->method('request')->with($method, $uri, $headers, $protocolVersion)->willReturn($request);
 
-        $sender = new Sender($http, $this->getMockBuilder('React\Http\Message\MessageFactory')->getMock());
+        $sender = new Sender($http, $this->getMockBuilder('React\Http\Io\MessageFactory')->getMock());
         $sender->send($Request);
     }
 }

tests/Io/TransactionTest.php

@@ -3,16 +3,16 @@
 namespace React\Tests\Http\Io;
 
 use Clue\React\Block;
-use React\Http\Io\Transaction;
-use React\Http\Message\MessageFactory;
-use React\Http\Message\ResponseException;
-use React\Tests\Http\TestCase;
 use PHPUnit\Framework\MockObject\MockObject;
 use Psr\Http\Message\RequestInterface;
+use React\Http\Io\MessageFactory;
+use React\Http\Io\Transaction;
+use React\Http\Message\ResponseException;
 use React\EventLoop\Factory;
 use React\Promise;
 use React\Promise\Deferred;
 use React\Stream\ThroughStream;
+use React\Tests\Http\TestCase;
 use RingCentral\Psr7\Response;
 
 class TransactionTest extends TestCase