Doc #71505 [ReO->Csd]: Missing documentation about deflate_init() etc.

Edit report at https://bugs.php.net/bug.php?id=71505&edit=1 ID: 71505 Updated by: cmb@php.net Reported by: salsi at icosaedro dot it Summary: Missing documentation about deflate_init() etc. -Status: Re-Opened +Status: Closed Type: Documentation Problem Package: Documentation problem PHP Version: Irrelevant Assigned To: cmb Block user comment: N Private report: N Previous Comments: ------------------------------------------------------------------------ [2016-08-01 15:53:56] 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:45:47] cmb@php.net Oops, I forgot the examples. ------------------------------------------------------------------------ [2016-08-01 15:43:01] 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:42:17] 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-02-03 10:03:35] 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! ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=71505&edit=1