ToWebs

Descripción

void header ( string cadena [, bool reemplazar [, int cod_respuesta_http]] )

La función header() es usada para enviar cabeceras HTTP puras. Consulte la especificación HTTP/1.1 para más información sobre las cabeceras HTTP.

El parámetro opcional reemplazar indica si la cabecera debe reemplazar una cabecera previa semejante, o si debe agregar una segunda cabecera del mismo tipo. Por defecto esta función procede a reemplazar, pero si pasa FALSE como el segundo argumento, puede obligar a que se envíen múltiples cabeceras del mismo tipo. Por ejemplo:


<?php
header('WWW-Authenticate: Negotiate');
header('WWW-Authenticate: NTLM', false);
?>

El segundo parámetro opcional, cod_respuesta_http, obliga a que el código de respuesta HTTP sea el valor especificado. (Este parámetro se encuentra disponible a partir de PHP 4.3.0.)

Existen dos llamadas de cabecera que son casos especiales. El primero es una cabecera que comience con la cadena "HTTP/" (no es importante la diferencia entre mayúsculas y minúsculas), la cual será usada para elegir el código de status HTTP a enviar. Por ejemplo, si ha configurado a Apache para que use un script PHP a la hora de gestionar peticiones por archivos inexistentes (usando la directiva ErrorDocument), puede que quiera asegurarse de que su script genere el código de status apropiado.


<?php
header("HTTP/1.0 404 Not Found");
?>

Nota: La línea de cabecera con el status HTTP será siempre la primera en ser enviada al cliente, independientemente de que la llamada a header() correspondiente sea la primera o no. El status puede ser sobrescrito llamando header() con una nueva línea de status en cualquier momento, a menos que las cabeceras HTTP ya hayan sido enviadas.

El segundo caso especial es la cabecera "Location:". No solo envía esta cabecera de vuelta al navegador, sino que también devuelve un código de status REDIRECT (302) al navegador a menos que algún código de status 3xx haya sido enviado ya.


<?php
header("Location: http://www.example.com/"); /* Redirigir al navegador */

/* Asegurarse de que no se ejecute el codigo adicional cuando se redireccione. */
exit;
?>

Nota: HTTP/1.1 requiere una URI absoluta como argumento a Location: incluyendo el esquema, el nombre del host y una ruta absoluta, aunque algunos clientes aceptan URIs relativas. Usualmente puede usar $_SERVER['HTTP_HOST'], $_SERVER['PHP_SELF'] y dirname() para construir una URI absoluta a partir de una relativa:
<?php header("Location: http://" . $_SERVER['HTTP_HOST'] . dirname($_SERVER['PHP_SELF']) . "/" . $url_relativa); ?>

Con frecuencia, los scripts PHP generan contenido dinámico que no debe ser almacenado en caché por el navegador del cliente o cualquier caché de proxy entre el servidor y el navegador del cliente. Muchos proxys y clientes pueden ser obligados a deshabilitar el uso de cachés con:


<?php
// Fecha en el pasado
header("Expires: Mon, 26 Jul 1997 05:00:00 GMT");

// siempre modificado
header("Last-Modified: " . gmdate("D, d M Y H:i:s") . " GMT");
 
// HTTP/1.1
header("Cache-Control: no-store, no-cache, must-revalidate");
header("Cache-Control: post-check=0, pre-check=0", false);

// HTTP/1.0
header("Pragma: no-cache");
?>

Nota: Puede que encuentre que sus páginas no son puestas en caché aun cuando no use todas las cabeceras enteriores. Existe un número de opciones que puede que se encuentren a disposición de los usuarios en sus navegadores para modificar sus comportamientos de caché predeterminados. Al enviar las anteriores cabeceras, usted debería sobrescribir cualquier parámetro de configuración que de otra forma podría estar causando que la salida de su script sea puesta en caché.
Adicionalmente, session_cache_limiter() y el parámetro de configuración session.cache_limiter pueden ser usados para generar automáticamente las cabeceras de uso de caché apropiadas cuando se están usando sesiones.

Recuerde que la función header() debe ser llamada antes de que cualquier salida sea enviada, ya sea mediante etiquetas HTML normales, líneas en blanco de un archivo, o desde PHP. Es un error bastante común interpretar código extra con include(), require(), o alguna otra función de acceso de archivos, y terminar con espacios o líneas en blanco que son impresas antes de un llamado a header(). El mismo problema existe cuando se usa un archivo PHP/HTML único.


<html>
<?php
/* Esto produce un error. Note la salida anterior, que se realiza
 * antes de llamar a header() */
header('Location: http://www.example.com/');
?>

Nota: A partir de PHP 4, puede usar búferes de salida para evitar este problema, con el efecto lateral de que toda su salida al navegador es colocada en un búfer en el servidor hasta que usted la envíe. Puede lograr esto usando ob_start() y ob_end_flush() en su script, o al definir la directiva de configuración output_buffering en su php.ini u otros archivos de configuración.

Si desea que el usuario reciba un cuadro de diálogo para almacenar los datos que usted envía, como en el caso de un archivo PDF generado al vuelo, puede usar la cabecera Content-Disposition para indicar un nombre de archivo recomendado y obligar a que el navegador despliegue un diálogo de guardado.


<?php
// Enviaremos un PDF
header('Content-type: application/pdf');

// Se va a llamar descarga.pdf
header('Content-Disposition: attachment; filename="descarga.pdf"');

// La fuente del PDF se encuentra en original.pdf
readfile('original.pdf');
?>

Nota: Existe un problema en Microsoft Internet Explorer 4.01 que impide que esto funcione. No existe forma de evitar este inconveniente. Hay también un fallo en Microsoft Internet Explorer 5.5 que interfiere con esto, el cual puede ser resuelto al actualizarse a Service Pack 2 o superior.

Nota: Si se encuentra habilitado el modo seguro, el uid del script es agregado a la sección realm de la cabecera WWW-Authenticate si define ésta cabecera (usada para Autenticación HTTP).

Vea también headers_sent(), setcookie(), y la sección sobre autenticación HTTP.