Merge pull request #251 from clue-labs/io

Move `@internal` classes to `React\Http\Io` namespace

Author: jsor

src/ChunkedDecoder.php src/Io/ChunkedDecoder.phpsrc/ChunkedDecoder.php renamed to src/Io/ChunkedDecoder.php

@@ -1,13 +1,20 @@
 <?php
-namespace React\Http;
+
+namespace React\Http\Io;
 
 use Evenement\EventEmitter;
 use React\Stream\ReadableStreamInterface;
-use React\Stream\WritableStreamInterface;
 use React\Stream\Util;
+use React\Stream\WritableStreamInterface;
 use Exception;
 
-/** @internal */
+/**
+ * [Internal] Decodes "Transfer-Encoding: chunked" from given stream and returns only payload data.
+ *
+ * This is used internally to decode incoming requests with this encoding.
+ *
+ * @internal
+ */
 class ChunkedDecoder extends EventEmitter implements ReadableStreamInterface
 {
     const CRLF = "\r\n";

src/ChunkedEncoder.php src/Io/ChunkedEncoder.phpsrc/ChunkedEncoder.php renamed to src/Io/ChunkedEncoder.php

@@ -1,13 +1,19 @@
 <?php
 
-namespace React\Http;
+namespace React\Http\Io;
 
 use Evenement\EventEmitter;
 use React\Stream\ReadableStreamInterface;
-use React\Stream\WritableStreamInterface;
 use React\Stream\Util;
+use React\Stream\WritableStreamInterface;
 
-/** @internal */
+/**
+ * [Internal] Encodes given payload stream with "Transfer-Encoding: chunked" and emits encoded data
+ *
+ * This is used internally to encode outgoing requests with this encoding.
+ *
+ * @internal
+ */
 class ChunkedEncoder extends EventEmitter implements ReadableStreamInterface
 {
     private $input;

src/CloseProtectionStream.php src/Io/CloseProtectionStream.phpsrc/CloseProtectionStream.php renamed to src/Io/CloseProtectionStream.php

@@ -1,14 +1,19 @@
 <?php
 
-namespace React\Http;
+namespace React\Http\Io;
 
 use Evenement\EventEmitter;
 use React\Stream\ReadableStreamInterface;
-use React\Stream\WritableStreamInterface;
 use React\Stream\Util;
+use React\Stream\WritableStreamInterface;
 
-/** @internal
- * This stream is used to protect the passed stream against closing.
+/**
+ * [Internal] Protects a given stream from actually closing and only pauses it instead.
+ *
+ * This is used internally to prevent the underlying connection from closing, so
+ * that we can still send back a response over the same stream.
+ *
+ * @internal
  * */
 class CloseProtectionStream extends EventEmitter implements ReadableStreamInterface
 {

src/HttpBodyStream.php src/Io/HttpBodyStream.phpsrc/HttpBodyStream.php renamed to src/Io/HttpBodyStream.php

@@ -1,19 +1,28 @@
 <?php
-namespace React\Http;
 
+namespace React\Http\Io;
+
+use Evenement\EventEmitter;
 use Psr\Http\Message\StreamInterface;
 use React\Stream\ReadableStreamInterface;
-use React\Stream\WritableStreamInterface;
-use Evenement\EventEmitter;
 use React\Stream\Util;
+use React\Stream\WritableStreamInterface;
 
 /**
+ * [Internal] Bridge between StreamInterface from PSR-7 and ReadableStreamInterface from ReactPHP
+ *
+ * This class is used in the server to stream the body of an incoming response
+ * from the client. This allows us to stream big amounts of data without having
+ * to buffer this data. Similarly, this used to stream the body of an outgoing
+ * request body to the client. The data will be sent directly to the client.
+ *
+ * Note that this is an internal class only and nothing you should usually care
+ * about. See the `StreamInterface` and `ReadableStreamInterface` for more
+ * details.
+ *
+ * @see StreamInterface
+ * @see ReadableStreamInterface
  * @internal
- * Uses a StreamInterface from PSR-7 and a ReadableStreamInterface from ReactPHP
- * to use PSR-7 objects and use ReactPHP streams
- * This is class is used in `HttpServer` to stream the body of a response
- * to the client. Because of this you can stream big amount of data without
- * necessity of buffering this data. The data will be send directly to the client.
  */
 class HttpBodyStream extends EventEmitter implements StreamInterface, ReadableStreamInterface
 {
@@ -22,8 +31,8 @@ class HttpBodyStream extends EventEmitter implements StreamInterface, ReadableSt
     private $size;
 
     /**
-     * @param ReadableStreamInterface $input - Stream data from $stream as a body of a PSR-7 object4
-     * @param int|null $size - size of the data body
+     * @param ReadableStreamInterface $input Stream data from $stream as a body of a PSR-7 object4
+     * @param int|null $size size of the data body
      */
     public function __construct(ReadableStreamInterface $input, $size)
     {

src/LengthLimitedStream.php src/Io/LengthLimitedStream.phpsrc/LengthLimitedStream.php renamed to src/Io/LengthLimitedStream.php

@@ -1,13 +1,20 @@
 <?php
 
-namespace React\Http;
+namespace React\Http\Io;
 
 use Evenement\EventEmitter;
 use React\Stream\ReadableStreamInterface;
-use React\Stream\WritableStreamInterface;
 use React\Stream\Util;
+use React\Stream\WritableStreamInterface;
 
-/** @internal */
+/**
+ * [Internal] Limits the amount of data the given stream can emit
+ *
+ * This is used internally to limit the size of the underlying connection stream
+ * to the size defined by the "Content-Length" header of the incoming request.
+ *
+ * @internal
+ */
 class LengthLimitedStream extends EventEmitter implements ReadableStreamInterface
 {
     private $stream;

src/Middleware/MultipartParser.php src/Io/MultipartParser.phpsrc/Middleware/MultipartParser.php renamed to src/Io/MultipartParser.php

@@ -1,13 +1,16 @@
 <?php
 
-namespace React\Http\Middleware;
+namespace React\Http\Io;
 
 use Psr\Http\Message\ServerRequestInterface;
-use React\Http\HttpBodyStream;
-use React\Http\UploadedFile;
 use RingCentral\Psr7;
 
 /**
+ * [Internal] Parses a string body with "Content-Type: multipart/form-data" into structured data
+ *
+ * This is use internally to parse incoming request bodies into structured data
+ * that resembles PHP's `$_POST` and `$_FILES` superglobals.
+ *
  * @internal
  */
 final class MultipartParser

src/RequestHeaderParser.php src/Io/RequestHeaderParser.phpsrc/RequestHeaderParser.php renamed to src/Io/RequestHeaderParser.php

@@ -1,12 +1,17 @@
 <?php
 
-namespace React\Http;
+namespace React\Http\Io;
 
 use Evenement\EventEmitter;
-use Exception;
 use RingCentral\Psr7 as g7;
+use Exception;
 
 /**
+ * [Internal] Parses an incoming request header from an input stream
+ *
+ * This is used internally to parse the request header from the connection and
+ * then process the remaining connection as the request body.
+ *
  * @event headers
  * @event error
  *

src/ServerRequest.php src/Io/ServerRequest.phpsrc/ServerRequest.php renamed to src/Io/ServerRequest.php

@@ -1,11 +1,24 @@
 <?php
 
-namespace React\Http;
+namespace React\Http\Io;
 
 use Psr\Http\Message\ServerRequestInterface;
 use RingCentral\Psr7\Request;
 
-/** @internal */
+/**
+ * [Internal] Implementation of the PSR-7 `ServerRequestInterface`
+ *
+ * This is used internally to represent each incoming request message.
+ *
+ * This implementation builds on top of an existing outgoing request message and
+ * only adds required server methods.
+ *
+ * Note that this is an internal class only and nothing you should usually care
+ * about. See the `ServerRequestInterface` for more details.
+ *
+ * @see ServerRequestInterface
+ * @internal
+ */
 class ServerRequest extends Request implements ServerRequestInterface
 {
     private $attributes = array();

src/UploadedFile.php src/Io/UploadedFile.phpsrc/UploadedFile.php renamed to src/Io/UploadedFile.php

@@ -1,13 +1,21 @@
 <?php
 
-namespace React\Http;
+namespace React\Http\Io;
 
-use InvalidArgumentException;
 use Psr\Http\Message\StreamInterface;
 use Psr\Http\Message\UploadedFileInterface;
+use InvalidArgumentException;
 use RuntimeException;
 
 /**
+ * [Internal] Implementation of the PSR-7 `UploadedFileInterface`
+ *
+ * This is used internally to represent each incoming file upload.
+ *
+ * Note that this is an internal class only and nothing you should usually care
+ * about. See the `UploadedFileInterface` for more details.
+ *
+ * @see UploadedFileInterface
  * @internal
  */
 final class UploadedFile implements UploadedFileInterface

src/Middleware/RequestBodyParserMiddleware.php

@@ -3,6 +3,7 @@
 namespace React\Http\Middleware;
 
 use Psr\Http\Message\ServerRequestInterface;
+use React\Http\Io\MultipartParser;
 
 final class RequestBodyParserMiddleware
 {