From 2bf2f8af067b3dc1db1532863a6b6bc7a9e8f610 Mon Sep 17 00:00:00 2001 From: Niklas Keller Date: Thu, 25 May 2017 17:51:25 +0200 Subject: [PATCH] Document compression streams --- docs/compression-streams.md | 29 ++++++++++++++++++++++++++++- examples/gzip-compress.php | 19 +++++++++++++++++++ examples/gzip-decompress.php | 2 +- lib/ZlibInputStream.php | 26 +++++++++++++++++++------- lib/ZlibOutputStream.php | 27 +++++++++++++++++++++------ 5 files changed, 88 insertions(+), 15 deletions(-) create mode 100644 examples/gzip-compress.php diff --git a/docs/compression-streams.md b/docs/compression-streams.md index dd7d4ad..69811e8 100644 --- a/docs/compression-streams.md +++ b/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) diff --git a/examples/gzip-compress.php b/examples/gzip-compress.php new file mode 100644 index 0000000..c45279b --- /dev/null +++ b/examples/gzip-compress.php @@ -0,0 +1,19 @@ +read()) !== null) { + yield $gzout->write($chunk); + } +}); diff --git a/examples/gzip-decompress.php b/examples/gzip-decompress.php index 75acbc5..267daec 100644 --- a/examples/gzip-decompress.php +++ b/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); diff --git a/lib/ZlibInputStream.php b/lib/ZlibInputStream.php index e99f5d4..55dd923 100644 --- a/lib/ZlibInputStream.php +++ b/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; } diff --git a/lib/ZlibOutputStream.php b/lib/ZlibOutputStream.php index b83a400..5b42ce3 100644 --- a/lib/ZlibOutputStream.php +++ b/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; }