[doc-en] master: Document the role of the window parameter (#1660)

Author: Grégoire Paris (greg0ire) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-09-09T08:25:58+02:00 Commit: https://github.com/php/doc-en/commit/82b5e0afeb38142e91fbba05f06b46c3129420ba Raw diff: https://github.com/php/doc-en/commit/82b5e0afeb38142e91fbba05f06b46c3129420ba.diff Document the role of the window parameter (#1660) Changed paths: M appendices/filters.xml Diff: diff --git a/appendices/filters.xml b/appendices/filters.xml index 1eb8fcc16fd6..5eb5a72f9ebb 100644 --- a/appendices/filters.xml +++ b/appendices/filters.xml @@ -285,7 +285,7 @@ fclose($fp); <section xml:id="filters.compression.zlib"> <title>zlib.deflate and zlib.inflate</title> - <simpara> + <para> <literal>zlib.deflate</literal> (compression) and <literal>zlib.inflate</literal> (decompression) are implementations of the compression methods described in <link xlink:href="&url.rfc;1951">RFC 1951</link>. @@ -302,10 +302,123 @@ fclose($fp); while lower values (down to 9 -- 512 bytes) yield worse compression in a smaller memory footprint. Default <parameter>window</parameter> size is currently <literal>15</literal>. + The <literal>zlib.deflate</literal> filter implements the compression + methods <literal>DEFLATE</literal>, <literal>ZLIB</literal> and + <literal>GZIP</literal> depending on the value of the + <parameter>window</parameter> parameter. + + The 4 lower bits of the window parameter set the size of the internal + “history buffer” used, being the base-2 logarithm of its size in a range + from 8 up to 15. The meaning of the others bits of the window parameter + can be set as described below. + + <itemizedlist> + <listitem> + <simpara> + <literal>DEFLATE</literal> (<link xlink:href="&url.rfc;1951">RFC 1951</link>) + is a raw compression algorithm without header, without checksum. It is + performed when the window parameter is set in the range from -9 up to + -15. This compression algorithm is the base for all the formats + generated by the <literal>zlib.deflate</literal> filter. + The corresponding functions that operate directly on strings are + <function>gzdeflate</function> and <function>gzinflate</function>. + </simpara> + </listitem> + + <listitem> + <simpara> + <literal>ZLIB</literal> (<link xlink:href="&url.rfc;1950">RFC 1950</link>) + applies the <literal>DEFLATE</literal> algorithm and adds a 2 bytes + header and 4 bytes trailer containing the Adler32 checksum of the + uncompressed data in big-endian byte order: + <literal><![CDATA[ZLIB = ZLIBHEADER(2B) DEFLATE ADLER32(4B)]]></literal> + + The 2 bytes header, read as 16 bit unsigned number in big-endian + order, must be multiple of 31. + This format is generated when the window parameter is set in the range + from 8 up to 15. + The corresponding functions that operate directly on strings are + <function>gzcompress</function> and <function>gzuncompress</function>. + </simpara> + </listitem> + + <listitem> + <simpara> + <literal>GZIP</literal> (<link xlink:href="&url.rfc;1952">RFC 1952</link>) + applies the <literal>DEFLATE</literal> algorithm adding an header and a + trailer with the <literal>CRC32</literal> checksum of the uncompressed + data and their length, both in little-endian byte ordering: + <literal><![CDATA[GZIP = GZIPHEADER(10B) DEFLATE CRC32(4B) LENGTH(4B)]]></literal> + + This is the format of the <literal>.gz</literal> files, with the + <literal>GZIPHEADER</literal> containing in the order the + <literal>GZIP</literal> signature (<literal>\x1f\x8B</literal>), the + compression method (<literal>\x08</literal>), a zero flag byte, a zero + modification time on 4 bytes, an extra-flags byte that depends on the + compression level, and the operating system set to the current system + (<literal>\x00</literal> = FAT filesystem, + <literal>\x03</literal> = Unix, etc.). + This format is generated when the window parameter is set in the range + from 9+16=25 up to 15+16=31. Note that there is a limit of 4GB to the + maximum length of the uncompressed data; beyond this limit, only the + modulo 2^32 of the actual length is stored in the <literal>LENGTH</literal> part. + The corresponding functions that operate directly on strings are + <function>gzencode</function> and <function>gzdecode</function>; the + <function>gzopen</function> function allows to read and write + <literal>.gz</literal> files. + </simpara> + </listitem> + </itemizedlist> + + With the <literal>zlib.inflate</literal> filter, only the + <parameter>window</parameter> parameter is allowed; any other parameter + (<parameter>memory</parameter>, <parameter>level</parameter>) is ignored. + Be $W the base-2 log of the history buffer size, so that 2^$W bytes are + allocated by the decompressor. For the ZLIB format this value must be + greater or equal to the one recorded in the header, which is checked at + decompression time; for the other formats it only has to be large enough + for the match distances actually present in the data. + The range is 9 ≤ $W ≤ 15. If unknown, $W=15 is the safer choice. + + <itemizedlist> + <listitem> + <simpara> + <literal>DEFLATE</literal> (<link xlink:href="&url.rfc;1951">RFC 1951</link>): + use window=-$W, with $W being a value not less than that used for + compression. If unknown, set window=-15. + </simpara> + </listitem> + + <listitem> + <simpara> + <literal>ZLIB</literal> (<link xlink:href="&url.rfc;1950">RFC 1950</link>): + use window=$W. The value of $W is available from the same ZLIB header, + otherwise set window=15. + </simpara> + </listitem> + + <listitem> + <simpara> + <literal>GZIP</literal> (<link xlink:href="&url.rfc;1952">RFC 1952</link>): + use window=$W+16. A GZIP header carries no window size, so set + window=31 unless the value used for compression is known. + </simpara> + </listitem> + + <listitem> + <simpara> + <literal>ZLIB or GZIP</literal>: + use window=$W+32 for automatic header detection, so that both the + formats can be recognized and decompressed; window=15+32=47 is the + safer choice. + </simpara> + </listitem> + </itemizedlist> + <parameter>memory</parameter> is a scale indicating how much work memory should be allocated. Valid values range from 1 (minimal allocation) to 9 (maximum allocation). This memory allocation affects speed only and does not impact the size of the generated payload. - </simpara> + </para> <note> <simpara>