Document compression streams

docs/compression-streams.md

@@ -1,3 +1,30 @@
 # Compression Streams
 
-TBD.
+This package implements compression and decompression streams based on Zlib. `ZlibOutputStream` can be used for compression, while `ZlibInputStream` can be used for decompression. Both can simply wrap an existing stream to apply them. Both accept an `$encoding` and `$options` parameter in their constructor.
+
+## Examples
+
+```php
+$inputStream = new ResourceInputStream(STDIN);
+$gzInputStream = new ZlibInputStream($inputStream, \ZLIB_ENCODING_GZIP);
+
+while (null !== $chunk = yield $gzInputStream) {
+    print $chunk;
+}
+```
+
+```php
+$outputStream = new ResourceOutputStream(STDOUT);
+$gzOutputStream = new ZlibOutputStream($outputStream, \ZLIB_ENCODING_GZIP);
+
+for ($i = 0; $i < 100; $i++) {
+    yield $gzOutputStream->write(bin2hex(random_bytes(32));
+}
+
+yield $gzOutputStream->end();
+```
+
+## See also
+
+ * [`./examples/gzip-compress.php`](../examples/gzip-compress.php)
+ * [`./examples/gzip-decompress.php`](../examples/gzip-decompress.php)

examples/gzip-compress.php

@@ -0,0 +1,19 @@
+<?php
+
+use Amp\ByteStream\ResourceInputStream;
+use Amp\ByteStream\ResourceOutputStream;
+use Amp\ByteStream\ZlibOutputStream;
+use Amp\Loop;
+
+require __DIR__ . "/../vendor/autoload.php";
+
+Loop::run(function () {
+    $stdin = new ResourceInputStream(STDIN);
+    $stdout = new ResourceOutputStream(STDOUT);
+
+    $gzout = new ZlibOutputStream($stdout, ZLIB_ENCODING_GZIP);
+
+    while (($chunk = yield $stdin->read()) !== null) {
+        yield $gzout->write($chunk);
+    }
+});

examples/gzip-decompress.php

@@ -11,7 +11,7 @@ Loop::run(function () {
     $stdin = new ResourceInputStream(STDIN);
     $stdout = new ResourceOutputStream(STDOUT);
 
-    $gzin = new ZlibInputStream($stdin);
+    $gzin = new ZlibInputStream($stdin, ZLIB_ENCODING_GZIP);
 
     while (($chunk = yield $gzin->read()) !== null) {
         yield $stdout->write($chunk);

lib/ZlibInputStream.php

@@ -5,6 +5,9 @@ namespace Amp\ByteStream;
 use Amp\Promise;
 use function Amp\call;
 
+/**
+ * Allows decompression of input streams using Zlib.
+ */
 final class ZlibInputStream implements InputStream {
     private $source;
     private $encoding;
@@ -12,11 +15,9 @@ final class ZlibInputStream implements InputStream {
     private $resource;
 
     /**
-     * ZlibInputStream constructor.
-     *
-     * @param InputStream $source
-     * @param int         $encoding
-     * @param array       $options
+     * @param InputStream $source Input stream to read compressed data from.
+     * @param int         $encoding Compression algorithm used, see `inflate_init()`.
+     * @param array       $options Algorithm options, see `inflate_init()`.
      *
      * @throws StreamException
      * @throws \Error
@@ -34,6 +35,7 @@ final class ZlibInputStream implements InputStream {
         }
     }
 
+    /** @inheritdoc */
     public function read(): Promise {
         return call(function () {
             if ($this->resource === null) {
@@ -69,15 +71,25 @@ final class ZlibInputStream implements InputStream {
         });
     }
 
-    protected function close() {
+    /** @internal */
+    private function close() {
         $this->resource = null;
         $this->source = null;
     }
 
+    /**
+     * Gets the used compression encoding.
+     *
+     * @return int Encoding specified on construction time.
+     */
     public function getEncoding(): int {
         return $this->encoding;
     }
-
+    /**
+     * Gets the used compression options.
+     *
+     * @return array Options array passed on construction time.
+     */
     public function getOptions(): array {
         return $this->options;
     }

lib/ZlibOutputStream.php

@@ -4,6 +4,9 @@ namespace Amp\ByteStream;
 
 use Amp\Promise;
 
+/**
+ * Allows compression of output streams using Zlib.
+ */
 final class ZlibOutputStream implements OutputStream {
     private $destination;
     private $encoding;
@@ -11,12 +14,11 @@ final class ZlibOutputStream implements OutputStream {
     private $resource;
 
     /**
-     * @param OutputStream $destination
-     * @param int          $encoding
-     * @param array        $options
+     * @param OutputStream $destination Output stream to write the compressed data to.
+     * @param int          $encoding Compression encoding to use, see `deflate_init()`.
+     * @param array        $options Compression options to use, see `deflate_init()`.
      *
-     * @throws StreamException
-     * @throws \Error
+     * @throws StreamException If an invalid encoding or invalid options have been passed.
      *
      * @see http://php.net/manual/en/function.deflate-init.php
      */
@@ -31,6 +33,7 @@ final class ZlibOutputStream implements OutputStream {
         }
     }
 
+    /** @inheritdoc */
     public function write(string $data): Promise {
         if ($this->resource === null) {
             throw new ClosedException("The stream has already been closed");
@@ -52,6 +55,7 @@ final class ZlibOutputStream implements OutputStream {
         return $promise;
     }
 
+    /** @inheritdoc */
     public function end(string $finalData = ""): Promise {
         if ($this->resource === null) {
             throw new ClosedException("The stream has already been closed");
@@ -73,15 +77,26 @@ final class ZlibOutputStream implements OutputStream {
         return $promise;
     }
 
-    protected function close() {
+    /** @internal */
+    private function close() {
         $this->resource = null;
         $this->destination = null;
     }
 
+    /**
+     * Gets the used compression encoding.
+     *
+     * @return int Encoding specified on construction time.
+     */
     public function getEncoding(): int {
         return $this->encoding;
     }
 
+    /**
+     * Gets the used compression options.
+     *
+     * @return array Options array passed on construction time.
+     */
     public function getOptions(): array {
         return $this->options;
     }