mirror of
https://github.com/php/doc-es.git
synced 2026-03-24 07:22:16 +01:00
342 lines
11 KiB
XML
342 lines
11 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<!-- EN-Revision: 5c1ccc6e24e5d470e75ef0a5887c2ff583266375 Maintainer: PhilDaiguille 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>Envía un encabezado HTTP bruto</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>header</methodname>
|
|
<methodparam><type>string</type><parameter>header</parameter></methodparam>
|
|
<methodparam choice="opt"><type>bool</type><parameter>replace</parameter><initializer>&true;</initializer></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>response_code</parameter><initializer>0</initializer></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>header</function> permite especificar el encabezado <acronym>HTTP</acronym>
|
|
<parameter>string</parameter> al enviar los ficheros HTML.
|
|
Consúltese <link xlink:href="&url.rfc;2616"><literal>HTTP/1.1
|
|
Specification</literal></link> para obtener más información sobre los encabezados
|
|
<acronym>HTTP</acronym>.
|
|
</para>
|
|
<para>
|
|
Nunca se olvide que <function>header</function> debe ser llamada
|
|
antes de que se envíe cualquier contenido, ya sea por líneas HTML habituales en el fichero,
|
|
o por salidas PHP. Un error muy común es leer un fichero con
|
|
<function>include</function> o
|
|
<function>require</function>,
|
|
y dejar espacios o líneas vacías, que producirán una salida antes de que la función <function>header</function>
|
|
sea llamada. El mismo problema existe con los ficheros
|
|
PHP/HTML estándar.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<html>
|
|
<?php
|
|
/* Esto producirá un error. Observe la salida anterior,
|
|
* que se encuentra antes de la llamada a la función header() */
|
|
header('Location: http://www.example.com/');
|
|
exit;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>header</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
El encabezado.
|
|
</para>
|
|
<para>
|
|
Existen dos encabezados especiales. El primero comienza con la cadena
|
|
"<literal>HTTP/</literal>" (insensible a mayúsculas/minúsculas), que se utiliza
|
|
para indicar el estado HTTP a enviar. Por ejemplo, si se ha configurado
|
|
Apache para utilizar scripts PHP para manejar las peticiones hacia ficheros
|
|
inexistentes (utilizando la directiva <literal>ErrorDocument</literal>),
|
|
asegúrese de que el script genere un código de estado correcto.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// Este ejemplo ilustra el caso especial "HTTP/"
|
|
// Alternativas mejores en casos típicos de uso incluyen:
|
|
// 1. header($_SERVER["SERVER_PROTOCOL"] . " 404 Not Found");
|
|
// (para sobrescribir mensajes de estado HTTP para clientes que aún usan HTTP/1.0)
|
|
// 2. http_response_code(404); (para usar el mensaje por defecto)
|
|
header("HTTP/1.1 404 Not Found");
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
El segundo tipo de llamada especial es <literal>"Location:"</literal>.
|
|
No solo devuelve un encabezado al cliente, sino que además
|
|
envía un estado <literal>REDIRECT</literal> (302) al navegador
|
|
siempre que no se haya enviado un código de estado <literal>201</literal> o <literal>3xx</literal>.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header("Location: http://www.example.com/"); /* Redirección del navegador */
|
|
|
|
/* Asegúrese de que el código siguiente no se ejecute una vez realizada la redirección. */
|
|
exit;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>replace</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
El argumento opcional <parameter>replace</parameter> indica
|
|
si la función <function>header</function> debe reemplazar
|
|
un encabezado previamente enviado, o bien añadir otro encabezado
|
|
del mismo tipo. Por omisión, un nuevo encabezado sobrescribirá el
|
|
anterior, pero si se pasa &false; en este argumento, se pueden
|
|
forzar múltiples encabezados para un mismo tipo de encabezado.
|
|
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>response_code</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Fuerza el código de respuesta HTTP al valor especificado. Tenga en cuenta que este
|
|
argumento solo tiene efecto si <parameter>header</parameter>
|
|
no está vacío.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
&return.void;
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="errors">
|
|
&reftitle.errors;
|
|
<para>
|
|
Cuando falla el intento de enviar un encabezado,
|
|
<function>header</function> genera un error de nivel
|
|
<constant>E_WARNING</constant>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title>Caja de descarga</title>
|
|
<para>
|
|
Si se desea que los usuarios reciban una alerta para guardar
|
|
los ficheros generados, como si se genera un
|
|
fichero PDF, se puede utilizar el encabezado
|
|
<link xlink:href="&url.rfc;2183">Content-Disposition</link> para
|
|
proporcionar un nombre de fichero por defecto, a mostrar en el
|
|
diálogo de guardado.
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// Se desea mostrar un pdf
|
|
header('Content-Type: application/pdf');
|
|
|
|
// Será nombrado downloaded.pdf
|
|
header('Content-Disposition: attachment; filename="downloaded.pdf"');
|
|
|
|
// El origen del PDF original.pdf
|
|
readfile('original.pdf');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Directivas concernientes a la caché</title>
|
|
<para>
|
|
Los scripts PHP generan a menudo HTML dinámico,
|
|
que no debe ser almacenado en caché, ni por el cliente, ni por los
|
|
proxy intermedios. Se puede forzar la desactivación de la
|
|
caché de muchos clientes y proxy 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>
|
|
Puede darse cuenta de que sus páginas nunca son almacenadas en caché incluso si se utilizan todos los encabezados anteriores.
|
|
Existe toda una colección de parámetros que los usuarios pueden modificar en su navegador para cambiar el
|
|
comportamiento por defecto de la caché. Al enviar los encabezados anteriores, se pueden imponer sus propias valores.
|
|
</para>
|
|
<para>
|
|
Además, los parámetros <function>session_cache_limiter</function> y
|
|
<literal>session.cache_limiter</literal> pueden ser utilizados para
|
|
generar los encabezados de caché correctos, cuando se utilizan sesiones.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Configurar una cookie</title>
|
|
<para>
|
|
<function>setcookie</function> ofrece un medio práctico de configurar cookies.
|
|
Para definir una cookie con atributos no soportados por <function>setcookie</function>,
|
|
<function>header</function> puede ser utilizado.
|
|
</para>
|
|
<para>
|
|
Por ejemplo, el código siguiente define una cookie que incluye un atributo
|
|
<literal>Partitioned</literal>.
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header('Set-Cookie: name=value; Secure; Path=/; SameSite=None; Partitioned;');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
¬e.network.header.sapi;
|
|
<note>
|
|
<para>
|
|
Se puede utilizar el sistema de caché (output buffering)
|
|
para evitar este problema. Todo el texto generado será almacenado en buffer en el servidor hasta que se envíe. Se pueden
|
|
utilizar las funciones <function>ob_start</function> y
|
|
<function>ob_end_flush</function> en los scripts, o modificando la directiva de configuración <literal>output_buffering</literal>
|
|
en el fichero &php.ini; o los ficheros
|
|
de configuración del servidor.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
El código de estado HTTP debe ser siempre el primero en enviarse al cliente,
|
|
en relación con la actual <function>header</function> que puede ser el primero
|
|
o no. El estado puede ser sobrescrito llamando a <function>header</function>
|
|
con un nuevo estado en cualquier momento, incluso si el encabezado HTTP ya ha sido enviado.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
La mayoría de los clientes modernos aceptan <acronym>URI</acronym>s relativas como argumento de
|
|
<link xlink:href="&spec.http1.1;#section-7.1.2">Location:</link>,
|
|
pero algunos clientes más antiguos exigen una URI absoluta
|
|
incluyendo el protocolo, el host y la ruta absoluta. Se puede utilizar generalmente las variables globales <varname>$_SERVER['HTTP_HOST']</varname>,
|
|
<varname>$_SERVER['PHP_SELF']</varname> y <function>dirname</function> para
|
|
construir una URI absoluta:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
/* Redirección hacia una página diferente del mismo directorio */
|
|
$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á activado. Debe ser pasado manualmente utilizando 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><function>header_remove</function></member>
|
|
<member><function>headers_list</function></member>
|
|
<member>
|
|
La sección sobre la'<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
|
|
-->
|