# ob_start

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_start — Activa el almacenamiento en búfer de la salida

### Descripción

ob_start(callable `$output_callback` = `null`, int `$chunk_size` = 0, int `$flags` = `PHP_OUTPUT_HANDLER_STDFLAGS`): bool

Esta función activará el almacenamiento en búfer de la salida. Mientras dicho almacenamiento esté activo, no se enviará ninguna salida desde el script (aparte de cabeceras); en su lugar la salida se almacenará en un búfer interno.

El contenido de este búfer interno se puede copiar a una variable de tipo string usando ob_get_contents(). Para producir la salida de lo almacenado en el búfer interno se ha de usar ob_end_flush(). De forma alternativa, ob_end_clean() desechará de manera silenciosa el contenido del búfer.

Advertencia

Algunos servidores web (p.ej. Apache) cambian en directorio de trabajo de un script cuando se invoca a la función de llamada de retorno. Se puede cambiar de nuevo mediante, por ejemplo, `chdir(dirname($_SERVER['SCRIPT_FILENAME']))` en la función de llamada de retorno.

Los búferes de salida son apilables, es decir, que se podría llamar a ob_start() mientras otro ob_start() esté activo. Se ha de asegurar llamar a ob_end_flush() las veces apropiadas. Si están activas múltiples funciones de llamada de retorno de salida, la salida se filtrará secuencialmente por cada una de ellas en orden de anidamiento.

### Parámetros

`output_callback`

  Se puede especificar una función `output_callback` opcional. Esta función toma un string como parámetro y debería devolver otro string. La función se llamará cuando el búfer de salida sea volcado (enviado), limpiado (con ob_flush(), ob_clean() o alguna función similar) o cuando el búfer de salida sea volcado al navegador al final de la petición. Cuando se llame a `output_callback`, ésta recibirá el contenido del búfer de salida como su propio parámetro, y se espera que devuelva un nuevo búfer de salida como resultado, que será enviado al navegador. Si `output_callback` no es una función llamable, esta función devolverá `false`. Esta es la firma de la llamada de retorno:

  handler(string `$buffer`, int `$phase` = ?): string
  `buffer`
    Contenido del búfer de salida.
  `phase`
    Máscara de bits de constantes `PHP_OUTPUT_HANDLER_*`.

  Si `output_callback` devuelve `false`, se enviará la entrada original al navegador.

  El parámetro `output_callback` se puede omitir pasando un valor `null`.

  ob_end_clean(), ob_end_flush(), ob_clean(), ob_flush() y ob_start() no se pueden llamar desde una función de llamada de retorno. Si se hace, el comportamiento no estará definido. Si se quiere borrar el contenido de un búfer, se ha de devolver "" (un string nulo) desde la función de llamada de retorno. Tampoco se pueden llamar a funciones usando las funciones de búfer de salida como `print_r($expresión, true)` o `highlight_file($nombre_fichero, true)` desde una función de llamada de retorno.

  > Nota:

  > En PHP 4.0.4, ob_gzhandler() se introdujo para facilitar el envío de datos codificados con gz a los navegadores web que admitan páginas web comprimidas. ob_gzhandler() determima el tipo de codificación de contenido que aceptará el navegador y devolverá su salida en consecuencia.

`chunk_size`

  Si se proporciona el parámetro opcional `chunk_size`, el búffer será volcado después de cualquier llamada de salida que cause que la longitud del búfer sea igual o exceda a `chunk_size`. El valor predeterminado `0` significa que la función de salida será llamada únicamente cuando el búfer de salida se cierre.

  Antes de PHP 5.4.0, el valor `1` era un caso especial que establecía el tamaño de segmento a 4096 bytes.

`flags`

  El parámetro `flags` es una máscara de bits que controla las operaciones que se pueden realizar sobre el búfer de salida. Lo predeterminado es permitir que los búferes de salida sean limpiados, volcados y borrados, lo que se puede hacer explícitamente mediante `PHP_OUTPUT_HANDLER_CLEANABLE` | `PHP_OUTPUT_HANDLER_FLUSHABLE` | `PHP_OUTPUT_HANDLER_REMOVABLE`, o `PHP_OUTPUT_HANDLER_STDFLAGS` como clave.

  Cada bandera (flag) controla el acceso a un conjunto de funciones, como está descrito a continuación:

  Constante | Funciones
  --- | ---
  `PHP_OUTPUT_HANDLER_CLEANABLE` | ob_clean(), ob_end_clean(), y ob_get_clean().
  `PHP_OUTPUT_HANDLER_FLUSHABLE` | ob_end_flush(), ob_flush(), y ob_get_flush().
  `PHP_OUTPUT_HANDLER_REMOVABLE` | ob_end_clean(), ob_end_flush(), y ob_get_flush().

### Valores devueltos

Devuelve `true` en caso de éxito o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
7.0.0 | En caso de utilizar ob_start() dentro de una retrollamada del búfer de salida, esta función ya no emitirá un `E_ERROR`, si no un `E_RECOVERABLE_ERROR`, permitiendo a los manejadores de errores propios capturar tales errores.
5.4.0 | El tercer parámetro de ob_start() se cambió de un parámetro boolean llamado `erase` (el cual, si se establecía a `false`, prevenía al búfer de salida de ser eliminado hasta el final de la ejecución del script) a un parámetro integer llamado `flags`. Desafortunadamente, esto resulta en una rotura de compatibilidad de la API para código escrito antes de PHP 5.4.0 que use el tercer parámetro. Véase el ejemplo de banderas para saber cómo manejar esto con código que necesite ser compatible con ambas.
5.4.0 | Un tamaño de segmento de `1` ahora resulta en segmentos de 1 byte que se van a enviar al búfer de salida.
4.3.2 | Se modficó esta función que devuelva `false` en caso de que la función `output_callback` pasada no pueda ejecutarse.

### Ejemplos

Ejemplo #1 Ejemplo de una función de llamada de retorno definida por el usuario

`<?php
function callback($búfer)
{
// reemplazar todas las manzanas por naranjas
return (str_replace("manzanas", "naranjas", $búfer));
}
ob_start("callback");
?>
<html>
<body>
<p>Es como comparar manzanas con naranjas.</p>
</body>
</html>
<?php
ob_end_flush();
?>`

El resultado del ejemplo sería:

    <html>
    <body>
    <p>Es como comparar naranjas con naranjas.</p>
    </body>
    </html>

Ejemplo #2 Crear un búfer de salida imborrable de forma compatible con PHP 5.3 y 5.4

`<?php
if (version_compare(PHP_VERSION, '5.4.0', '>=')) {
ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^
PHP_OUTPUT_HANDLER_REMOVABLE);
} else {
ob_start(null, 0, false);
}
?>`

### Ver también

- ob_get_contents() - Devolver el contenido del búfer de salida
- ob_end_clean() - Limpiar (eliminar) el búfer de salida y deshabilitar el almacenamiento en el mismo
- ob_end_flush() - Volcar (enviar) el búfer de salida y deshabilitar el almacenamiento en el mismo
- ob_implicit_flush() - Habilitar/deshabilitar el volcado implícito
- ob_gzhandler() - ob_start callback function to gzip output buffer
- ob_iconv_handler() - Convierte la codificación de caracteres al manejador del buffer de salida
- mb_output_handler() - Función de llamada de retorno que convierte la codificación de caracteres en búfer de salida
- ob_tidyhandler() - Función callback de ob_start para reparar el buffer