archived-doc-pt-br/reference/network/functions/setcookie.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 6122a8317ca0068fc71f6a5167e0a2d99166ec7c Maintainer: leonardolara Status: ready --><!-- CREDITS: adiel,thiago,ae,leonardolara -->
<refentry xml:id="function.setcookie" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>setcookie</refname>
  <refpurpose>Envia um 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>Assinatura alternativa disponível a partir do PHP 7.3.0 (sem suporte a parâmetros nomeados):</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>
   A função <function>setcookie</function> define um cookie para ser enviado juntamente
   com os cabeçalhos HTTP. Como outros cabeçalhos, os cookies devem ser enviados
   <emphasis>antes</emphasis> de qualquer saída do script (isso é
   uma restrição do protocolo). Isso requer que esta função seja chamada antes de qualquer
   saída, incluindo as tags <literal>&lt;html&gt;</literal> e
   <literal>&lt;head&gt;</literal>, assim como espaços em branco.
  </simpara>
  <simpara>
   Uma vez que os cookies foram definidos, eles podem ser acessados no próximo carregamento da página
   através do array <varname>$_COOKIE</varname>.
   Os valores dos cookies também podem existir no
   array <varname>$_REQUEST</varname>.
  </simpara>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   A <link xlink:href="&url.rfc;6265">RFC 6265</link> fornece a referência
   normativa de como cada parâmetro de <function>setcookie</function>
   é interpretado.
   <variablelist>
    <varlistentry>
     <term><parameter>name</parameter></term>
     <listitem>
      <simpara>
       O nome do cookie.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>value</parameter></term>
     <listitem>
      <simpara>
       O valor do cookie. Esse valor é armazenado no computador do cliente; não
       deve ser armazenada informação sensível. Supondo que o <parameter>name</parameter> seja
       <literal>'cookiename'</literal>, o valor pode ser lido através de
       <varname>$_COOKIE['cookiename']</varname>
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>expires_or_options</parameter></term>
     <listitem>
      <simpara>
       O tempo para o cookie expirar. Esse valor é um timestamp Unix,
       portanto é o número de segundos desde a época Unix.
       Uma maneira de configurar esse valor é adicionando o número de segundos em que o cookie deve
       durar antes de expirar ao resultado da função <function>time</function>.
       Por exemplo, <literal>time()+60*60*24*30</literal> irá configurar o cookie
       para expirar em 30 dias.
       Outra opção é usar a função <function>mktime</function>.
       Se configurado para <literal>0</literal> ou omitido, o cookie vai expirar
       no final da sessão (quando o navegador fechar).
      </simpara>
      <note>
       <simpara>
        O parâmetro <parameter>expires_or_options</parameter> recebe
        um timestamp Unix, ao contrário do formato de data <literal>Wdy, DD-Mon-YYYY
        HH:MM:SS GMT</literal>, isso acontece porque o PHP faz essa conversão
        internamente.
       </simpara>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>path</parameter></term>
     <listitem>
      <simpara>
       O caminho no servidor onde o cookie estará disponível. Se configurado
       para <literal>'/'</literal>, o cookie estará disponível para todo o
       <parameter>domain</parameter>. Se configurado para o diretório
       <literal>'/foo/'</literal>, o cookie estará disponível apenas dentro do
       diretório <literal>/foo/</literal> e todos os subdiretórios como
       <literal>/foo/bar/</literal> do <parameter>domain</parameter>.
       O valor padrão é o
       diretório atual onde o cookie está sendo configurado.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>domain</parameter></term>
     <listitem>
      <simpara>
       O (sub)domínio para qual o cookie estará disponível. Definindo para um
       subdomínio (como <literal>'www.example.com'</literal>) deixará o cookie
       disponível para aquele subdomínio e todos os outros sub-domínios abaixo dele
       (exemplo w2.www.example.com). Para deixar o cookie disponível para todo o
       domínio (incluindo todos os subdomínios dele), basta definir o valor
       para o nome do domínio (<literal>'example.com'</literal>, nesse caso).
      </simpara>
      <simpara>
       Navegadores antigos ainda implementam a
       <link xlink:href="&url.rfc;2109">RFC 2109</link> e podem requerer um
       <literal>.</literal> no início para funcionar com todos os subdomínios.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>secure</parameter></term>
     <listitem>
      <simpara>
       Indica que o cookie só poderá ser transmitido sob uma conexão
       segura HTTPS do cliente. Quando configurado para &true;, o
       cookie será enviado somente se uma conexão segura existir.
       No lado do servidor, fica por conta do programador enviar esse
       tipo de cookie somente sob uma conexão segura (ex
       respeitando <varname>$_SERVER["HTTPS"]</varname>).
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>httponly</parameter></term>
     <listitem>
      <simpara>
       Quando for &true;, o cookie será acessível somente sob o protocolo HTTP.
       Isso significa que o cookie não será acessível por linguagens de
       script, como JavaScript. É dito que essa configuração pode ajudar a
       reduzir ou identificar roubos de identidade através de ataques do tipo XSS
       (entretanto ela não é suportada por todos os navegadores), mas essa informação
       é constantemente discutida. Foi adicionada no PHP 5.2.0.
       &true; ou &false;
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <simpara>
       Um <type>array</type> associativo que pode ter qualquer uma das chaves
       <literal>expires</literal>, <literal>path</literal>, <literal>domain</literal>,
       <literal>secure</literal>, <literal>httponly</literal> e <literal>samesite</literal>.
      </simpara>
      <simpara>
       Os valores têm o mesmo efeito como descrito para os
       parâmetros de mesmo nome. O valor do elemento <literal>samesite</literal>
       deve ser <literal>None</literal>, <literal>Lax</literal>
       ou <literal>Strict</literal>.
       Se uma das opções não for informada, os valores padrão serão os
       mesmos valores padrão dos parâmetros explícitos. Se
       <literal>samesite</literal> for omitido, o atributo SameSite do cookie
       não será atribuído.
      </simpara>

      <note>
       <simpara>
        Para definir um cookie que inclui atributos que não estão entre as chaves listadas,
        use a função <function>header</function>.
       </simpara>
      </note>
      <note>
       <simpara>
        Se <literal>samesite</literal> for igual a <literal>"None"</literal> então
        <literal>secure</literal> também precisa ser habilitado senão o cookie será
        bloqueado pelo cliente.
       </simpara>
      </note>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <simpara>
   Se houver saída antes da chamada dessa função,
   <function>setcookie</function> irá falhar e retornará &false;. Se a função
   <function>setcookie</function> for executada com sucesso, ela retornará &true;.
   Isso não indica que o usuário aceitou o cookie.
  </simpara>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simpara>
   Se o array <parameter>options</parameter> contiver chaves não suportadas:
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     Antes do PHP 8.0.0, era gerado um <constant>E_WARNING</constant>.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     A partir do PHP 8.0.0, é lançado um <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>
       O formato de data do cookie agora é <literal>'D, d M Y H:i:s \G\M\T'</literal>;
       anteriormente era <literal>'D, d-M-Y H:i:s T'</literal>.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       Passar chaves não suportadas agora lança um <exceptionname>ValueError</exceptionname>
       em vez de emitir um <constant>E_WARNING</constant>.
      </entry>
     </row>
     <row>
      <entry>7.3.0</entry>
      <entry>
       Uma assinatura alternativa para suportar o array <parameter>options</parameter>
       foi adicionado. Essa assinatura também permite configurar o atributo
       SameSite do cookie.
      </entry>
     </row>

    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <simpara>
   Os efeitos dos exemplos a seguir podem ser observados usando a lista de cookies
   da ferramenta de desenvolvedor do navegador (normalmente na aba de Armazenamento ou Aplicação).
  </simpara>
  <example>
   <title>Exemplo de <function>setcookie</function> para enviar cookies</title>
   <programlisting role="php">
<![CDATA[
<?php

$value = 'alguma coisa de algum lugar';

// Define um "cookie de sessão" que expira quando o navegador é fechado
setcookie("CookieTeste", $value);
// Define um cookie que expira em 1 hora
setcookie("CookieTeste", $value, time()+3600);
// Define um cookie que se aplica somente a um caminho específico de um domnínio específico
// Observe que o domínio usado deve corresponder ao domínio do site
setcookie("CookieTeste", $value, time()+3600, "/~rasmus/", "example.com", true);

?>
]]>
   </programlisting>
  </example>
  <simpara>
   Observe que a porção do valor do cookie será automaticamente codificada em
   URL e decodificada pelo PHP. Isto pode ser evitado usando
   <function>setrawcookie</function> em seu lugar.
  </simpara>
  <simpara>
   Para ver o conteúdo dos cookies definidos no exemplo acima em uma requisição
   posterior:
  </simpara>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
// Mostra um cookie individual
echo $_COOKIE["CookieTeste"];

// Outra maneira de depurar/testar é vendo todos os cookies
print_r($_COOKIE);
?>
]]>
   </programlisting>
  </informalexample>
  <example>
   <title>Exemplo de <function>setcookie</function> para apagar cookies</title>
   <simpara>
    Para excluir um cookie, defina a data de expiração para uma data no passado
    (porém diferente de zero, que é reservado para cookies de sessão).
   </simpara>
   <simpara>
    Para excluir os cookies definidos no exemplo anterior:
   </simpara>
   <programlisting role="php">
<![CDATA[
<?php
// Configura a data de expiração para uma hora atrás
setcookie("CookieTeste", "", time() - 3600);
setcookie("CookieTeste", "", time() - 3600, "/~rasmus/", ".example.com", 1);
?>
]]>
   </programlisting>
  </example>
  <example>
   <title><function>setcookie</function> e arrays</title>
   <simpara>
    "Arrays de cookies" podem ser definidos usando a notação de array
    no nome do cookie. Isso tem o efeito de definir tantos cookies quantos
    elementos houver no array, mas quando o cookie for recebido pelo
    script, os valores serão todos colocados em um array com o nome do
    cookie:
   </simpara>
   <programlisting role="php">
<![CDATA[
<?php
// define os cookies
setcookie("cookie[tres]", "cookietres");
setcookie("cookie[dois]", "cookiedois");
setcookie("cookie[um]", "cookieum");

// Exibe os cookies depois que a página recarregar
if (isset($_COOKIE['cookie'])) {
    foreach ($_COOKIE['cookie'] as $nome => $valor) {
        $nome = htmlspecialchars($nome);
        $valor = htmlspecialchars($valor);
        echo "$nome : $valor <br />\n";
    }
}
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
tres : cookietres
dois : cookiedois
um : cookieum
]]>
   </screen>
  </example>
  <note>
   <simpara>
    Utilizar caracteres como <literal>[</literal> e <literal>]</literal>
    no nome do cookie não é válido conforme a RFC 6265, seção 4, mas deve
    ser suportado por navegadores conforme a RFC 6265, seção 5.
   </simpara>
  </note>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <simpara>
    Buffer de saída pode ser usado para permitir saída do script antes de
    chamar essa função. Toda a saída será armazenada em buffer até que seja enviada
    (explicitamente ou ao final da execução do script). Isso é feito
    chamando <function>ob_start</function> e
    <function>ob_end_flush</function> no script, ou configurando a
    diretiva <literal>output_buffering</literal> no
    &php.ini; ou nos arquivos de configuração do servidor.
   </simpara>
  </note>
  <para>
   Problemas comuns:
   <itemizedlist>
    <listitem>
     <simpara>
      Os cookies não estarão disponíveis até o próximo carregamento da página
      para a qual o cookie deverá estar visível. Para testar se um cookie foi
      enviado com sucesso, deve ser verificado o cookie no próximo carregamento da
      página antes que ele expire. O tempo para expirar é configurado pelo
      parâmetro <parameter>expires_or_options</parameter>. Uma boa maneira de depurar a
      existência dos cookies é chamando a função <literal>print_r($_COOKIE);</literal>.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Os cookies devem ser excluídos com os mesmos parâmetros com os quais
      foram configurados. Se o argumento <parameter>value</parameter> for uma string vazia,
      e todos os outros argumentos forem iguais à chamada anterior de <function>setcookie</function>,
      o cookie com o nome especificado será excluído do cliente remoto.
      Internamente, isso é feito colocando o valor do cookie para <literal>'deleted'</literal> e a
      data de expiração para um ano no passado.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Quando um cookie for configurado com o valor &false;, será realizada uma tentativa de excluí-lo.
      Por isso, valores booleanos não devem ser usados. No lugar deles, utilize <emphasis>0</emphasis> para &false;
      e <emphasis>1</emphasis> para &true;.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Nomes de cookies podem ser definidos como nomes de arrays e estarão disponíves para
      os scripts PHP como arrays, mas cookies separados serão armazenados pelo navegador.
      Considere utilizar <function>json_encode</function> para definir um cookie com nomes e
      valores múltiplos. Não é recomendado usar <function>serialize</function>
      para esse propósito pois pode resultar em furos de segurança.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <simpara>
   Várias chamadas para a função <function>setcookie</function> são feitas na ordem em que são chamadas.
  </simpara>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><function>header</function></member>
   <member><function>setrawcookie</function></member>
   <member><link linkend="features.cookies">Seção de 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>
 </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
-->