# Búferes de salida a nivel de usuario

## Tabla de contenidos

- ¿Qué salida está bufferizada?
- Anidamiento de búferes de salida
- Tamaño del búfer
- Operaciones permitidas en los búferes
- Gestores de salida
- Trabajar con los gestores de salida
- Flags pasados a los gestores de salida
- Valores de retorno de los gestores de salida

La bufferización de salida a nivel de usuario de PHP puede iniciarse, manipularse y finalizar desde el código PHP. Cada uno de estos búferes incluye un búfer de salida y una función de gestión de salida asociada.

## 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().

Precaución

Llamar a ob_end_flush() o ob_get_flush() desactivará el búfer activo.

Precaución

Lavar los búferes lavará el valor de retorno del gestor de salida que puede diferir del contenido del búfer. Por ejemplo, usar ob_gzhandler() comprimirá la salida y lavará la salida comprimida.

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.

Precaución

Llamar a ob_get_clean() o ob_get_flush() desactivará el búfer activo después de devolver su contenido.

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

Precaución

Llamar a ob_end_clean() o ob_get_clean() desactivará el búfer activo.

## 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().

Advertencia

Los búferes de salida iniciados sin el flag `PHP_OUTPUT_HANDLER_REMOVABLE` no pueden desactivarse y generarán un `E_NOTICE`.

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.

Precaución

Si no se desea el lavado del contenido del búfer, debe usarse un gestor de salida personalizado para evitar el lavado al cerrar.

## 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().

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open