archived-doc-es/reference/network/functions/setcookie.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 6122a8317ca0068fc71f6a5167e0a2d99166ec7c Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no Maintainer: Marqitos -->
<refentry xml:id="function.setcookie" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>setcookie</refname>
  <refpurpose>Envía una cookie</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>setcookie</methodname>
   <methodparam><type>string</type><parameter>name</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>value</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>expires_or_options</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>path</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>domain</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>secure</parameter><initializer>&false;</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>httponly</parameter><initializer>&false;</initializer></methodparam>
  </methodsynopsis>
  <simpara>Firma alternativa disponible a partir de PHP 7.3.0 (no soportado con parámetros nombrados):</simpara>
  <methodsynopsis>
   <type>bool</type><methodname>setcookie</methodname>
   <methodparam><type>string</type><parameter>name</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>value</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
  </methodsynopsis>
  <simpara>
   <function>setcookie</function> define una cookie que será enviada junto con el
   resto de los encabezados HTTP. Al igual que con otros encabezados, las cookies deben ser enviadas
   <emphasis>antes</emphasis> de cualquier salida del script (esto es una
   restricción del protocolo HTTP). Esto requiere que esta función sea llamada
   antes de cualquier salida, incluyendo las etiquetas <literal>&lt;html&gt;</literal> y
   <literal>&lt;head&gt;</literal> así como cualquier espacio en blanco.
  </simpara>
  <simpara>
   Una vez que las cookies han sido establecidas, estarán disponibles durante
   el próximo cargado de página en el array <varname>$_COOKIE</varname>.
   Los valores de las cookies
   también pueden existir en la variable <varname>$_REQUEST</varname>.
  </simpara>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   La <link xlink:href="&url.rfc;6265">RFC 6265</link> es la referencia para
   la interpretación de los argumentos pasados a <function>setcookie</function>.
   <variablelist>
    <varlistentry>
     <term><parameter>name</parameter></term>
     <listitem>
      <simpara>
       El nombre de la cookie.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>value</parameter></term>
     <listitem>
      <simpara>
        El valor de la cookie. Este valor se almacena en el ordenador del cliente;
        no se deben almacenar información importante.
        Si el argumento <parameter>name</parameter> vale <literal>'cookiename'</literal>,
        este valor es recuperado con <varname>$_COOKIE['cookiename']</varname>.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>expires_or_options</parameter></term>
     <listitem>
      <simpara>
       El tiempo después del cual la cookie expira. Esto es un timestamp Unix, por lo tanto,
       será un número de segundos desde la época Unix (1 de enero de 1970).
       Una forma de definir este valor es añadiendo el número de segundos antes
       de que la cookie expire al resultado de una llamada a <function>time</function>.
       Por ejemplo <literal>time()+60*60*24*30</literal> configurará la cookie para
       que expire en 30 días. Otra posibilidad es utilizar la función
       <function>mktime</function>. Si no se especifica este argumento o si vale 0, la cookie expirará
       al final de la sesión (cuando el navegador se cierre).
      </simpara>
      <note>
       <simpara>
        El parámetro <parameter>expires_or_options</parameter> toma una
        marca de tiempo Unix, a diferencia del formato de fecha <literal>Wdy, DD-Mon-YYYY
        HH:MM:SS GMT</literal>, porque PHP realiza esta conversión
        internamente.
       </simpara>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>path</parameter></term>
     <listitem>
      <simpara>
       La ruta en el servidor donde la cookie estará disponible.
       Si el valor es <literal>'/'</literal>, la cookie estará disponible
       en todo el dominio <parameter>domain</parameter>. Si el valor
       es <literal>'/foo/'</literal>, la cookie estará únicamente disponible
       en el directorio <literal>/foo/</literal> así como todos sus
       subdirectorios como <literal>/foo/bar/</literal> en el dominio
       <parameter>domain</parameter>. El valor por omisión es el directorio
       actual donde la cookie fue definida.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>domain</parameter></term>
     <listitem>
      <simpara>
       El (sub-)dominio para el cual la cookie está disponible. Definir esto a un
       subdominio (tal como <literal>'www.example.com'</literal>) hará que la cookie
       esté disponible para este subdominio así como todos sus subdominios
       (por ejemplo: w2.www.example.com). Para hacer que la cookie
       esté disponible en todo el dominio (así como todos sus subdominios), simplemente
       defina el valor con el nombre de dominio (<literal>'example.com'</literal>,
       en este ejemplo).
      </simpara>
      <simpara>
       Los navegadores antiguos que continúan implementando la
       <link xlink:href="&url.rfc;2109">RFC 2109</link> (obsoleta)
       pueden requerir un <literal>.</literal> para hacer disponible
       todos los subdominios.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>secure</parameter></term>
     <listitem>
      <simpara>
       Indica si la cookie debe ser transmitida únicamente a través de una
       conexión segura HTTPS desde el cliente. Cuando este argumento
       vale &true;, la cookie solo será enviada si la conexión es segura.
       Del lado del servidor, es responsabilidad del desarrollador enviar este tipo de cookie
       únicamente en conexiones seguras (por ejemplo, utilizando
       la variable <varname>$_SERVER["HTTPS"]</varname>).
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>httponly</parameter></term>
     <listitem>
      <simpara>
       Cuando este argumento vale &true;, la cookie solo será accesible por
       el protocolo HTTP. Esto significa que la cookie no será accesible
       vía lenguajes de script, como Javascript. Se ha sugerido que esta
       configuración permite limitar ataques XSS (aunque no es soportada por todos los navegadores),
       sin embargo este hecho es frecuentemente cuestionado.
       &true; o &false;
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <simpara>
       Un &array; asociativo que puede tener como claves
       <literal>expires</literal>, <literal>path</literal>, <literal>domain</literal>,
       <literal>secure</literal>, <literal>httponly</literal> y <literal>samesite</literal>.
      </simpara>
      <simpara>
       Los valores tienen el mismo significado que los descritos para los argumentos
       con el mismo nombre. El valor del elemento <literal>samesite</literal> debe
       ser <literal>None</literal>, <literal>Lax</literal> o <literal>Strict</literal>.
       Si una opción autorizada no es dada, entonces su valor por omisión será
       idéntico al valor por omisión de los argumentos explícitos. Si el elemento
       <literal>samesite</literal> es omitido, entonces el atributo SameSite de la cookie
       no será definido.
      </simpara>
      <note>
       <simpara>
        Para definir una cookie que incluye atributos que no figuran entre las claves listadas,
        utilice <function>header</function>.
       </simpara>
      </note>
      <note>
       <simpara>
        Si <literal>samesite</literal> es <literal>"None"</literal>, entonces
        <literal>secure</literal> también debe estar habilitado o el cliente
        bloqueará la cookie.
       </simpara>
      </note>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <simpara>
   Si algo fue enviado a la salida estándar antes de la llamada
   a esta función, <function>setcookie</function> fallará y
   retornará &false;. Si <function>setcookie</function> tiene éxito,
   retornará &true;.
   Esto no indica si el cliente acepta o no la cookie.
  </simpara>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simpara>
   Si el &array; <parameter>options</parameter> contiene claves no soportadas:
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     Antes de PHP 8.0.0, se generaba un <constant>E_WARNING</constant>.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     A partir de PHP 8.0.0, se lanza una <exceptionname>ValueError</exceptionname>.
    </simpara>
   </listitem>
  </itemizedlist>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.2.0</entry>
      <entry>
       La fecha de la cookie está en formato <literal>'D, d M Y H:i:s \G\M\T'</literal>;
       previamente era <literal>'D, d-M-Y H:i:s T'</literal>.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       Pasar claves no soportadas ahora lanza una <exceptionname>ValueError</exceptionname>
       en lugar de emitir un <constant>E_WARNING</constant>.
      </entry>
     </row>
     <row>
      <entry>7.3.0</entry>
      <entry>
       Se añadió una firma alternativa que soporta un array
       de <parameter>options</parameter>. Esta firma soporta la definición del atributo SameSite de la cookie.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <simpara>
   Los efectos de los siguientes ejemplos se pueden observar utilizando la lista de cookies de las
   herramientas para desarrolladores del navegador (normalmente en la pestaña Almacenamiento o Aplicación).
  </simpara>
  <example>
   <title>Ejemplo de envío de una cookie con <function>setcookie</function></title>
   <programlisting role="php">
<![CDATA[
<?php

$value = 'Valor de prueba';

// Establecer una "cookie de sesión" que caduca cuando se cierra el navegador
setcookie("TestCookie", $value);
// Establecer una cookie que expira en 1 hora
setcookie("TestCookie", $value, time()+3600);
// Establecer una cookie que se aplique solo a una ruta específica en un dominio específico.
// Tenga en cuenta que el dominio utilizado debe coincidir con el dominio del sitio.
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", true);
?>
]]>
   </programlisting>
  </example>
  <simpara>
   Tenga en cuenta que PHP codificará y decodificará automáticamente
   la parte del valor de la cookie. Esto se puede evitar usando
   <function>setrawcookie</function>.
  </simpara>
  <simpara>
   Para ver el contenido de las cookies configuradas en el ejemplo anterior en una
   solicitud posterior:
  </simpara>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
// Mostrar una cookie
echo $_COOKIE["TestCookie"];

// Otro método para mostrar todas las cookies
print_r($_COOKIE);
?>
]]>
   </programlisting>
  </informalexample>
  <example>
   <title>Ejemplo de borrado de una cookie con <function>setcookie</function></title>
   <simpara>
    Para eliminar una cookie, configure la fecha de expiración en un valor del pasado
    (pero no cero, que está reservado para las cookies de sesión).
   </simpara>
   <simpara>
    Para eliminar las cookies establecidas en el ejemplo anterior:
   </simpara>
   <programlisting role="php">
<![CDATA[
<?php
// Define la fecha de expiración a una hora antes de la fecha actual
setcookie("TestCookie", "", time() - 3600);
setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
?>
]]>
   </programlisting>
  </example>
  <example>
   <title><function>setcookie</function> y los arrays</title>
   <simpara>
    Se puede establecer un "array de cookies" usando la notación de array en el
    nombre de la cookie. Esto permite configurar tantas cookies como
    elementos haya en el array, pero cuando el script recibe la cookie,
    todos los valores se colocan en un array con el nombre de la
    cookie:
   </simpara>
   <programlisting role="php">
<![CDATA[
<?php
// Establece las cookies
setcookie("cookie[three]", "cookiethree");
setcookie("cookie[two]", "cookietwo");
setcookie("cookie[one]", "cookieone");

// Después del recargado de la página, las mostramos
if (isset($_COOKIE['cookie'])) {
    foreach ($_COOKIE['cookie'] as $name => $value) {
        $name = htmlspecialchars($name);
        $value = htmlspecialchars($value);
        echo "$name : $value <br />\n";
    }
}
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
three : cookiethree
two : cookietwo
one : cookieone
]]>
   </screen>
  </example>
  <note>
   <simpara>
    El uso de caracteres de separación como <literal>[</literal> y
    <literal>]</literal> como parte del nombre de la cookie no es respetuoso con la RFC 6265, sección 4, pero se asume que es soportado
    por los agentes de usuario, siguiendo la RFC 6265, sección 5.
   </simpara>
  </note>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <simpara>
    El almacenamiento en búfer de salida permite la salida del script antes de
    llamar a esta función. Toda la salida se almacenará en búfer hasta que se vacíe
    (ya sea explícitamente o al final de la ejecución del script). Puede hacer esto
    llamando a <function>ob_start</function> y
    <function>ob_end_flush</function> en ek script, o activando la directiva
    <literal>output_buffering</literal> en su archivo de configuración
    &php.ini; o en el archivo de configuración de su servidor.
   </simpara>
  </note>
  <para>
   Errores comunes:
   <itemizedlist>
    <listitem>
     <simpara>
      Las cookies solo serán accesibles al cargar la próxima página,
      o al recargar la página actual. Para probar si una cookie
      ha sido definida con éxito, verifique la presencia de la cookie en el próximo
      cargado de página antes de que la cookie expire. El tiempo de expiración
      se define utilizando el argumento <parameter>expires_or_options</parameter>.
      Una forma sencilla de verificar el posicionamiento de la cookie es utilizar
      <literal>print_r($_COOKIE);</literal>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Las cookies deben ser borradas con los mismos argumentos
      que los utilizados durante su creación. Si el argumento
      <parameter>value</parameter> es una cadena vacía y los otros argumentos son exactamente los mismos que en una llamada <function>setcookie</function> previa,
      entonces la cookie será borrada del cliente.
      Internamente, el borrado se realiza posicionando el valor a
      <literal>'deleted'</literal> y la fecha de expiración a un año en el pasado.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Dado que la asignación de un valor valiendo &false; a una cookie intentará borrarla,
      no se deben utilizar valores booleanos. En su lugar, utilice <emphasis>0</emphasis> para &false;
      y <emphasis>1</emphasis> para &true;.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Los nombres de las cookies se pueden establecer como nombres de array y estarán disponibles
      para los scripts PHP como arrays, pero el navegador almacena cookies independientes.
      Considere usar <function>json_encode</function> para establecer una cookie con varios
      nombres y valores. No se recomienda usar <function>serialize</function>
      para este propósito, ya que puede generar vulnerabilidades de seguridad.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <simpara>
   Las llamadas múltiples a la función <function>setcookie</function> se realizarán en orden.
  </simpara>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><function>header</function></member>
   <member><function>setrawcookie</function></member>
   <member><link linkend="features.cookies">cookies section</link></member>
   <member><link xlink:href="&url.rfc;6265">RFC 6265</link></member>
   <member><link xlink:href="&url.rfc;2109">RFC 2109</link></member>
  </simplelist>
 </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
-->