clue/reactphp-zlib
, (*1)
Streaming zlib compressor and decompressor for ReactPHP,
supporting compression and decompression of GZIP, ZLIB and raw DEFLATE formats., (*2)
Table of contents, (*3)
Support us
We invest a lot of time developing, maintaining and updating our awesome
open-source projects. You can help us sustain this high-quality of our work by
becoming a sponsor on GitHub. Sponsors get
numerous benefits in return, see our sponsoring page
for details., (*4)
Let's take these projects to the next level together! 🚀, (*5)
Quickstart example
Once installed, you can use the following code to pipe a readable
gzip file stream into an decompressor which emits decompressed data events for
each individual log file chunk:, (*6)
$stream = new React\Stream\ReadableResourceStream(fopen('access.log.gz', 'r'));
$decompressor = new Clue\React\Zlib\Decompressor(ZLIB_ENCODING_GZIP);
$stream->pipe($decompressor);
$decompressor->on('data', function ($data) {
echo $data; // chunk of decompressed log data
});
See also the examples., (*7)
This library is a lightweight wrapper around the underlying zlib library.
The zlib library offers a number of different formats (sometimes referred to as encodings) detailed below., (*8)
This library supports the GZIP compression format as defined in RFC 1952.
This is one of the more common compression formats and is used in several places:, (*9)
- PHP:
ZLIB_ENCODING_GZIP (PHP 5.4+ only)
- PHP:
gzdecode() (PHP 5.4+ only) and gzencode()
- Files with
.gz file extension, e.g. .tar.gz or .tgz archives (also known as "tarballs")
-
gzip and gunzip (and family) command line tools
-
HTTP compression with
Content-Encoding: gzip header
- Java:
GZIPOutputStream
Technically, this format uses raw DEFLATE compression wrapped in a GZIP header and footer:, (*10)
10 bytes header (+ optional headers) + raw DEFLATE body + 8 bytes footer
This library supports the raw DEFLATE compression format as defined in RFC 1951.
The DEFLATE compression algorithm returns what we refer to as "raw DEFLATE format".
This raw DEFLATE format is commonly wrapped in container formats instead of being used directly:, (*11)
- PHP:
ZLIB_ENCODING_RAW (PHP 5.4+ only)
- PHP:
gzdeflate() and gzinflate()
- Wrapped in GZIP format
- Wrapped in ZLIB format
Note: This format is not to be confused with what some people call "deflate format" or "deflate encoding".
These names are commonly used to refer to what we call ZLIB format., (*12)
This library supports the ZLIB compression format as defined in RFC 1950.
This format is commonly used in a streaming context:, (*13)
- PHP:
ZLIB_ENCODING_DEFLATE (PHP 5.4+ only)
- PHP:
gzcompress() and gzuncompress()
-
HTTP compression with
Content-Encoding: deflate header
- Java:
DeflaterOutputStream
- Qt's
qCompress()
and qUncompress()
uses the ZLIB format prefixed with the uncompressed length (as UINT32BE).
Technically, this format uses raw DEFLATE compression wrapped in a ZLIB header and footer:, (*14)
2 bytes header (+ optional headers) + raw DEFLATE body + 4 bytes footer
Note: This format is often referred to as the "deflate format" or "deflate encoding".
This documentation avoids this name in order to avoid confusion with the raw DEFLATE format., (*15)
Usage
All classes use the Clue\React\Zlib namespace., (*16)
Compressor
The Compressor class can be used to compress a stream of data., (*17)
It implements the DuplexStreamInterface
and accepts uncompressed data on its writable side and emits compressed data
on its readable side., (*18)
$encoding = ZLIB_ENCODING_GZIP; // or ZLIB_ENCODING_RAW or ZLIB_ENCODING_DEFLATE
$compressor = new Clue\React\Zlib\Compressor($encoding);
$compressor->on('data', function ($data) {
echo $data; // compressed binary data chunk
});
$compressor->write($uncompressed); // write uncompressed data chunk
This is particularly useful in a piping context:, (*19)
$input->pipe($filterBadWords)->pipe($compressor)->pipe($output);
For more details, see ReactPHP's
DuplexStreamInterface., (*20)
Decompressor
The Decompressor class can be used to decompress a stream of data., (*21)
It implements the DuplexStreamInterface
and accepts compressed data on its writable side and emits decompressed data
on its readable side., (*22)
$encoding = ZLIB_ENCODING_GZIP; // or ZLIB_ENCODING_RAW or ZLIB_ENCODING_DEFLATE
$decompressor = new Clue\React\Zlib\Decompressor($encoding);
$decompressor->on('data', function ($data) {
echo $data; // decompressed data chunk
});
$decompressor->write($compressed); // write compressed binary data chunk
This is particularly useful in a piping context:, (*23)
$input->pipe($decompressor)->pipe($filterBadWords)->pipe($output);
For more details, see ReactPHP's
DuplexStreamInterface., (*24)
Install
The recommended way to install this library is through Composer.
New to Composer?, (*25)
This project follows SemVer.
This will install the latest supported version:, (*26)
composer require clue/zlib-react:^1.2
See also the CHANGELOG for details about version upgrades., (*27)
This project aims to run on any platform and thus does not require any PHP
extensions besides ext-zlib and supports running on PHP 7 through current PHP 8+.
It's highly recommended to use the latest supported PHP version for this project., (*28)
The ext-zlib extension is required for handling the underlying data compression
and decompression.
This extension is already installed as part of many PHP distributions out-of-the-box,
e.g. it ships with Debian/Ubuntu-based PHP installations and Windows-based
builds by default. If you're building PHP from source, you may have to
manually enable it., (*29)
We're committed to providing a smooth upgrade path for legacy setups.
If you need to support legacy PHP versions and legacy HHVM, you may want to
check out the legacy v0.2.x release branch.
This legacy release branch also provides an installation candidate that does not
require ext-zlib during installation but uses runtime checks instead.
In this case, you can install this project like this:, (*30)
composer require "clue/zlib-react:^1.0||^0.2.2"
Tests
To run the test suite, you first need to clone this repo and then install all
dependencies through Composer:, (*31)
composer install
To run the test suite, go to the project root and run:, (*32)
vendor/bin/phpunit
License
This project is released under the permissive MIT license., (*33)
Did you know that I offer custom development services and issuing invoices for
sponsorships of releases and for contributions? Contact me (@clue) for details., (*34)
More
-
If you want to learn more about processing streams of data, refer to the documentation of
the underlying react/stream component., (*35)
-
If you want to process compressed tarballs (.tar.gz and .tgz file extension), you may
want to use clue/reactphp-tar on the decompressed stream., (*36)
Wallogit.com
