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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 7a35b9c421a8626895621f3eea7bb36b24fe569d 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>
   <type>bool</type><methodname>setcookie</methodname>
   <methodparam><type>string</type><parameter>name</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>value</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>expire</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>path</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>domain</parameter></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>
  <para>
   <function>setcookie</function> define una cookie para ser enviada junto con el
   resto de las cabeceras de HTTP. Al igual que otras cabeceras, las cookies deben ser enviadas
   <emphasis>antes</emphasis> de que el script genere ninguna salida (es una
   restricción del protocolo). Ésto implica que las llamadas a esta función se coloquen 
   antes de que se genere cualquier salida, incluyendo las etiquetas <literal>&lt;html&gt;</literal> y 
   <literal>&lt;head&gt;</literal> al igual que cualquier espacio en blanco.
  </para>
  <para>
   Una vez que han sido enviadas las cookies, se puede acceder a ellas en la próxima carga de la página
   gracias a los arrays <varname>$_COOKIE</varname> o <varname>$HTTP_COOKIE_VARS</varname>. Nótese que
   las <link linkend="language.variables.superglobals">superglobales</link>
   tales como <varname>$_COOKIE</varname> están disponibles a partir de PHP 4.1.0.
   El valor de
   las cookies también está en <varname>$_REQUEST</varname>.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   Todos los argumentos exceptuando el argumento <parameter>name</parameter> son
   opcionales. También puede reemplazar un argumento con un string vacío
   (<emphasis>&quot;&quot;</emphasis>) para saltárselo.
   Ya que el argumento <parameter>expire</parameter> es un entero, no puede
   pasarse por alto con un string vacío, en su lugar utilice un
   cero (<emphasis>0</emphasis>).
  </para>
  <para>
   La referencia <link xlink:href="&url.rfc;2109">RFC 6265</link> provee la
   normativa que establece cómo debe ser interpretado cada parámetro de
   <function>setcookie</function>.
   <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 guarda en el computador del cliente;
       no almacene información sensible. Asumiendo que el
       <parameter>name</parameter> es <literal>'cookiename'</literal>, este
       valor se obtiene con <varname>$_COOKIE['cookiename']</varname>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>expire</parameter></term>
     <listitem>
      <para>
       El tiempo en el que expira la cookie. Es una fecha Unix por tanto
       está en número de segundos a partir de la presente época. En otras palabras,
       probablemente utilizará la función <function>time</function> más
       el número de segundos que quiere que dure la cookie. También
       podría utilizar la función <function>mktime</function>.
       <literal>time()+60*60*24*30</literal> configurará la cookie para
       expirar en 30 días. Si se pone 0, o se omite, la cookie expirará al
       final de la sesión (al cerrarse el navegador).
      </para>
      <para>
       <note>
        <para>
         Puede notar que el parámetro <parameter>expire</parameter> recibe una
         fecha Unix, por oposición al formato de fecha <literal>Wdy, DD-Mon-YYYY
         HH:MM:SS GMT</literal>, esto se debe a que PHP realiza esta 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 dominio para el cual la cookie está disponible. Establecer el dominio a
       <literal>'www.example.com'</literal> hará que la cookie esté
       disponible en el subdominio <literal>www</literal> y subdominios superiores.
       Las cookies disponibles en un dominio inferior, como
       <literal>'example.com'</literal>, estarán disponibles en dominios superiores,
       como <literal>'www.example.com'</literal>.
       
       Los navegadores antiguos que aún implementan la referencia obsoleta
       <link xlink:href="&url.rfc;2109">RFC 2109</link> pueden necesitar un
       <literal>.</literal> al inicio 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>
   </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 algunos ejemplos acerca de cómo enviar cookies:
   <example>
    <title>ejemplo de envío con <function>setcookie</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$value = 'cualquier cosa';

setcookie("TestCookie", $value);
setcookie("TestCookie", $value, time()+3600);  /* expira en una 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
// Imprimir una cookie individual
echo $_COOKIE["TestCookie"];
echo $HTTP_COOKIE_VARS["TestCookie"];

//Otra manera de depurar/probar es viendo todas las cookies
print_r($_COOKIE);
?>
]]>
    </programlisting>
   </informalexample>
  </para>
  <para>
   <example>
    <title>ejemplo de borrado con <function>setcookie</function></title>
    <para>
     Al borrar una cookie debiese 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 ésto 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
// crear las cookies
setcookie("cookie[tres]", "cookietres");
setcookie("cookie[dos]", "cookiedos");
setcookie("cookie[uno]", "cookieuno");

// imprimirlas luego que la página es recargada
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[
tres : cookietres
dos : cookiedos
uno : cookieuno
]]>
    </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>5.5.0</entry>
       <entry>
        Ahora se incluye un atribugo 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>
  <note>
   <para>
    Si la directiva de PHP <link linkend="ini.register-globals">register_globals</link>
    está en <literal>on</literal> los valores de las cookies también serán convertidos
    en variables. En el ejemplo de más abajo,<varname>$TestCookie</varname> existirá.
    Se recomienda simplemente utilizar <varname>$_COOKIE</varname>.
   </para>
  </note>
  <para>
   Trampas habituales:
   <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>expire</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">sección sobre cookies</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
-->