New version

Changed custom Reader interface for `castor/io` ones

Author: mnavarrocarter

README.md

@@ -41,8 +41,8 @@ as a second argument:
 ```php
 <?php
 
-use function MNC\Http\buffer;
 use function MNC\Http\fetch;
+use Castor\Io\Eof;
 
 $response = fetch('https://some-domain.example/some-form', [
     'method' => 'POST',
@@ -53,8 +53,14 @@ $response = fetch('https://some-domain.example/some-form', [
     'body' => json_encode(['data' => 'value'])
 ]);
 
-// Emit the response to stdout
-while (($chunk = $response->body()->read()) !== null) {
+// Emit the response to stdout in chunks
+while (true) {
+    $chunk = '';
+    try {
+        $response->body()->read(4096, $chunk);
+    } catch (Eof $e) {
+        break;
+    }
     echo $chunk;
 }
 ```
@@ -86,7 +92,9 @@ echo $response->status()->reasonPhrase(); // OK
 echo $response->headers()->has('content-type'); // true
 echo $response->headers()->contains('content-type', 'html'); // true
 echo $response->headers()->get('content-type'); // text/html;charset=utf-8
-echo $response->body()->read(); // Outputs some bytes from the response body
+$bytes = '';
+echo $response->body()->read(4096, $bytes); // Allocates reader data into $bytes
+echo $bytes; // Outputs some bytes from the response body
 ```
 
 ### Exception Handling
@@ -112,23 +120,23 @@ you most likely will be reacting in different ways to each one of them.
 ### Body Buffering
 
 When you call the `MNC\Http\Response::body()` method you get an instance of
-`MNC\Http\Io\Reader`, which is a very simple interface inspired in golang's
+`Castor\Io\Reader`, which is a very simple interface inspired in golang's
 `io.Reader`. This interface allows you to read a chunk of bytes until you reach
 `EOF` in the data source.
 
 Often times, you don't want to read byte per byte, but get the whole contents 
-of the body as a string at once. This library provides the `buffer` function
+of the body as a string at once. This library provides the `readAll` function
 as a convenience for that:
 
 ```php
 <?php
 
-use function MNC\Http\buffer;
+use function Castor\Io\readAll;
 use function MNC\Http\fetch;
 
 $response = fetch('https://mnavarro.dev');
 
-echo buffer($response->body()); // Buffers all the contents in memory and emits them.
+echo readAll($response->body()); // Buffers all the contents in memory and emits them.
 ````
 
 Buffering is a very good convenience, but it needs to be used with care, since it could
@@ -148,15 +156,15 @@ in content types like `text/plain`. However, there is big gain in user experienc
 when we provide helpers like these in our apis.
 
 This library provides an approach a bit more safe. If the response headers contain the
-`application/json` content type, the `MNC\Http\Io\Reader` object of the body is internally
+`application/json` content type, the ``Castor\Io\Reader`` object of the body is internally
 decorated with a `MNC\Http\Encoding\Json` object. This object implements both the
-`Reader` and `JsonDecoder` interfaces. Checking for the former is the safest way of
-handling json payloads:
+`Reader` interface. Checking for the former is the safest way of handling json
+payloads:
 
 ```php
 <?php
 
-use MNC\Http\Encoding\JsonDecoder;
+use MNC\Http\Encoding\Json;
 use function MNC\Http\fetch;
 
 $response = fetch('https://api.github.com/users/mnavarrocarter', [
@@ -167,7 +175,7 @@ $response = fetch('https://api.github.com/users/mnavarrocarter', [
 
 $body = $response->body();
 
-if ($body instanceof JsonDecoder) {
+if ($body instanceof Json) {
     var_dump($body->decode()); // Dumps the json as an array
 } else {
     // The response body is not json encoded
@@ -236,7 +244,7 @@ api, using the token internally.
 ```php
 <?php
 
-use MNC\Http\Encoding\JsonDecoder;
+use MNC\Http\Encoding\Json;
 use function MNC\Http\fetch;
 
 $authenticate = static function (string $token) {
@@ -253,7 +261,7 @@ $authenticate = static function (string $token) {
         ]);
 
         $body = $response->body();
-        if ($body instanceof JsonDecoder) {
+        if ($body instanceof Json) {
             return $body->decode();
         }
         return null;
@@ -285,7 +293,7 @@ api client that I need to use.
 ```php
 <?php
 
-use MNC\Http\Encoding\JsonDecoder;
+use MNC\Http\Encoding\Json;
 use function MNC\Http\fetch;
 
 // We start with an interface, a well defined contract.
@@ -325,7 +333,7 @@ final class FetchApiClient implements ApiClient
             ]);
 
             $body = $response->body();
-            if ($body instanceof JsonDecoder) {
+            if ($body instanceof Json) {
                 return $body->decode();
             }
             return null;

composer.json

@@ -24,8 +24,9 @@
         }
     },
     "require": {
-        "php": "^7.4|^8.0",
-        "ext-json": "*"
+        "php": ">=7.4",
+        "ext-json": "*",
+        "castor/io": "^0.2.1"
     },
     "scripts": {
         "lint": "php-cs-fixer fix",
@@ -42,6 +43,6 @@
         "amphp/http-server": "^2.1",
         "amphp/http-server-static-content": "^1.0.6",
         "mnavarrocarter/amp-http-router": "^0.1.0",
-        "friendsofphp/php-cs-fixer": "^2.16"
+        "friendsofphp/php-cs-fixer": "dev-master"
     }
 }

examples/arguments.php

@@ -1,6 +1,6 @@
 <?php
 
-use function MNC\Http\buffer;
+use function Castor\Io\readAll;
 use function MNC\Http\fetch;
 
 require_once __DIR__ . '/../vendor/autoload.php';
@@ -14,4 +14,4 @@
     'body' => json_encode(['data' => 'value'])
 ]);
 
-echo buffer($response->body()); // Emits the response
+echo readAll($response->body()); // Emits the response

examples/buffered.php

@@ -2,9 +2,9 @@
 
 require_once __DIR__ . '/../vendor/autoload.php';
 
-use function MNC\Http\buffer;
+use function Castor\Io\readAll;
 use function MNC\Http\fetch;
 
 $response = fetch('https://mnavarro.dev');
 
-echo buffer($response->body());
+echo readAll($response->body());

examples/class.php

@@ -1,6 +1,6 @@
 <?php
 
-use MNC\Http\Encoding\JsonDecoder;
+use MNC\Http\Encoding\Json;
 use function MNC\Http\fetch;
 
 require_once __DIR__ . '/../vendor/autoload.php';
@@ -42,7 +42,7 @@ public static function authenticate(string $token): FetchApiClient
             ]);
 
             $body = $response->body();
-            if ($body instanceof JsonDecoder) {
+            if ($body instanceof Json) {
                 return $body->decode();
             }
             return null;

examples/composition.php

@@ -1,6 +1,6 @@
 <?php
 
-use MNC\Http\Encoding\JsonDecoder;
+use MNC\Http\Encoding\Json;
 use function MNC\Http\fetch;
 
 $authenticated = static function (string $token) {
@@ -17,7 +17,7 @@
         ]);
 
         $body = $response->body();
-        if ($body instanceof JsonDecoder) {
+        if ($body instanceof Json) {
             return $body->decode();
         }
         return null;

examples/info.php

@@ -12,4 +12,6 @@
 echo $response->headers()->has('content-type'); // true
 echo $response->headers()->contains('content-type', 'html'); // true
 echo $response->headers()->get('content-type'); // text/html;charset=utf-8
-echo $response->body()->read(); // Outputs some bytes from the response body
+$bytes = '';
+$response->body()->read(4096, $bytes); // Reads data into $bytes
+echo $bytes; // Outputs some bytes from the response body

examples/json.php

@@ -2,7 +2,7 @@
 
 require_once __DIR__ . '/../vendor/autoload.php';
 
-use MNC\Http\Encoding\JsonDecoder;
+use MNC\Http\Encoding\Json;
 use function MNC\Http\fetch;
 
 $response = fetch('https://api.github.com/users/mnavarrocarter', [
@@ -13,6 +13,6 @@
 
 $body = $response->body();
 
-if ($body instanceof JsonDecoder) {
+if ($body instanceof Json) {
     var_dump($body->decode()); // Dumps the json as an array
 }

examples/simple.php

@@ -1,11 +1,18 @@
 <?php
 
+use Castor\Io\Eof;
 use function MNC\Http\fetch;
 
 require_once __DIR__ . '/../vendor/autoload.php';
 
 $response = fetch('https://mnavarro.dev');
 
-while (($chunk = $response->body()->read()) !== null) {
+while (true) {
+    $chunk = '';
+    try {
+        $response->body()->read(4096, $chunk);
+    } catch (Eof $e) {
+        break;
+    }
     echo $chunk;
 }

src/Encoding/Json.php

@@ -9,15 +9,15 @@
 
 namespace MNC\Http\Encoding;
 
+use Castor\Io\Error;
+use function Castor\Io\readAll;
+use Castor\Io\Reader;
 use JsonException;
-use function MNC\Http\buffer;
-use MNC\Http\Io\Reader;
-use MNC\Http\Io\ReaderError;
 
 /**
  * Class Json.
  */
-final class Json implements Reader, JsonDecoder
+final class Json implements Reader
 {
     private Reader $reader;
 
@@ -33,15 +33,18 @@ public function __construct(Reader $reader)
      * @return array<mixed, mixed>
      *
      * @throws JsonException
-     * @throws ReaderError
+     * @throws Error
      */
     public function decode(): array
     {
-        return json_decode(buffer($this->reader), true, 512, JSON_THROW_ON_ERROR);
+        return json_decode(readAll($this->reader), true, 512, JSON_THROW_ON_ERROR);
     }
 
-    public function read(int $bytes = self::DEFAULT_CHUNK_SIZE): ?string
+    /**
+     * {@inheritDoc}
+     */
+    public function read(int $length, string &$bytes): int
     {
-        return $this->reader->read($bytes);
+        return $this->reader->read($length, $bytes);
     }
 }