Skip to content

[Sync-En] filters: document the role of the zlib window parameter #1316

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
julionc merged 1 commit into from
Sep 18, 2026
+168 −51
Merged

[Sync-En] filters: document the role of the zlib window parameter #1316

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
219 changes: 168 additions & 51 deletions appendices/filters.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 3f1dbc451b313fb1ec8058f24c1beccf55fce316 Maintainer: PhilDaiguille Status: ready -->
<!-- EN-Revision: 82b5e0afeb38142e91fbba05f06b46c3129420ba Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no Maintainer: Marqitos -->
<appendix xml:id="filters" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Lista de filtros estándar</title>
Expand Down Expand Up @@ -54,8 +54,8 @@
<?php
$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'string.rot13');
fwrite($fp, "Ceci est un test.\n");
/* muestra : Prpv rfg ha grfg. */
fwrite($fp, "Esto es una prueba.\n");
/* Muestra: Rfgb rf han cehron. */
?>
]]>
</programlisting>
Expand All @@ -75,8 +75,8 @@ fwrite($fp, "Ceci est un test.\n");
<?php
$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'string.toupper');
fwrite($fp, "Ceci est un test.\n");
/* muestra : CECI EST UN TEST. */
fwrite($fp, "Esto es una prueba.\n");
/* Muestra: ESTO ES UNA PRUEBA. */
?>
]]>
</programlisting>
Expand All @@ -96,8 +96,8 @@ fwrite($fp, "Ceci est un test.\n");
<?php
$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'string.tolower');
fwrite($fp, "Ceci est un test.\n");
/* muestra : ceci est un test. */
fwrite($fp, "Esto es una prueba.\n");
/* Muestra: esto es una prueba. */
?>
]]>
</programlisting>
Expand All @@ -121,16 +121,16 @@ fwrite($fp, "Ceci est un test.\n");
<![CDATA[
<?php
$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'string.strip_tags', STREAM_FILTER_WRITE, "<strong><em><span>");
fwrite($fp, "<strong>Ce texte en gras</strong> finit par être agrandi <h1>en un titre 1</h1>\n");
stream_filter_append($fp, 'string.strip_tags', STREAM_FILTER_WRITE, "<b><i><u>");
fwrite($fp, "<b>texto en negrita</b> ampliado a un <h1>encabezado de nivel 1</h1>\n");
fclose($fp);
/* muestra : Ce texte en gras finit par être agrandi en un titre 1 */
/* Muestra: texto en negrita ampliado a un encabezado de nivel 1 */

$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'string.strip_tags', STREAM_FILTER_WRITE, array('strong','em','span'));
fwrite($fp, "<strong>Ce texte en gras</strong> finit par être agrandi <h1>en un titre 1</h1>\n");
stream_filter_append($fp, 'string.strip_tags', STREAM_FILTER_WRITE, array('b','i','u'));
fwrite($fp, "<b>texto en negrita</b> ampliado a un <h1>encabezado de nivel 1</h1>\n");
fclose($fp);
/* muestra : Ce texte en gras finit par être agrandi en un titre 1 */
/* Muestra: texto en negrita ampliado a un encabezado de nivel 1 */
?>
]]>
</programlisting>
Expand Down Expand Up @@ -174,22 +174,22 @@ $fp = fopen('php://output', 'w');
stream_filter_append($fp, 'convert.base64-encode');
fwrite($fp, "This is a test.\n");
fclose($fp);
/* muestra : VGhpcyBpcyBhIHRlc3QuCg== */
/* Muestra: VGhpcyBpcyBhIHRlc3QuCg== */

$param = array('line-length' => 8, 'line-break-chars' => "\r\n");
$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'convert.base64-encode', STREAM_FILTER_WRITE, $param);
fwrite($fp, "This is a test.\n");
fclose($fp);
/* muestra : VGhpcyBp
: cyBhIHRl
: c3QuCg== */
/* Muestra: VGhpcyBp
: cyBhIHRl
: c3QuCg== */

$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'convert.base64-decode');
fwrite($fp, "VGhpcyBpcyBhIHRlc3QuCg==");
fclose($fp);
/* muestra : This is a test. */
/* Muestra: This is a test. */
?>
]]>
</programlisting>
Expand Down Expand Up @@ -223,7 +223,7 @@ fclose($fp);
$fp = fopen('php://output', 'w');
stream_filter_append($fp, 'convert.quoted-printable-encode');
fwrite($fp, "This is a test.\n");
/* muestra : =This is a test.=0A */
/* Muestra: =This is a test.=0A */
?>
]]>
</programlisting>
Expand Down Expand Up @@ -282,7 +282,7 @@ fclose($fp);

<section xml:id="filters.compression.zlib">
<title>zlib.deflate y zlib.inflate</title>
<simpara>
<para>
<literal>zlib.deflate</literal> (compresión) y
<literal>zlib.inflate</literal> (descompresión) son las implementaciones
de los métodos de compresión presentados en la
Expand All @@ -296,18 +296,135 @@ fclose($fp);
0, que representa la ausencia de compresión, y -1, que representa el nivel por defecto de zlib:
actualmente, 6.

<parameter>window</parameter> es el tamaño del buffer de memoria, en base 2.
Los valores superiores, hasta 15, es decir, 32768 bytes, dan mejores
compresiones, y los valores inferiores, hasta 9, es decir, 512 bytes,
ocupan menos espacio en memoria. Por defecto,
<parameter>window</parameter> es el logaritmo en base 2 del tamaño de la
ventana de compresión. Los valores superiores, hasta 15, es decir, 32768 bytes,
dan una mejor compresión a costa de más memoria, y los valores inferiores,
hasta 9, es decir, 512 bytes, dan una compresión menor ocupando menos
espacio en memoria. Por defecto,
<parameter>window</parameter> vale actualmente <literal>15</literal>.

<parameter>memory</parameter> es una indicación del nivel de memoria
necesario.
El filtro <literal>zlib.deflate</literal> implementa los métodos de
compresión <literal>DEFLATE</literal>, <literal>ZLIB</literal> y
<literal>GZIP</literal> según el valor del parámetro
<parameter>window</parameter>.

Los 4 bits inferiores del parámetro window fijan el tamaño del
«búfer de historial» interno utilizado, siendo el logaritmo en base 2 de su
tamaño, en un rango de 8 a 15. El significado de los demás bits del
parámetro window puede fijarse como se describe a continuación.

<itemizedlist>
<listitem>
<simpara>
<literal>DEFLATE</literal> (<link xlink:href="&url.rfc;1951">RFC 1951</link>)
es un algoritmo de compresión sin tratar, sin encabezado ni suma de
verificación. Se aplica cuando el parámetro window se fija en el rango
de -9 a -15. Este algoritmo de compresión es la base de todos los
formatos generados por el filtro <literal>zlib.deflate</literal>.
Las funciones correspondientes que operan directamente sobre strings son
<function>gzdeflate</function> y <function>gzinflate</function>.
</simpara>
</listitem>

<listitem>
<simpara>
<literal>ZLIB</literal> (<link xlink:href="&url.rfc;1950">RFC 1950</link>)
aplica el algoritmo <literal>DEFLATE</literal> y añade un encabezado de
2 bytes y un tráiler de 4 bytes que contiene la suma de verificación
Adler32 de los datos sin comprimir, en orden de bytes big-endian:
<literal><![CDATA[ZLIB = ZLIBHEADER(2B) DEFLATE ADLER32(4B)]]></literal>

El encabezado de 2 bytes, leído como un número de 16 bits sin signo en
orden big-endian, debe ser múltiplo de 31.
Este formato se genera cuando el parámetro window se fija en el rango
de 8 a 15.
Las funciones correspondientes que operan directamente sobre strings son
<function>gzcompress</function> y <function>gzuncompress</function>.
</simpara>
</listitem>

<listitem>
<simpara>
<literal>GZIP</literal> (<link xlink:href="&url.rfc;1952">RFC 1952</link>)
aplica el algoritmo <literal>DEFLATE</literal> añadiendo un encabezado y
un tráiler con la suma de verificación <literal>CRC32</literal> de los
datos sin comprimir y su longitud, ambos en orden de bytes little-endian:
<literal><![CDATA[GZIP = GZIPHEADER(10B) DEFLATE CRC32(4B) LENGTH(4B)]]></literal>

Es el formato de los ficheros <literal>.gz</literal>, en el que
<literal>GZIPHEADER</literal> contiene, en este orden, la firma
<literal>GZIP</literal> (<literal>\x1f\x8B</literal>), el método de
compresión (<literal>\x08</literal>), un byte de flags a cero, una fecha
de modificación a cero en 4 bytes, un byte de flags adicionales que
depende del nivel de compresión, y el sistema operativo fijado al sistema
actual (<literal>\x00</literal> = sistema de ficheros FAT,
<literal>\x03</literal> = Unix, etc.).
Este formato se genera cuando el parámetro window se fija en el rango
de 9+16=25 a 15+16=31. Tenga en cuenta que existe un límite de 4GB para
la longitud máxima de los datos sin comprimir; más allá de este límite,
solo se almacena el módulo 2^32 de la longitud real en la parte
<literal>LENGTH</literal>.
Las funciones correspondientes que operan directamente sobre strings son
<function>gzencode</function> y <function>gzdecode</function>; la
función <function>gzopen</function> permite leer y escribir ficheros
<literal>.gz</literal>.
</simpara>
</listitem>
</itemizedlist>

Con el filtro <literal>zlib.inflate</literal>, solo se admite el parámetro
<parameter>window</parameter>; cualquier otro parámetro
(<parameter>memory</parameter>, <parameter>level</parameter>) se ignora.
Sea $W el logaritmo en base 2 del tamaño del búfer de historial, de modo
que el descompresor asigna 2^$W bytes. Para el formato ZLIB, este valor
debe ser mayor o igual al registrado en el encabezado, lo cual se
comprueba durante la descompresión; para los demás formatos, basta con
que sea lo suficientemente grande para las distancias de coincidencia
realmente presentes en los datos.
El rango es 9 ≤ $W ≤ 15. Si se desconoce, $W=15 es la opción más segura.

<itemizedlist>
<listitem>
<simpara>
<literal>DEFLATE</literal> (<link xlink:href="&url.rfc;1951">RFC 1951</link>):
utilice window=-$W, siendo $W un valor no inferior al utilizado para
la compresión. Si se desconoce, fije window=-15.
</simpara>
</listitem>

<listitem>
<simpara>
<literal>ZLIB</literal> (<link xlink:href="&url.rfc;1950">RFC 1950</link>):
utilice window=$W. El valor de $W puede obtenerse del propio encabezado
ZLIB; en caso contrario, fije window=15.
</simpara>
</listitem>

<listitem>
<simpara>
<literal>GZIP</literal> (<link xlink:href="&url.rfc;1952">RFC 1952</link>):
utilice window=$W+16. Un encabezado GZIP no contiene el tamaño de la
ventana, por lo que debe fijarse window=31, salvo que se conozca el valor
utilizado para la compresión.
</simpara>
</listitem>

<listitem>
<simpara>
<literal>ZLIB o GZIP</literal>:
utilice window=$W+32 para la detección automática del encabezado, de
modo que ambos formatos puedan reconocerse y descomprimirse;
window=15+32=47 es la opción más segura.
</simpara>
</listitem>
</itemizedlist>

<parameter>memory</parameter> es una escala que indica cuánta memoria de
trabajo debe asignarse.
Los valores válidos van de 1, para la asignación mínima, a 9, para una
asignación máxima. La asignación de memoria afecta la velocidad de ejecución,
y no el coste global.
</simpara>
asignación máxima. La asignación de memoria afecta únicamente a la velocidad
de ejecución y no influye en el tamaño de los datos generados.
</para>

<note>
<simpara>
Expand All @@ -332,23 +449,23 @@ fclose($fp);
$params = array('level' => 6, 'window' => 15, 'memory' => 9);

$original_text = "This is a test.\nThis is only a test.\nThis is not an important string.\n";
echo "El texto original es largo de " . strlen($original_text) . " bytes.\n";
echo "El texto original tiene " . strlen($original_text) . " caracteres.\n";

$fp = fopen('test.deflated', 'w');
stream_filter_append($fp, 'zlib.deflate', STREAM_FILTER_WRITE, $params);
fwrite($fp, $original_text);
fclose($fp);

echo "El fichero comprimido hace " . filesize('test.deflated') . " bytes de largo.\n";
echo "El texto original era :\n";
echo "El fichero comprimido tiene " . filesize('test.deflated') . " bytes.\n";
echo "El texto original era:\n";
/* Utiliza readfile y zlib.inflate para descomprimir al vuelo */
readfile('php://filter/zlib.inflate/resource=test.deflated');

/* Muestra :
/* Muestra:

El texto original es largo de 70 bytes
El fichero comprimido hace 56 bytes de largo.
El texto original era :
El texto original tiene 70 caracteres.
El fichero comprimido tiene 56 bytes.
El texto original era:
This is a test.
This is only a test.
This is not an important string.
Expand All @@ -367,20 +484,20 @@ This is not an important string.
<![CDATA[
<?php
$original_text = "This is a test.\nThis is only a test.\nThis is not an important string.\n";
echo "El texto original es largo de " . strlen($original_text) . " bytes.\n";
echo "El texto original tiene " . strlen($original_text) . " caracteres.\n";

$fp = fopen('test.deflated', 'w');
/* Aquí, "6" indica el nivel de compresión de 6 */
stream_filter_append($fp, 'zlib.deflate', STREAM_FILTER_WRITE, 6);
fwrite($fp, $original_text);
fclose($fp);

echo "El fichero comprimido hace " . filesize('test.deflated') . " bytes de largo.\n";
echo "El fichero comprimido tiene " . filesize('test.deflated') . " bytes.\n";

/* Muestra :
/* Muestra:

El texto original es largo de 70 bytes
El fichero comprimido hace 56 bytes de largo.
El texto original tiene 70 caracteres.
El fichero comprimido tiene 56 bytes.

*/
?>
Expand All @@ -404,7 +521,7 @@ El fichero comprimido hace 56 bytes de largo.

<parameter>work</parameter> es también un &integer; cuyo valor va de
0 a 250, e indica el nivel de esfuerzo proporcionado con un método de
compresión antes de pasar a otro método, más lento. Modificar este
compresión antes de pasar a otro método, más lento pero más fiable. Modificar este
parámetro solo tiene efecto en la velocidad de compresión. La ganancia de espacio
o la memoria utilizada permanecen iguales. Un nivel de 0 indica que la
biblioteca debe utilizar su configuración por defecto.
Expand Down Expand Up @@ -432,19 +549,19 @@ El fichero comprimido hace 56 bytes de largo.
<?php
$param = array('blocks' => 9, 'work' => 0);

echo "El fichero original hace " . strlen(LICENSE) . " bytes de largo.\n";
echo "El fichero original tiene " . filesize('LICENSE') . " bytes.\n";

$fp = fopen('LICENSE.compressed', 'w');
stream_filter_append($fp, 'bzip2.compress', STREAM_FILTER_WRITE, $param);
fwrite($fp, file_get_contents('LICENSE'));
fclose($fp);

echo "El fichero comprimido hace " . filesize('LICENSE.compressed') . " bytes de largo.\n";
echo "El fichero comprimido tiene " . filesize('LICENSE.compressed') . " bytes.\n";

/* Muestra :
/* Muestra:

El fichero original hace 3288 bytes de largo.
El fichero comprimido hace 1488 bytes de largo.
El fichero original tiene 3288 bytes.
El fichero comprimido tiene 1488 bytes.

*/
?>
Expand Down Expand Up @@ -484,8 +601,8 @@ El fichero comprimido hace 1488 bytes de largo.
<thead>
<row>
<entry>Parámetro</entry>
<entry>Obligatorio ?</entry>
<entry>Por omisión</entry>
<entry>¿Obligatorio?</entry>
<entry>Por defecto</entry>
<entry>Valores posibles</entry>
</row>
</thead>
Expand All @@ -500,13 +617,13 @@ El fichero comprimido hace 1488 bytes de largo.
<entry>algorithms_dir</entry>
<entry>Opcional</entry>
<entry>ini_get('mcrypt.algorithms_dir')</entry>
<entry>Ruta hacia los algoritmos de módulos</entry>
<entry>Ubicación de los módulos de algoritmos</entry>
</row>
<row>
<entry>modes_dir</entry>
<entry>Opcional</entry>
<entry>ini_get('mcrypt.modes_dir')</entry>
<entry>Ruta hacia los modos de módulos</entry>
<entry>Ubicación de los módulos de modos</entry>
</row>
<row>
<entry>iv</entry>
Expand Down