mirror of
https://github.com/php/doc-es.git
synced 2026-03-25 16:02:13 +01:00
ce2e8abb67
git-svn-id: https://svn.php.net/repository/phpdoc/es/trunk@334597 c90b9560-bf6c-de11-be94-00142212c4b1
349 lines
11 KiB
XML
349 lines
11 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<!-- EN-Revision: afc3f34c682418a582b0f9199db0bac4a087821f Maintainer: chuso Status: ready -->
|
|
<!-- Reviewed: no -->
|
|
<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.header">
|
|
<refnamediv>
|
|
<refname>header</refname>
|
|
<refpurpose>Enviar encabezado sin formato HTTP</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>header</methodname>
|
|
<methodparam><type>string</type><parameter>string</parameter></methodparam>
|
|
<methodparam choice="opt"><type>bool</type><parameter>replace</parameter><initializer>true</initializer></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>http_response_code</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>header</function> es usado para enviar encabezados <acronym>HTTP</acronym>
|
|
sin formato. Ver la especificación <link xlink:href="&url.rfc;2616">HTTP/1.1 specification</link>
|
|
para más información sobre encabezados <acronym>HTTP</acronym>.
|
|
</para>
|
|
<para>
|
|
Recuerde que <function>header</function> 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 <function>include</function> o <function>require</function>,
|
|
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 <function>header</function>.
|
|
Sucede el mismo problema cuando se utiliza un solo fichero PHP/HTML.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<html>
|
|
<?php
|
|
/* Esto producirá un error. Fíjese en el html
|
|
* que se muestra antes que la llamada a header() */
|
|
header('Location: http://www.example.com/');
|
|
exit;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>string</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
El encabezado en formato cadena.
|
|
</para>
|
|
<para>
|
|
Existen dos casos especiales en el uso de header. El primero el encabezado que
|
|
empieza con la cadena "<literal>HTTP/</literal>" (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 <literal>ErrorDocument</literal>), querrá asegurarse
|
|
de que el script genera el código de status que corresponde.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header("HTTP/1.0 404 Not Found");
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
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) <literal>REDIRECT</literal> al navegador
|
|
a no ser que el código de status <literal>201</literal> o
|
|
<literal>3xx</literal> ya haya sido enviado.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?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;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>replace</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
El parámetro opcional <parameter>replace</parameter> 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:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header('WWW-Authenticate: Negotiate');
|
|
header('WWW-Authenticate: NTLM', false);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>http_response_code</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Fuerza el código de respuesta HTTP a un valor específico. Observe que
|
|
este parámetro solamente tiene efecto si <parameter>string</parameter>
|
|
no está vacío.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
&return.void;
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="changelog">
|
|
&reftitle.changelog;
|
|
<para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>5.1.2</entry>
|
|
<entry>
|
|
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.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title>Diálogo de descarga</title>
|
|
<para>
|
|
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 <link
|
|
xlink:href="&url.rfc;2183">Content-Disposition</link> para
|
|
proporcionar un nombre de fichero recomendado y forzar al navegador el mostarar
|
|
el diálogo para guardar el fichero.
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?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');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Directivas caché</title>
|
|
<para>
|
|
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:
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?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
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
<note>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
Adicionalmente, las opciones de configuración de <function>session_cache_limiter</function> y
|
|
<literal>session.cache_limiter</literal> pueden ser usadas para generar automáticamente
|
|
encabezados caché cuando se están usando sesiones.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
¬e.network.header.sapi;
|
|
<note>
|
|
<para>
|
|
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
|
|
<function>ob_start</function> y <function>ob_end_flush</function>
|
|
en el script, o definiendo la directiva <literal>output_buffering</literal>
|
|
en el &php.ini; o
|
|
en los ficheros de configuración del servidor.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
El encabezado con el status HTTP siempre será el primero a ser enviado
|
|
al cliente, sin tener en cuenta si está usando <function>header</function>
|
|
con el status en primer lugar o no. El status puede ser sobreescrito
|
|
pasando a <function>header</function> un nuevo status
|
|
en cualquier momento a no ser que los encabezados HTTP ya hayan sido enviados.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<simpara>
|
|
Si el <link linkend="ini.safe-mode">modo seguro</link> está habilitado el
|
|
uid del script es añadido en <literal>realm</literal>
|
|
del encabezado <literal>WWW-Authenticate</literal> si se define
|
|
este encabezado (usado para autenticación HTTP).
|
|
</simpara>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
HTTP/1.1 require una <acronym>URI</acronym> absoluta como argumento para
|
|
<link xlink:href="&spec.http1.1;-sec14.html#sec14.30">Location:</link>
|
|
incluyendo el esquema, nombre del host y ruta absoluta, pero
|
|
algunos clientes aceptan también URIs relativas. Se puede usar
|
|
<varname>$_SERVER['HTTP_HOST']</varname>,
|
|
<varname>$_SERVER['PHP_SELF']</varname>
|
|
y <function>dirname</function> para crear una URI absoluta desde
|
|
una relativa:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?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;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
El ID de sesión no es pasado con el encabezado Location incluso si <link
|
|
linkend="ini.session.use-trans-sid">session.use_trans_sid</link> está
|
|
habilitado. Debe ser pasado manualmente usando la constante
|
|
<constant>SID</constant>.
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><function>headers_sent</function></member>
|
|
<member><function>setcookie</function></member>
|
|
<member><function>http_response_code</function></member>
|
|
<member>
|
|
La sección<link linkend="features.http-auth">Autenticación
|
|
HTTP</link>
|
|
</member>
|
|
</simplelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|