Búferes de salida a nivel de usuario

Iniciar un búfer de salida

Los búferes de salida a nivel de usuario pueden iniciarse utilizando la función ob_start() o definiendo los parámetros output_buffering y output_handler de php.ini. Tanto uno como otro pueden crear búferes de salida, ob_start() es más flexible ya que acepta funciones definidas por el usuario como gestores de salida y las operaciones permitidas en el búfer (flush, clean, remove) pueden definirse también. Los búferes de salida iniciados con ob_start() estarán activos a partir de la línea donde se llamó a la función, mientras que los iniciados con output_buffering bufferizarán la salida desde la primera línea del script.

PHP también incluye un gestor de salida interno "URL-Rewriter" que inicia su propio búfer de salida y solo permite dos instancias del mismo funcionando al mismo tiempo (una para la reescritura de URL a nivel de usuario y otra para el soporte transparente de identificadores de sesión). Estos búferes pueden iniciarse llamando a la función output_add_rewrite_var() y/o activando el parámetro session.use_trans_sid de php.ini.

La extensión zlib tiene su propio búfer de salida que puede activarse utilizando el parámetro zlib.output_compression de php.ini.

Nota: Mientras que "URL-Rewriter" es especial en cuanto a que solo permite dos instancias del mismo funcionando al mismo tiempo, todos los búferes de salida a nivel de usuario utilizan los mismos búferes subyacentes usados por ob_start() con su funcionalidad implementada por una función de gestión de salida personalizada. Como tal, toda su funcionalidad puede emularse con código de usuario.

Lavar, acceder y limpiar el contenido del búfer

Lavar envía y elimina el contenido del búfer activo. Los búferes de salida se lavan cuando el tamaño de la salida excede el tamaño del búfer, el script finaliza o se llama a ob_flush(), ob_end_flush(), o ob_get_flush().

El contenido del búfer activo puede recuperarse llamando a ob_get_contents() o ob_get_flush().

Si solo se necesita la longitud del contenido del búfer, ob_get_length() o ob_get_status() devolverá la longitud del contenido en bytes.

El contenido del búfer activo puede limpiarse llamando a ob_clean(), ob_end_clean() o ob_get_clean().

Desactivar los búferes

Los búferes de salida pueden desactivarse llamando a ob_end_clean(), ob_end_flush(), ob_get_flush() o ob_get_clean().

Cada búfer de salida que no haya sido desactivado al final del script o cuando se llama a exit() será lavado y desactivado por el proceso de terminación de PHP. Los búferes se lavarán y desactivarán en orden inverso a su inicio. El último búfer iniciado será el primero, el primer búfer iniciado será el último en lavarse y desactivarse.

Excepciones lanzadas en los gestores de salida

Si una excepción no capturada es lanzada en un gestor de salida el programa termina y el gestor es invocado por el proceso de terminación después de lo cual se devuelve el mensaje de error "Excepción no capturada".

Si la excepción no capturada es lanzada en un gestor invocado por ob_flush(), ob_end_flush() o ob_get_flush(), el contenido del búfer se lava antes del mensaje de error.

Si una excepción no capturada es lanzada en un gestor de salida durante la terminación, el gestor termina y ni el contenido del búfer ni el mensaje de error son lavados.

Nota: Si un gestor lanza una excepción su flag PHP_OUTPUT_HANDLER_DISABLED está definido.

Errores generados en los gestores de salida

Si un error no fatal es generado en un gestor de salida el programa continúa su ejecución.

Si un error no fatal es generado en un gestor invocado por ob_flush(), ob_end_flush() o ob_get_flush(), el búfer vacía algunos datos dependiendo del valor de retorno del gestor. Si el gestor devuelve false el búfer y el mensaje de error son lavados. Si el gestor devuelve otra cosa, el valor de retorno del gestor es lavado pero no el mensaje de error.

Nota: Si un gestor devuelve false su flag PHP_OUTPUT_HANDLER_DISABLED está definido.

Si un error fatal es generado en un gestor de salida el programa termina y el gestor es invocado por el proceso de terminación después de lo cual el mensaje de error es lavado.

Si el error fatal es generado en un gestor invocado por ob_flush(), ob_end_flush() o ob_get_flush(), el contenido del búfer es lavado antes del mensaje de error.

Si un error fatal es generado en un gestor de salida durante la terminación el programa termina sin lavar el contenido del búfer o el mensaje de error.

Salida en los gestores de salida

En circunstancias específicas, la salida producida en el gestor es lavada con el contenido del búfer. Esta salida no se añade al búfer y no forma parte de la cadena devuelta por ob_get_flush().

Durante las operaciones de lavado de búfer (llamada a ob_flush(), ob_end_flush(), ob_get_flush() y durante la terminación) si el valor de retorno de un gestor es false el contenido del búfer es lavado seguido de la salida. Si el gestor no es invocado durante la terminación el gestor lanzando una excepción o la llamada a exit() resulta en el mismo comportamiento.

Nota: Si un gestor devuelve false su flag PHP_OUTPUT_HANDLER_DISABLED está definido.

Flags de estado de los gestores de salida

Los flags de estado de los gestores de la máscara de bits flags del búfer están definidos en cada invocación del gestor de salida y forman parte de la máscara de bits flags devuelta por ob_get_status(). Si el gestor se ejecuta con éxito y no devuelve false, PHP_OUTPUT_HANDLER_STARTED y PHP_OUTPUT_HANDLER_PROCESSED están definidos. Si el gestor devuelve false o lanza una excepción durante la ejecución, PHP_OUTPUT_HANDLER_STARTED y PHP_OUTPUT_HANDLER_DISABLED están definidos.

Nota: Si PHP_OUTPUT_HANDLER_DISABLED de un gestor está definido, el gestor no será invocado al llamar a ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush() ob_get_clean(), ob_get_flush(), ob_clean(), ob_flush() o durante el proceso de terminación de PHP. Antes de PHP 8.4.0, este flag no tenía ningún efecto al llamar a las funciones ob_clean() o ob_flush().