(PHP 4, PHP 5)
header — Enviar encabezado sin formato HTTP
$string
[, bool $replace = true
[, int $http_response_code
]] )header() es usado para enviar encabezados HTTP sin formato. Ver la especificación » HTTP/1.1 specification para más información sobre encabezados HTTP.
Recuerde que header() debe ser llamado antes de mostrar nada por pantalla, etiquetas HTML, líneas en blanco desde un fichero o desde PHP. Es un error muy común leer código con funciones como include o require, u otro tipo de funciones de acceso de ficheros que incluyen espacios o líneas en blanco que se muestran antes de llamar a la función header(). Sucede el mismo problema cuando se utiliza un solo fichero PHP/HTML.
<html>
<?php
/* Esto producirá un error. Fíjate en el html
* que se muestra antes que la llamada a header() */
header('Location: http://www.example.com/');
?>
string
El encabezado en formato cadena.
Existen dos casos especiales en el uso de header. El primero el encabezado que empieza con la cadena "HTTP/" (las mayúsculas no son importantes), es utilizado para averiguar el código de status HTTP a enviar. Por ejemplo, si se tiene Apache configurado para usar un script en PHP para controlar las peticiones a ficheros no encontrados (usando la directiva ErrorDocument), querrá asegurarse de que el script genera el código de status que corresponde.
<?php
header("HTTP/1.0 404 Not Found");
?>
Para el uso de FastCGI deb usarse la siguiente respuesta para un 404:
<?php
header("Status: 404 Not Found");
?>
El segundo caso especial es el encabezado "Location:" No solamente envía el encabezado al navegador, sino que también devuelve el código de status (302) REDIRECT al navegador a no ser que el código de status 201 o 3xx ya haya sido enviado.
<?php
header("Location: http://www.example.com/"); /* Redirección del navegador */
/* Asegurándonos de que el código interior no será ejecutado cuando se realiza la redirección. */
exit;
?>
replace
El parámetro opcional replace indica
cuando el encabezado debe reemplazar un encabezado previo similar o
añadir un segundo encabezado del mismo tipo. Por defecto lo reemplazará,
pero si se pasa FALSE como segundo argumento se puede forzar
múltiples encabezados del mismo tipo. Por ejemplo:
<?php
header('WWW-Authenticate: Negotiate');
header('WWW-Authenticate: NTLM', false);
?>
http_response_code
Fuerza el código de respuesta HTTP a un valor específico. Observe que
este parámetro solamente tiene efecto si string
no está vacío.
No devuelve ningún valor.
| Versión | Descripción |
|---|---|
| 4.4.2 and 5.1.2 | Esta función ahora previene que se pueda enviar más de un encabezado a la vez como protección en contra de ataques de inyección de encabezados. |
| 4.3.0 |
Se añadió el parámetro http_response_code parameter.
|
| 4.0.4 |
Se añadió el parámetro replace.
|
Ejemplo #1 Diálogo de descarga
Si se quiere preguntar al usuario si quiere guardar los datos que se están enviando, como un fichero PDF generado, puede usarse el encabezado » Content-Disposition para proporcionar un nombre de fichero recomendado y forzar al navegador el mostarar el diálogo para guardar el fichero.
<?php
// Vamos a mostrar un PDF
header('Content-type: application/pdf');
// Se llamará downloaded.pdf
header('Content-Disposition: attachment; filename="downloaded.pdf"');
// La fuente de PDF se encuentra en original.pdf
readfile('original.pdf');
?>
Ejemplo #2 Directivas caché
Scripts PHP normalmente generan contenido dinámico que no debe ser puesto en caché por el navegador cliente o por ningún proxy caché entre el servidor y el navegador cliente. En muchos proxies y clientes se puede forzar la desactivación de la caché con:
<?php
header("Cache-Control: no-cache, must-revalidate"); // HTTP/1.1
header("Expires: Sat, 26 Jul 1997 05:00:00 GMT"); // Fecha en el pasado
?>
Nota:
Seguramente encontrará que sus páginas no están en caché incluso si no se usan los encabezados mencionados más arriba. Existen varias opciones que los usuarios pueden cambiar en sus navegadores para cambiar el comportamiento por defecto de la caché. Al enviar los encabezados mencionados más arriba, se sobreescrirán cualquiera de las opciones que intentan guardar en caché lo que muestre su script.
Adicionalmente, las opciones de configuración de session_cache_limiter() y session.cache_limiter pueden ser usadas para generar automáticamente encabezados caché cuando se están usando sesiones.
Nota:
Las cabeceras sólo serán accesibles y mostradas si se utiliza un SAPI que lo soporte.
Nota:
Se puede usar búfer de salida para evitar este problema, procesando en el servidor todo el contenido a mostrar en el navegador antes de ser enviado. Se puede hacer esto usando ob_start() y ob_end_flush() en el script, o definiendo la directiva output_buffering en el php.ini o en los ficheros de configuración del servidor.
Nota:
El encabezado con el status HTTP siempre será el primero a ser enviado al cliente, sin tener en cuenta si está usando header() con el status en primer lugar o no. El status puede ser sobreescrito pasando a header() un nuevo status en cualquier momento a no ser que los encabezados HTTP ya hayan sido enviados.
Nota:
Existe un bug en Microsoft Internet Explorer 4.01 que hace que no funcione. No existe una solución. También hay un bug en Microsoft Internet Explorer 5.5 que también sucede lo mismo, puede ser resuelto actualizando a Service Pack 2 o superior.
Nota: Si el modo seguro está habilitado el uid del script es añadido en realm del encabezado WWW-Authenticate si se define este encabezado (usado para autenticación HTTP).
Nota:
HTTP/1.1 require una URI absoluta como argumento para » Location: incluyendo el esquema, nombre del host y ruta absoluta, pero algunos clientes aceptan también URIs relativas. Se puede usar $_SERVER['HTTP_HOST'], $_SERVER['PHP_SELF'] y dirname() para crear una URI absoluta desde una relativa:
<?php
/* Redirecciona a una página diferente en el mismo directorio el cual se hizo la petición */
$host = $_SERVER['HTTP_HOST'];
$uri = rtrim(dirname($_SERVER['PHP_SELF']), '/\\');
$extra = 'mypage.php';
header("Location: http://$host$uri/$extra");
exit;
?>
Nota:
El ID de sesión no es pasado con el encabezado Location incluso si session.use_trans_sid está habilitado. Debe ser pasado manualmente usando la constante
SID.