setcookie.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 4a7ddddc27271967b616ad3400cfbe2a9b48212b Maintainer: andresdzphp Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.setcookie" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>setcookie</refname>
  <refpurpose>Enviar una cookie</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis role="procedural">
   <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</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>
  <methodsynopsis role="procedural">
   <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>
  <para>
   <function>setcookie</function> define una cookie para ser enviada junto
   con el resto de cabeceras HTTP. Como otros encabezados, cookies deben ser enviadas
   <emphasis>antes</emphasis> de cualquier salida en el script (este es un
   protocolo de restricción). Esto requiere que hagas llamadas a esta función
   antes de cualquier salida, incluyendo etiquetas <literal>&lt;html&gt;</literal> y
   <literal>&lt;head&gt;</literal> así como cualquier espacio en blanco.
  </para>
  <para>
   Una vez que las cookies se han establecido, se puede acceder a ellas en la siguiente página de carga
   con el array <varname>$_COOKIE</varname>.
   valores Cookie
   también pueden existir en <varname>$_REQUEST</varname>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <link xlink:href="&url.rfc;6265">RFC 6265</link> proporciona la referencia
   normativa como cada parámetro <function>setcookie</function> es
   interpretado.
   <variablelist>
    <varlistentry>
     <term><parameter>name</parameter></term>
     <listitem>
      <para>
       El nombre de la cookie.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>value</parameter></term>
     <listitem>
      <para>
       El valor de la cookie. Este valor se almacena en el ordenador del cliente;
       no almacenar información sensible. Asumiendo que el
       <parameter>name</parameter> es <literal>'cookiename'</literal>, este
       valor es recuperado a través de <varname>$_COOKIE['cookiename']</varname>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>expires</parameter></term>
     <listitem>
      <para>
       El tiempo en que la cookie expira. Esta es una marca de tiempo Unix
       en número de segundos desde la época. En otras palabras, lo más probable
       es que se haga con la función <function>time</function>
       más el número de segundos antes de que quiera que expire. O
       se podría usar <function>mktime</function>.
       <literal>time()+60*60*24*30</literal> hará que la cookie establecida
       expire en 30 días. Si se establece a 0, o es omitido, la cookie expirará
       al final de la sesión (cuando el navegador es cerrado).
      </para>
      <para>
       <note>
        <para>
         Puede notar que el parámetro <parameter>expires</parameter> toma una
         marca de tiempo Unix, en lugar de formato de fecha <literal>Wdy, DD-Mon-YYYY
         HH:MM:SS GMT</literal>, esto es porque PHP hace la conversión
         internamente.
        </para>
       </note>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>path</parameter></term>
     <listitem>
      <para>
       La ruta dentro del servidor en la que la cookie estará disponible.
       Si se utiliza <literal>'/'</literal>, la cookie estará disponible
       en la totalidad del <parameter>domain</parameter>. Si se configura
       como <literal>'/foo/'</literal>, la cookie sólo estará disponible
       dentro del directorio <literal>/foo/</literal> y todos sus
       sub-directorios en el <parameter>domain</parameter>, tales como
       <literal>/foo/bar/</literal>. El valor por defecto es el
       directorio actual en donde se está configurando la cookie.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>domain</parameter></term>
     <listitem>
      <para>
       El (sub)dominio al que la cookie está disponible. Estableciendo esto a un
       subdominio (como <literal>'www.example.com'</literal>) hará que la
       cookie esté disponible para ese subdominio y todos los demás subdominios del mismo (p.e.
       w2.www.example.com). Para que la cookie esté disponible para todo el dominio
       (incluyendo todos sus subdominios), simplemente establezca el nombre de
       domonio (<literal>'example.com'</literal>, en este caso).
      </para>
      <para>
       Los navegadores más antiguos todavía implementan la obsoleta
       <link xlink:href="&url.rfc;2109">RFC 2109</link> pueden necesitar un
       <literal>.</literal> para comparar todos los subdominios.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>secure</parameter></term>
     <listitem>
      <para>
       Indica que la cookie sólo debiera transmitirse por una
       conexión segura HTTPS desde el cliente. Cuando se configura como &true;,
       la cookie sólo se creará si es que existe una conexión segura.
       Del lado del servidor, depende del programador el enviar este
       tipo de cookies solamente a través de conexiones seguras (por ejemplo,
       con <varname>$_SERVER["HTTPS"]</varname>).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>httponly</parameter></term>
     <listitem>
      <para>
       Cuando es &true; la cookie será accesible sólo a través del protocolo
       HTTP. Esto significa que la cookie no será accesible por lenguajes
       de scripting, como JavaScript. Se ha indicado que esta configuración
       ayuda efectivamente a reducir el robo de identidad a través de ataques XSS (aunque no
       es soportada por todos los navegadores). pero esa afirmación se disputa a menudo. Agregado en PHP 5.2.0.
       Puede ser &true; o &false;
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
       Un <type>array</type> asociativo que puede tener cualquiera de las claves
       <literal>expires</literal>, <literal>path</literal>, <literal>domain</literal>,
       <literal>secure</literal>, <literal>httponly</literal> y <literal>samesite</literal>.
       Los valores tienen el mismo significado que se describe para los parámetros con
       el mismo nombre. El valor de el elemento <literal>samesite</literal> debería
       ser <literal>None</literal>, <literal>Lax</literal> o <literal>Strict</literal>.
       Si no se da ninguna de las opciones permitidas, sus valores por defecto son los
       mismos que los valores por defecto de los parámetros explícitos. Si el
       elemento <literal>samesite</literal> es omitido, no se establece ningún
       atributo de la cookie SameSite.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Si existe algún tipo de output anterior a la llamada de esta función,
   <function>setcookie</function> fallará y retornará &false;. Si
   <function>setcookie</function> ejecuta satisfactoriamente, retornará &true;.
   Esto no indica si es que el usuario ha aceptado la cookie o no.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   A continuación se presentan algunos ejemplos de cómo enviar cookies:
   <example>
    <title>Ejemplo de envío con <function>setcookie</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$value = 'something from somewhere';

setcookie("TestCookie", $value);
setcookie("TestCookie", $value, time()+3600);  /* expira en 1 hora */
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", 1);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Nótese que la parte del valor de la cookie será automáticamente
   codificada con urlencode al enviar la cookie, y al ser recibida
   será automáticamente decodificada y asignada a una variable con el mismo
   nombre que el nombre de la cookie. Si no se desea ésto, se puede usar
   <function>setrawcookie</function> si es que se está utilizando PHP 5. Para ver
   el contenido de nuestra cookie de prueba en un script, simplemente siga
   uno de los ejemplo siguientes:
  </para>
  <para>
   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
// Imprime una cookie individual
echo $_COOKIE["TestCookie"];

// Otra forma de depurar/prueba es ver todas las cookies
print_r($_COOKIE);
?>
]]>
    </programlisting>
   </informalexample>
  </para>
  <para>
   <example>
    <title>Ejemplo de eliminación con <function>setcookie</function></title>
    <para>
     Al borrar una cookie debe asegurarse que la fecha de expiración
     ya ha pasado, de modo a detonar el mecanismo de eliminación del navegador.
     El siguiente ejemplo muestra cómo borrar las cookies enviadas en el ejemplo anterior:
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// establecer la fecha de expiración a una hora atrás
setcookie("TestCookie", "", time() - 3600);
setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>setcookie</function> y los arrays</title>
    <para>
     También puede crear arrays de cookies utilizando la notación de arrays
     en el nombre de la cookie. El efecto de esto es de crear tantas cookies
     como elementos hay en el array, pero al recibir el script la cookie, todos
     los valores son colocados en un array con el nombre de la
     cookie:
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// set the cookies
setcookie("cookie[three]", "cookiethree");
setcookie("cookie[two]", "cookietwo");
setcookie("cookie[one]", "cookieone");

// después de que la página se recargue, imprime
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>
  </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>7.3.0</entry>
       <entry>
        Una alternativa que soporta un array <parameter>options</parameter>
        ha sido añadida. Esta alternativa soporta también la configuración del atributo
        de la cookie de SameSite.
       </entry>
      </row>
      <row>
       <entry>5.5.0</entry>
       <entry>
        Ahora se incluye un atributo Max-Age en la cabecera Set-Cookie enviada al
        cliente.
       </entry>
      </row>
      <row>
       <entry>5.2.0</entry>
       <entry>
        Se añadió el parámetro <parameter>httponly</parameter>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Se puede utilizar buffering de salida para enviar output anterior a
    la llamada a esta función, de modo que todo el output hacia el browser
    sea almacenado en el servidor hasta que lo envíe. Para hacer ésto
    invoque en su script a <function>ob_start</function> y
    <function>ob_end_flush</function>, o active la directiva de configuración
    <literal>output_buffering</literal> en el
    archivo &php.ini; o en los archivos de configuración del servidor.
   </para>
  </note>
  <para>
   Common Pitfalls:
   <itemizedlist>
    <listitem>
     <simpara>
      Las cookies no se volverán visibles hasta la próxima carga de la página
      en la que debieran serlo. Para probar si se ha creado correctamente una
      cookie, se debe buscar la cookie en alguna página cargada posteriormente
      y antes que la cookie expire. El tiempo de expiración se establece con el
      parámetro <parameter>expires</parameter>. Una forma sencilla de verificar
      la existencia de cookies es invocando <literal>print_r($_COOKIE);</literal>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Las cookies deben ser borradas usando los mismos parámetros con que fueron creadas.
      Si el argumento del valor es un string vacío o &false;, y todos los demás argumentos
      coinciden con una llamada anterior a setcookie, entonces la cookie con el nombre
      especificado será eliminada del cliente remoto.
      Internamente ésto se logra estableciendo el valor a 'deleted' y el tiempo
      de expiración a un año atrás.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Ya que configurar el valor de una cookie como &false; intentará eliminar la cookie,
      no se debieran utilizar valores booleanos. En su lugar, use <emphasis>0</emphasis> como &false;
      y <emphasis>1</emphasis> como &true;.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Los nombres de las cookies pueden declararse como nombres de arrays y estarán disponibles
      en sus scripts PHP como arrays, pero en el sistema del usuario se guardarán como cookies
      separadas. Considere la función <function>explode</function> para crear una sola cookie
      con nombres y valores múltiples. No se recomienda utilizar la función
      <function>serialize</function> para este propósito, pues puede significar
      vulnerabilidades en la seguridad.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <simpara>
   Múltiples llamadas a <function>setcookie</function> se efectúan en el orden de llamada.
  </simpara>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <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>
  </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
-->