php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #71505 Missing documentation about deflate_init() etc.
Submitted: 2016-02-03 10:03 UTC Modified: 2016-08-01 15:54 UTC
Votes:1
Avg. Score:5.0 ± 0.0
Reproduced:1 of 1 (100.0%)
Same Version:1 (100.0%)
Same OS:-1 (-100.0%)
From: salsi at icosaedro dot it Assigned: cmb (profile)
Status: Closed Package: Documentation problem
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
 [2016-02-03 10:03 UTC] salsi at icosaedro dot it
Description:
------------
The following functions are available since PHP 7.0.0 and quoted in its changelog, but their description is still missing from the manual; I add here my findings as guessed from the C source code and from the ZLIB manual in a DocBlock-like format:


/**
 * Initialize an incremental deflate context using the specified encoding.
 * Note that the 'window' option here only sets the window size of the algorithm,
 * differently from the zlib filters where the same parameter also set the
 * encoding to use; the encoding must be set with the $encoding parameter.
 * Limitation: there is no currently way to set the header informations on a
 * GZIP compressed stream, which are set as follows: GZIP signature (“\x1f\x8B”);
 * compression method (“\x08” == DEFLATE); 6 zero bytes; the operating system
 * set to the current system (“\x00” = Windows, “\x03” = Unix, etc.).
 * @param int $encoding One of:
 * ZLIB_ENCODING_RAW (DEFLATE algorithm as per RFC 1951),
 * ZLIB_ENCODING_DEFLATE (ZLIB compress algorithm as per RFC 1950) or
 * ZLIB_ENCODING_GZIP (GZIP algorithm as per RFC 1952).
 * @param int[string] $options Allowed entries are:<br>
 * 'level': compression level, range -1..9, default -1;<br>
 * 'memory': compression memory level, range 1..9, default 8;<br>
 * 'window': zlib window size (logarithm), range 8..15, default 15;<br>
 * 'strategy': one of ZLIB_FILTERED, ZLIB_HUFFMAN_ONLY, ZLIB_RLE, ZLIB_FIXED
 * or ZLIB_DEFAULT_STRATEGY (default);
 * 'dictionary': a string or an array of strings of the preset dictionary
 * (default: no preset dictionary).
 * @return resource Deflate context, or FALSE on error.
 * @triggers E_WARNING Invalid option. Failed to create the context.
 */
function deflate_init($encoding, $options = array());


/**
 * Incrementally deflate data in the specified context.
 * @param resource $context Context created with deflate_init().
 * @param string $data Chunk of data to compress.
 * @param int $flush_mode One of: ZLIB_BLOCK, ZLIB_NO_FLUSH, ZLIB_PARTIAL_FLUSH,
 * ZLIB_SYNC_FLUSH (default), ZLIB_FULL_FLUSH, ZLIB_FINISH. Normally you will
 * want to set ZLIB_NO_FLUSH here to maximize compression, and ZLIB_FINISH to
 * terminate with the last chunk of data. See the ZLIB manual at
 * {@link http://www.zlib.net/manual.html} for a detailed description of
 * these constants.
 * @return string Chunk of dompressed data, or FALSE on error.
 * @triggers E_WARNING Invalid parameters.
 */
function deflate_add($context, $data, $flush_mode = ZLIB_SYNC_FLUSH);


/**
 * Initialize an incremental inflate context with the specified encoding.
 * @param int $encoding One of:
 * ZLIB_ENCODING_RAW (DEFLATE algorithm as per RFC 1951),
 * ZLIB_ENCODING_DEFLATE (ZLIB compress algorithm as per RFC 1950) or
 * ZLIB_ENCODING_GZIP (GZIP algorithm as per RFC 1952).
 * @param int[string] $options Allowed entries are:<br>
 * 'level': compression level, range -1..9, default -1;<br>
 * 'memory': compression memory level, range 1..9, default 8;<br>
 * 'window': zlib window size (logarithm), range 8..15, default 15;<br>
 * 'strategy': one of ZLIB_FILTERED, ZLIB_HUFFMAN_ONLY, ZLIB_RLE, ZLIB_FIXED
 * or ZLIB_DEFAULT_STRATEGY (default);
 * 'dictionary': a string or an array of strings of the preset dictionary
 * (default: no preset dictionary).
 * @return resource Inflate context, or FALSE on error.
 * @triggers E_WARNING Invalid encoding. Invalid option. Failed to allocate
 * the context.
 */
function inflate_init($encoding, $options = array());

/**
 * Incrementally inflate encoded data in the specified context.
 * Limitation: header informations from GZIP compressed data are not made
 * available.
 * @param resource $context Context created with inflate_init().
 * @param string $encoded_data Chunk of compressed data.
 * @param int $flush_mode One of: ZLIB_BLOCK, ZLIB_NO_FLUSH, ZLIB_PARTIAL_FLUSH,
 * ZLIB_SYNC_FLUSH (default), ZLIB_FULL_FLUSH, ZLIB_FINISH. Normally you will
 * want to set ZLIB_NO_FLUSH to maximize speed, and ZLIB_FINISH to
 * terminate with the last block of data. See the ZLIB manual at
 * {@link http://www.zlib.net/manual.html} for a detailed description of
 * these constants.
 * @return string Chunk of decompressed data, or FALSE on error.
 * @triggers E_WARNING Invalid parameters. Inflating this data requires a preset
 * dictionary, please specify it in the options array of inflate_init().
 * Corrupted compressed stream or invalid checksum (whenever available).
 */
function inflate_add($context, $encoded_data, $flush_mode = ZLIB_SYNC_FLUSH);


A very simple example of use:

// Performs GZIP compression:
$deflateContext = deflate_init(ZLIB_ENCODING_GZIP);
$compressed = deflate_add($deflateContext, "Data to compress", ZLIB_NO_FLUSH);
$compressed .= deflate_add($deflateContext, ", more data", ZLIB_NO_FLUSH);
$compressed .= deflate_add($deflateContext, ", and even more data!", ZLIB_FINISH);

// Performs GZIP decompression:
$inflateContext = inflate_init(ZLIB_ENCODING_GZIP);
$uncompressed = inflate_add($inflateContext, $compressed, ZLIB_NO_FLUSH);
$uncompressed .= inflate_add($inflateContext, NULL, ZLIB_FINISH);
echo $uncompressed;
# --> Data to compress, more data, and even more data!


Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2016-02-03 18:39 UTC] cmb@php.net
-Type: Bug +Type: Documentation Problem
 [2016-08-01 13:50 UTC] cmb@php.net
-Assigned To: +Assigned To: cmb
 [2016-08-01 15:42 UTC] cmb@php.net
Automatic comment from SVN on behalf of cmb
Revision: http://svn.php.net/viewvc/?view=revision&amp;revision=339759
Log: Fix #71505: Missing documentation about deflate_init() etc.
 [2016-08-01 15:43 UTC] cmb@php.net
-Status: Assigned +Status: Closed
 [2016-08-01 15:43 UTC] cmb@php.net
The fix for this bug has been committed. Since the websites are not directly
updated from the repository, the fix might need some time to spread
across the globe to all mirror sites, including PHP.net itself.

Thank you for the *awesome* report, and for helping us make PHP.net better.
 [2016-08-01 15:45 UTC] cmb@php.net
-Status: Closed +Status: Re-Opened
 [2016-08-01 15:45 UTC] cmb@php.net
Oops, I forgot the examples.
 [2016-08-01 15:53 UTC] cmb@php.net
Automatic comment from SVN on behalf of cmb
Revision: http://svn.php.net/viewvc/?view=revision&amp;revision=339760
Log: Fix #71505: Missing documentation about deflate_init() etc.

Add the example.
 [2016-08-01 15:54 UTC] cmb@php.net
-Status: Re-Opened +Status: Closed
 [2020-02-07 06:07 UTC] phpdocbot@php.net
Automatic comment on behalf of cmb
Revision: http://git.php.net/?p=doc/en.git;a=commit;h=e47d027b6e9bd6b39171d16b7b15176e9d8d8831
Log: Fix #71505: Missing documentation about deflate_init() etc.
 [2020-02-07 06:07 UTC] phpdocbot@php.net
Automatic comment on behalf of cmb
Revision: http://git.php.net/?p=doc/en.git;a=commit;h=5f177879f0e84765c01d2b76e05aa01454a67fa4
Log: Fix #71505: Missing documentation about deflate_init() etc.
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Sat Apr 20 09:01:28 2024 UTC