variables.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 22583751fbfdaa3eaa41aeb6470d1343f5cb2c78 Maintainer: leonardolara Status: ready --><!-- CREDITS: ae,felipe,fabioluciano,adiel,gabrielsanva,leonardolara -->
 <chapter xml:id="language.variables" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Variáveis</title>

  <sect1 xml:id="language.variables.basics">
   <title>Básico</title>

   <simpara>
    As variáveis no PHP são representadas por um cifrão ($) seguido pelo
    nome da variável. Os nomes de variável são sensíveis a maiúsculas e minúsculas.
   </simpara>

   <para>
    Um nome válido de variável inicia com uma letra
    (<literal>A-Z</literal>, <literal>a-z</literal>, ou os bytes de 128 a 255)
    ou sublinhado, seguido
    de qualquer número de letras, números ou sublinhados. Em uma
    expressão regular, poderia ser representado assim:
    <code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>
   </para>

   <note>
    <simpara>
     O PHP não suporta nomes de variáveis em Unicode, porém, algumas codificações
     de caracteres (tal como UTF-8) codificam os caracteres de uma forma que todos os bytes
     de um caractere multi-byte fiquem dentro da faixa permitida, fazendo com que
     o nome da variável seja válido.
    </simpara>
   </note>

   <note>
    <simpara>
     <literal>$this</literal> é uma variável especial que não pode ser
     atribuída.
     Antes do PHP 7.1.0, atribuição indireta (por exemplo, usando
     <link linkend="language.variables.variable">variáveis variáveis</link>)
     era possível.
    </simpara>
   </note>

   &tip.userlandnaming;

   <example>
    <title>Nomes de variáveis válidos</title>
    <programlisting role="php">
<![CDATA[
<?php
$var = 'Bob';
$Var = 'Joe';
echo "$var, $Var";      // exibe "Bob, Joe"

$_4site = 'not yet';    // válido; começa com um sublinhado
$täyte = 'mansikka';    // válido; 'ä' é um caracter ASCII (extendido) 228
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Nomes de variáveis inválidos</title>
    <programlisting role="php">
<![CDATA[
<?php
$4site = 'not yet';     // inválido; começa com um número
]]>
    </programlisting>
   </example>

   <simpara>
    O PHP aceita uma sequência de quaisquer bytes como um nome de variável. Nomes
    de variáveis que não seguem as regras de nomenclatura mencionadas acima só podem ser
    acessadas dinamicamente no momento da execução. Consulte a seção sobre
    <link linkend="language.variables.variable">variáveis variáveis</link>
    para informação sobre como acessá-las.
   </simpara>

   <example>
    <title>Acessando nomes obscuros de variáveis</title>
    <programlisting role="php">
<![CDATA[
<?php
${'invalid-name'} = 'bar';
$name = 'invalid-name';
echo ${'invalid-name'}, " ", $$name;
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
bar bar
]]>
    </screen>
   </example>

   <para>
    Por padrão, as variáveis são sempre atribuídas por valor. Isto significa
    que ao atribuir uma expressão a uma variável, o valor
    da expressão original é copiado integralmente para a variável de
    destino. Isto significa também que, após atribuir o valor de uma variável a
    outra, a alteração de uma destas variáveis
    não afetará a outra. Para maiores informações sobre este tipo de
    atribuição, veja o capítulo em <link
    linkend="language.expressions">Expressões</link>.
   </para>
   <para>
    O PHP também oferece um outro meio de atribuir valores a variáveis:
    <link linkend="language.references">atribuição por referência</link>.
    Isto significa que a nova variável simplesmente referencia (em outras palavras,
    "torna-se um apelido para" ou "aponta para") a variável original.
    Alterações na nova variável afetam a original, e vice-versa.
   </para>
   <para>
    Para atribuir por referência, simplesmente adicione um e-comercial (&amp;)
    na frente do nome da variável que estiver sendo atribuída (variável
    de origem). Por exemplo, o trecho de código abaixo exibe '<literal>My
    name is Bob</literal>' duas vezes:

    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
$foo = 'Bob';              // Atribui o valor 'Bob' a variável $foo
$bar = &$foo;              // Referecia $foo através de $bar.
$bar = "My name is $bar";  // Altera $bar...
echo $bar;
echo $foo;                 // $foo é alterada também.
?>
]]>
     </programlisting>
    </informalexample>
   </para>

   <para>
    Uma observação importante a se fazer, é que somente variáveis
    podem ser atribuídas por referência.
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
$foo = 25;
$bar = &$foo;      // Esta atribuição é válida.
$bar = &(24 * 7);  // Inválido; referencia uma expressão sem nome.

function test()
{
   return 25;
}

$bar = &test();    // Inválido porque test() não retorna uma variável por referência.
?>
]]>
     </programlisting>
    </informalexample>
   </para>

   <para>
    Não é necessário declarar variáveis no PHP, contudo é uma ótima
    prática. Acessar uma variável indefinida resultará em um
    <constant>E_WARNING</constant> (antes do PHP 8.0.0, <constant>E_NOTICE</constant>).
    Uma variável indefinida tem um valor padrão de &null;.
    O construtor de linguagem <function>isset</function>
    pode ser usado para detectar se uma variável já foi inicializada.
   </para>
   <para>
    <example>
     <title>Valor padrão de uma variável não inicializada</title>
     <programlisting role="php">
<![CDATA[
<?php
// Variável não definida E não referenciada (sem contexto de uso);
var_dump($unset_var);
?>
]]>
     </programlisting>
     &example.outputs;
     <screen>
<![CDATA[
Warning: Undefined variable $unset_var in ...
NULL
]]>
     </screen>
    </example>
   </para>

   <simpara>
    O PHP permite autovivificação de array (criação automática de novos arrays)
    a partir de uma variável indefinida.
    Anexar um elemento a uma variável indefinida criará um novo array e
    não gerará um alerta.
   </simpara>
   <example>
    <title>Autovivificação de um array a partir de uma variável indefinida</title>
    <programlisting role="php">
<![CDATA[
<?php
$unset_array[] = 'value'; // Não gera um alerta.
?>
]]>
    </programlisting>
   </example>

   <warning>
    <simpara>
     Depender do valor padrão de uma variável não inicializada é problemático
     ao incluir um arquivo em outro que usa o mesmo
     nome de variável.
    </simpara>
   </warning>

   <simpara>
    Uma variável pode ser destruída usando o construtor de linguagem
    <function>unset</function>.
   </simpara>

   <simpara>
    Para obter informações sobre funções relacionadas a variáveis, consulte a
    <link linkend="ref.var">Referência de funções variáveis</link>.
   </simpara>
  </sect1>

  <sect1 xml:id="language.variables.predefined">
   <title>Variáveis Predefinidas</title>

   <para>
    O PHP fornece um número de
    <link linkend="reserved.variables">variáveis predefinidas</link>.
    O PHP também fornece um conjunto adicional de arrays predefinidos
    contendo as variáveis do servidor web (se aplicável), as
    variáveis de ambiente e as entradas do usuário. Esses estão automaticamente disponíveis em
    qualquer escopo. Por essa razão, também são conhecidos como
    "superglobais" (não há um mecanismo no PHP para
    superglobais definidos pelo usuário). Consulte a
    <link linkend="language.variables.superglobals">lista de superglobais</link>
    para mais detalhes.
   </para>

   <note>
    <title>Variáveis variáveis</title>
    <para>
     Superglobais não podem ser utilizadas como
     <link linkend="language.variables.variable">variáveis variáveis</link>
     dentro de funções ou métodos de classe.
    </para>
   </note>

   <para>
    Se determinadas variáveis não estiverem definidas na diretiva <link
    linkend="ini.variables-order">variables_order</link>, seus
    arrays predefinidos também estarão vazios.
   </para>
  </sect1>


  <sect1 xml:id="language.variables.scope">
   <title>Escopo de variáveis</title>

   <simpara>
    O escopo de uma variável é o contexto onde ela está definida.
    O PHP tem um escopo de função e um escopo global.
    Qualquer variável definida fora de uma função está limitada ao escopo global.
    Quando um arquivo é incluído, o código que ele contém herda o escopo da variável
    da linha na qual a inclusão ocorre.
   </simpara>
   <example>
    <title>Exemplo de escopo global de variável</title>
    <programlisting role="php">
<![CDATA[
<?php
$a = 1;
include 'b.inc'; // Variável $a estará disponível dentro de b.inc
?>
]]>
    </programlisting>
   </example>

   <simpara>
    Qualquer variável criada dentro de uma função nomeada ou de
    uma função <link linkend="functions.anonymous">anônima</link>
    é limitada ao escopo do corpo da função.
    Entretanto, <link linkend="functions.arrow">funções de seta</link>
    vinculam variáveis ​​do escopo pai para disponibilizá-las dentro do corpo.
    Se uma inclusão de arquivo ocorrer dentro de uma função dentro
    do arquivo chamador, as variáveis ​​contidas no arquivo chamado estarão
    disponíveis como se tivessem sido definidas dentro da função chamadora.
   </simpara>

   <example>
    <title>Exemplo de escopo local de variável</title>
    <programlisting role="php">
<![CDATA[
<?php
$a = 1; // escopo global

function test()
{
    echo $a; // Variável $a é indefinida já que refere-se a uma versão local de $a
}
?>
]]>
    </programlisting>
   </example>

   <simpara>
    O exemplo acima irá gerar um <constant>E_WARNING</constant> de variável indefinida
    (ou um <constant>E_NOTICE</constant> antes do PHP 8.0.0).
    Isto acontece porque a instrução echo
    refere-se a uma versão local da variável <varname>$a</varname>,
    e não possui nenhum valor atribuído neste escopo. Pode-se
    perceber que esta é uma pequena diferença em relação à linguagem C, em que
    variáveis globais estão automaticamente disponíveis para
    funções a menos que tenham sido substituídas por uma definição local.
    Isto pode causar problemas quando uma variável
    global for inadvertidamente modificada. No PHP, as variáveis globais precisam ser
    declaradas como globais dentro de uma função, se elas precisarem ser utilizadas
    na função.
   </simpara>

   <sect2 xml:id="language.variables.scope.global">
    <title>A palavra-chave <literal>global</literal></title>
    <simpara>
     A palavra-chave <literal>global</literal> é usada para vincular uma variável
     de um escopo global a um escopo local. A palavra-chave pode ser usada com
     uma lista de variáveis ​​ou com uma única variável. Uma variável local será criada
     referenciando a variável global de mesmo nome. Se a variável global
     não existir, a variável será criada no escopo global e
     receberá o valor &null;.
    </simpara>
    <para>
     <example>
      <title>Usando <literal>global</literal></title>
      <programlisting role="php">
<![CDATA[
<?php
$a = 1;
$b = 2;

function Soma()
{
    global $a, $b;

    $b = $a + $b;
}

Soma();
echo $b;
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
3
]]>
      </screen>
     </example>
    </para>

   <simpara>
    Declarar
    <varname>$a</varname> e <varname>$b</varname> como globais na
    função fará com que todas as referências a essas variáveis refiram-se às
    versões globais. Não há um limite para o número de variáveis
    globais que podem ser manipuladas por uma função.
   </simpara>

   <simpara>
    Uma segunda maneira de acessar variáveis do escopo global é utilizando
    o array especial <varname>$GLOBALS</varname> definido pelo PHP. O
    exemplo anterior poderia ser reescrito como:
   </simpara>
   <para>
    <example>
     <title>Usando <varname>$GLOBALS</varname> no lugar de global</title>
     <programlisting role="php">
<![CDATA[
<?php
$a = 1;
$b = 2;

function Soma()
{
    $GLOBALS['b'] = $GLOBALS['a'] + $GLOBALS['b'];
}

Soma();
echo $b;
?>
]]>
     </programlisting>
    </example>
   </para>

   <simpara>
    O array <varname>$GLOBALS</varname> é um array associativo, com
    o nome da variável global na chave e o conteúdo dessa
    variável no valor do elemento do array.
    Veja que <varname>$GLOBALS</varname> existe em qualquer escopo, isto
    porque <varname>$GLOBALS</varname> é uma <link
    linkend="language.variables.superglobals">superglobal</link>.
    Eis um exemplo demonstrando o poder das superglobais:
   </simpara>
   <para>
    <example>
     <title>Exemplo demonstrando superglobals e escopos</title>
     <programlisting role="php">
<![CDATA[
<?php
function test_superglobal()
{
    echo $_POST['name'];
}
?>
]]>
     </programlisting>
    </example>
   </para>
   <note>
    <simpara>
     Utilizar a instrução <literal>global</literal> fora de uma função não é
     um erro. Pode ser utilizado se o arquivo for incluído de dentro de uma função.
    </simpara>
   </note>
  </sect2>

  <sect2 xml:id="language.variables.scope.static">
   <title>Utilizando variáveis <literal>static</literal></title>
   <simpara>
    Outro recurso importante do escopo de variáveis é a
    variável <emphasis>estática</emphasis>. Uma variável estática existe
    somente no escopo local da função, mas não perde seu valor
    quando a execução do programa deixa o escopo. Considere o seguinte
    exemplo:
   </simpara>
   <para>
    <example>
     <title>Exemplo demonstrando a necessidade de variáveis estáticas</title>
     <programlisting role="php">
<![CDATA[
<?php
function Teste()
{
    $a = 0;
    echo $a;
    $a++;
}
?>
]]>
     </programlisting>
    </example>
   </para>
   <simpara>
    Essa função é inútil, já que cada vez que é chamada, define
    <varname>$a</varname> com o valor <literal>0</literal>, e exibe
    <literal>0</literal>. A instrução <varname>$a</varname>++ , que aumenta o valor da
    variável, não tem sentido já que assim que a função termina, a
    variável <varname>$a</varname> desaparece. Para fazer um função
    de contagem útil, que não perderá a contagem atual,
    a variável <varname>$a</varname> será declarada como estática:
   </simpara>
   <para>
    <example>
     <title>Exemplo de uso de variáveis estáticas</title>
     <programlisting role="php">
<![CDATA[
<?php
function Teste()
{
    static $a = 0;
    echo $a;
    $a++;
}
?>
]]>
     </programlisting>
    </example>
   </para>
   <simpara>
    Agora, a variável <varname>$a</varname> é inicializada apenas na primeira chamada da função
    e cada vez que a função <literal>test()</literal> for chamada, exibirá o
    valor de <varname>$a</varname> e depois o incrementará.
   </simpara>

   <simpara>
    Variáveis estáticas fornecem uma solução para lidar com funções
    recursivas. A seguinte
    função recursiva conta até 10, utilizando a variável
    estática <varname>$count</varname> para saber quando parar:
   </simpara>
   <para>
    <example>
     <title>Variáveis estáticas em funções recursivas</title>
     <programlisting role="php">
<![CDATA[
<?php
function Teste()
{
    static $count = 0;

    $count++;
    echo $count;
    if ($count < 10) {
        Teste();
    }
    $count--;
}
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    Antes do PHP 8.3.0, variáveis estáticas somente poderiam ser inicializadas usando
    uma expressão constante. A partir do PHP 8.3.0, expressões dinâmicas
    (por exemplos, chamadas de funções) também são permitidas:
   </para>
   <para>
    <example>
     <title>Declarando variáveis estáticas</title>
     <programlisting role="php">
<![CDATA[
<?php
function foo(){
    static $int = 0;          // correto
    static $int = 1+2;        // correto
    static $int = sqrt(121);  // correto a partir do PHP 8.3

    $int++;
    echo $int;
}
?>
]]>
     </programlisting>
    </example>
   </para>

   <simpara>
    Variáveis ​​estáticas dentro de funções anônimas persistem apenas dentro daquela
    instância de função específica. Se a função anônima for recriada em cada
    chamada, a variável estática será reinicializada.
   </simpara>
   <example>
    <title>Variáveis ​​estáticas em funções anônimas</title>
    <programlisting role="php">
<![CDATA[
<?php
function funcaoExemplo($input) {
    $result = (static function () use ($input) {
        static $counter = 0;
        $counter++;
        return "Entrada: $input, Contador: $counter\n";
    });

    return $result();
}

// Chamadas a funcaoExemplo irão recriar a função anônima, de forma que a variável
// estática não reterá seu valor.
echo funcaoExemplo('A'); // Exibe: Entrada: A, Contador: 1
echo funcaoExemplo('B'); // Exibe: Entrada: B, Contador: 1
?>
]]>
    </programlisting>
   </example>

   <para>
    A partir do PHP 8.1.0, quando um método com variáveis estáticas é herdado (mas não sobrescrito),
    o método herdado não compartilhará as variáveis estáticas do método acima.
    Isso significa que variáveis estáticas nos métodos agora se comportam da mesma forma que propriedades estáticas.
   </para>

   <simpara>
    A partir do PHP 8.3.0, variáveis estáticas podem ser inicializadas com expressões arbitrárias.
    Isto significa que chamadas de métodos, por exemplo, podem ser usadas para iniciá-las.
   </simpara>

   <example>
    <title>Uso de variáveis estáticas em métodos herdados</title>
    <programlisting role="php">
<![CDATA[
<?php
class Foo {
    public static function counter() {
        static $counter = 0;
        $counter++;
        return $counter;
    }
}
class Bar extends Foo {}
var_dump(Foo::counter()); // int(1)
var_dump(Foo::counter()); // int(2)
var_dump(Bar::counter()); // int(3), e antes do PHP 8.1.0 int(1)
var_dump(Bar::counter()); // int(4), e antes do PHP 8.1.0 int(2)
?>
]]>
    </programlisting>
   </example>
  </sect2>

  <sect2 xml:id="language.variables.scope.references">
   <title>Referências em variáveis <literal>global</literal> e <literal>static</literal></title>
   <simpara>
    O PHP implementa os modificadores
    <link linkend="language.variables.scope.static">static</link> e
    <link linkend="language.variables.scope.global">global</link>
    para variáveis, em termo de <link linkend="language.references">
    referências</link>. Por exemplo, uma variável global verdadeira,
    importada dentro do escopo de uma função com a instrução <literal>global</literal>,
    na verdade, cria uma referência para a variável global. Isto pode levar a
    comportamentos imprevisíveis nos seguintes casos:
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
function test_global_ref() {
    global $obj;
    $new = new stdClass;
    $obj = &$new;
}

function test_global_noref() {
    global $obj;
    $new = new stdClass;
    $obj = $new;
}

test_global_ref();
var_dump($obj);
test_global_noref();
var_dump($obj);
?>
]]>
    </programlisting>
   </informalexample>

   &example.outputs;

   <screen>
<![CDATA[
NULL
object(stdClass)#1 (0) {
}
]]>
   </screen>

   <simpara>
    Um comportamento similar se aplica à declaração <literal>static</literal>.
    Referências não são armazenadas estaticamente:
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
function &get_instance_ref() {
    static $obj;

    echo 'Objeto estático: ';
    var_dump($obj);
    if (!isset($obj)) {
        $new = new stdClass;
        // Atribui uma referencia à variável estática
        $obj = &$new;
    }
    if (!isset($obj->property)) {
        $obj->property = 1;
    } else {
        $obj->property++;
    }
    return $obj;
}

function &get_instance_noref() {
    static $obj;

    echo "Objeto estático: ";
    var_dump($obj);
    if (!isset($obj)) {
        $new = new stdClass;
        // Atribui o objeto à variável estática
        $obj = $new;
    }
    if (!isset($obj->property)) {
        $obj->property = 1;
    } else {
        $obj->property++;
    }
    return $obj;
}

$obj1 = get_instance_ref();
$still_obj1 = get_instance_ref();
echo "\n";
$obj2 = get_instance_noref();
$still_obj2 = get_instance_noref();
?>
]]>
    </programlisting>
   </informalexample>
   &example.outputs;
   <screen>
<![CDATA[
Objeto estático: NULL
Objeto estático: NULL

Objeto estático: NULL
Objeto estático: object(stdClass)#3 (1) {
  ["property"]=>
  int(1)
}
]]>
   </screen>

   <simpara>
    Este exemplo demonstra que ao atribuir uma referência a uma variável
    estática, ela não será <emphasis>lembrada</emphasis> quando a função
    <literal>&amp;get_instance_ref()</literal> for chamada uma segunda vez.
   </simpara>
   </sect2>
  </sect1>

  <sect1 xml:id="language.variables.variable">
   <title>Variáveis variáveis</title>

   <simpara>
    As vezes, é conveniente possuir nome variáveis para
    variáveis. Isto é, o nome de uma variável que pode ser definido e utilizado
    dinamicamente. Uma variável normal é definida com uma instrução como:
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
$a = 'hello';
?>
]]>
    </programlisting>
   </informalexample>

   <simpara>
    Uma variável variável obtém o valor de uma variável e a trata como
    o nome de uma variável. No exemplo acima,
    <emphasis>hello</emphasis> pode ser utilizado como o nome de uma variável
    utilizando dois sinais de cifrão:
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
$$a = "world";
?>
]]>
    </programlisting>
   </informalexample>

   <simpara>
    Neste ponto, duas variáveis foram definidas e armazenadas na
    árvore de símbolos do PHP: <varname>$a</varname> que contém "hello" e
    <varname>$hello</varname> que contém "world". Assim, esta
    instrução:
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
echo "$a {$$a}";
?>
]]>
    </programlisting>
   </informalexample>

   <simpara>
    produz a mesma saída que:
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
echo "$a $hello";
?>
]]>
    </programlisting>
   </informalexample>

   <simpara>
    assim sendo, as duas produzem: <computeroutput>hello world</computeroutput>.
   </simpara>

   <simpara>
    Para poder utilizar variáveis variáveis com arrays, é necessário
    resolver um problema de ambiguidade. Isso é, se for escrito
    <varname>$$a[1]</varname>, o interpretador precisa saber se a
    intenção é utilizar <varname>$a[1]</varname> como uma variável ou se
    a intenção é usar <varname>$$a</varname> como uma variável e <literal>[1]</literal>
    como o índice dessa variável. A sintaxe para resolver essa ambiguidade
    é <varname>${$a[1]}</varname> para o primeiro caso e
    <varname>${$a}[1]</varname> para o segundo.
   </simpara>

   <simpara>
    Propriedades de classes também podem ser acessadas utilizando-se nomes de propriedades variáveis. O
    nome de propriedade variável será resolvido dentro do escopo em que a
    chamada foi feita. Por exemplo, se houver uma expressão como
    <varname>$foo->$bar</varname>, o escopo local será examinado procurando por
    <varname>$bar</varname> e seu valor será utilizado como o nome da
    propriedade <varname>$foo</varname>. Isso também funciona se
    <varname>$bar</varname> for um array.
   </simpara>

   <simpara>
    Chaves também podem ser utilizadas para delimitar claramente os nomes
    de propriedade. São muito úteis ao acessar valores de uma propriedade que
    contenham um array, quando o nome da propriedade tem várias partes,
    ou quando o nome da propriedade contém caracteres que não
    são válidos (por exemplo, em saídas da função <function>json_decode</function>
    ou <link linkend="book.simplexml">SimpleXML</link>).
   </simpara>

   <para>
    <example>
     <title>Exemplo de propriedade variável</title>
      <programlisting role="php">
<![CDATA[
<?php
class Foo {
    public $bar = 'Eu sou bar.';
    public $arr = ['Eu sou A.', 'Eu sou B.', 'Eu sou C.'];
    public $r   = 'Eu sou r.';
}

$foo = new Foo();
$bar = 'bar';
$baz = ['foo', 'bar', 'baz', 'quux'];
echo $foo->$bar . "\n";
echo $foo->{$baz[1]} . "\n";

$start = 'b';
$end   = 'ar';
echo $foo->{$start . $end} . "\n";

$arr = 'arr';
echo $foo->{$arr[1]} . "\n";
echo $foo->{$arr}[1] . "\n";

?>
]]>
     </programlisting>
     &example.outputs;
     <screen>
<![CDATA[
Eu sou bar.
Eu sou bar.
Eu sou bar.
Eu sou r.
Eu sou B.
]]>
     </screen>
    </example>
   </para>

   <warning>
    <simpara>
     Observe que variáveis variáveis não podem ser utilizadas nos
     <link linkend="language.variables.superglobals">arrays superglobais</link>
     dentro de funções ou métodos de classe. A variável <literal>$this</literal>
     também é uma variável especial que não pode ser referenciada dinamicamente.
    </simpara>
   </warning>

  </sect1>

  <sect1 xml:id="language.variables.external">
   <title>Variáveis de fontes externas</title>

   <sect2 xml:id="language.variables.external.form">
    <title>Formulários HTML (GET e POST)</title>

    <simpara>
     Quando um formulário é submetido para um script PHP, a informação deste
     formulário estará automaticamente disponível para o script. Há
     algumas maneiras de acessar estas informações, por exemplo:
    </simpara>

    <para>
     <example>
      <title>Um formulário HTML simples</title>
      <programlisting role="html">
<![CDATA[
<form action="foo.php" method="post">
    Nome:  <input type="text" name="username" /><br />
    Email: <input type="text" name="email" /><br />
    <input type="submit" name="submit" value="Me aperte!" />
</form>
]]>
      </programlisting>
     </example>
    </para>

    <para>
     Existem apenas duas formas de acessar dados de formulários HTML.
     Os métodos disponíveis atualmente são listadas a seguir:
    </para>

    <para>
     <example>
      <title>Acessando dados de um formulário HTML via POST</title>
      <programlisting role="php">
<![CDATA[
<?php
echo $_POST['username'];
echo $_REQUEST['username'];
?>
]]>
      </programlisting>
     </example>
    </para>

    <para>
     Utilizar um formulário GET é similar, exceto que será utilizada a variável
     predefinida GET em seu lugar. GET também se aplica à variável
     <literal>QUERY_STRING</literal> (a informação depois do '?' numa URL). Então,
     por exemplo, <literal>http://www.example.com/test.php?id=3</literal>
     contém os dados GET que estarão acessíveis com <varname>$_GET['id']</varname>.
     Veja também <varname>$_REQUEST</varname>.
    </para>

    <note>
     <para>
      Pontos e espaços em nomes de variáveis são convertidos para sublinhados. Por
      exemplo <literal>&lt;input name="a.b" /&gt;</literal> se tornará
      <literal>$_REQUEST["a_b"]</literal>.
     </para>
    </note>

    <simpara>
     O PHP também entende arrays no contexto de variáveis de formulário
     (veja essa <link linkend="faq.html">FAQ</link>). Pode-se,
     por exemplo, agrupar variáveis relacionadas, ou utilizar este
     recurso para obter valores de uma entrada de seleção múltipla. No exemplo
     abaixo, o formulário é enviado para si mesmo, e depois de submetido, os dados
     são mostrados:
    </simpara>

    <para>
     <example>
      <title>Variáveis de formulários mais complexos</title>
      <programlisting role="php">
<![CDATA[
<?php
if ($_POST) {
    echo '<pre>';
    echo htmlspecialchars(print_r($_POST, true));
    echo '</pre>';
}
?>
<form action="" method="post">
    Nome:  <input type="text" name="personal[name]" /><br />
    Email: <input type="text" name="personal[email]" /><br />
    Cerveja: <br />
    <select multiple name="beer[]">
        <option value="heineken">Heineken</option>
        <option value="stella">Stella Artois</option>
        <option value="av42">Double Rye Ipa</option>
    </select><br />
    <input type="submit" value="Enviar dados!" />
</form>
]]>
      </programlisting>
     </example>
    </para>

    <note>
     <simpara>
      Se um nome de variável externa se parece com sintaxe de array válida, as letras
      finais são silenciosamente ignoradas. Por exemplo, <literal>&lt;input name="foo[bar]baz"&gt;</literal>
      se torna <literal>$_REQUEST['foo']['bar']</literal>.
     </simpara>
    </note>

    <sect3 xml:id="language.variables.external.form.submit">
     <title>Nomes de variáveis SUBMIT IMAGE</title>

     <simpara>
      Ao submeter um formulário, é possível utilizar imagens em vez
      do botão de submissão padrão com uma tag do tipo:
     </simpara>

     <informalexample>
      <programlisting role="html">
<![CDATA[
<input type="image" src="image.gif" name="sub" />
]]>
      </programlisting>
     </informalexample>

     <simpara>
      Quando o usuário clicar em algum lugar da imagem, o formulário
      será transmitido para o servidor com duas variáveis
      adicionais, <varname>sub_x</varname> and <varname>sub_y</varname>.
      Elas contém as coordenadas do
      clique do usuário na imagem. Os mais experientes percebem que os
      nomes reais dessas variáveis enviadas ao navegador contêm um ponto
      ao invés de um sublinhado, mas o PHP converte o ponto para um
      sublinhado automaticamente.
     </simpara>
    </sect3>

   </sect2>

   <sect2 xml:id="language.variables.external.cookies">
    <title>Cookies HTTP</title>

    <simpara>
     O PHP suporta transparentemente cookies HTTP como os definidos pela <link
     xlink:href="&url.rfc;6265">RFC 6265</link>. Cookies são um
     mecanismo o armazenamento de dados no navegador,
     rastreando e identificando o retorno de usuários. Você pode definir cookies com
     a função <function>setcookie</function>. Cookies são parte do
     cabeçalho HTTP, então a função SetCookie precisa ser chamada antes
     de qualquer saída ser enviada ao navegador. Esta é a mesma restrição
     da função <function>header</function>. Dados de cookies
     estão disponíveis nos arrays de dados de cookies apropriados,
     como <varname>$_COOKIE</varname> e também em <varname>$_REQUEST</varname>.
     Veja o manual de <function>setcookie</function> para mais detalhes e
     exemplos.
    </simpara>

    <note>
     <simpara>
      A partir dos PHP 7.2.34, 7.3.23 e 7.4.11, respectivamente, os <emphasis>nomes</emphasis>
      dos cookies recebidos não são decodificados (a partir do formato URL) por razões de segurança.
     </simpara>
    </note>

    <simpara>
     Se a intenção for atribuir vários valores a uma única variável do cookie, deve-se
     atribuí-la como um array:
    </simpara>

    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
  setcookie("MyCookie[foo]", 'Testing 1', time()+3600);
  setcookie("MyCookie[bar]", 'Testing 2', time()+3600);
?>
]]>
     </programlisting>
    </informalexample>

    <simpara>
     Isso criará dois cookies separados embora <varname>MyCookie</varname> será
     agora um único array no script. Se a intenção for definir apenas um cookie
     com vários valores, pode-se utilizar <function>serialize</function> ou
     <function>explode</function> nos valores primeiro.
    </simpara>

    <simpara>
     Note que um cookie substituirá um anterior com o mesmo
     nome no navegador, a menos que o caminho ou o domínio seja diferente. Portanto,
     para uma aplicação de carrinho de compras, pode-se manter um contador
     e repassá-lo:
    </simpara>

    <example>
     <title>Um exemplo de <function>setcookie</function></title>
     <programlisting role="php">
<![CDATA[
<?php
if (isset($_COOKIE['count'])) {
    $count = $_COOKIE['count'] + 1;
} else {
    $count = 1;
}
setcookie('count', $count, time()+3600);
setcookie("Cart[$count]", $item, time()+3600);
?>
]]>
     </programlisting>
    </example>

   </sect2>

   <sect2 xml:id="language.variables.external.dot-in-names">
    <title>Pontos em nomes de variáveis recebidas</title>

    <para>
     Normalmente o PHP não altera o nome de variáveis quando elas
     são passadas para um script. Entretanto, deve ser notado que o
     ponto (ponto final) não é um caractere válido em nome de
     variável do PHP. Para ilustrar o motivo, veja o seguinte exemplo:
     <programlisting role="php">
<![CDATA[
<?php
$varname.ext;  /* nome de variável inválido */
?>
]]>
     </programlisting>
     Dessa forma, o interpretador entende isso como uma variável com nome de
     <varname>$varname</varname>, seguida do operador de concatenação
     de strings, seguida de uma string crua (uma string não delimitada que
     não bate com nenhuma palavra-chave ou reservada) 'ext'. Obviamente,
     isso não tem os resultados pretendidos.
    </para>

    <para>
     Nessa situação, é importante notar que o PHP
     substituirá automaticamente qualquer ponto nos nomes de variáveis recebidas por
     sublinhados.
    </para>

   </sect2>

   <sect2 xml:id="language.variables.determining-type-of">
    <title>Determinando o tipo das variáveis</title>

    <para>
     Como o PHP determina os tipos de variáveis e faz conversões
     (geralmente) quando necessário, nem sempre é óbvio o tipo de uma variável
     em cada momento. O PHP inclui várias funções
     que permitem determinar qual o tipo de uma variável, por exemplo:
     <function>gettype</function>, <function>is_array</function>,
     <function>is_float</function>, <function>is_int</function>,
     <function>is_object</function>,e
     <function>is_string</function>. Veja também o capítulo sobre
     <link linkend="language.types">Tipos</link>.
    </para>
    <para>
     Pelo fato do HTTP ser um protocolo de texto, a maioria, se não todo o conteúdo presente nos
     <link linkend="language.variables.superglobals">arrays superglobais</link>
     como <varname>$_POST</varname> e <varname>$_GET</varname> permanecerão
     como strings. O PHP não tentará converter valores para um tipo específico.
     No exemplo abaixo, <varname>$_GET["var1"]</varname> conterá a
     string "null" e <varname>$_GET["var2"]</varname> conterá a string "123".
     <programlisting>
<![CDATA[
/index.php?var1=null&var2=123
]]>
      </programlisting>
    </para>
   </sect2>

   <sect2 xml:id="language.variables.external.changelog">
    &reftitle.changelog;

    <para>
     <informaltable>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>&Version;</entry>
         <entry>&Description;</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>7.2.34, 7.3.23, 7.4.11</entry>
         <entry>
          Os <emphasis>nomes</emphasis> dos cookies recebidos não são mais decodificados (a partir do formato URL)
          por razões de segurança.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </informaltable>
    </para>
   </sect2>

  </sect1>

 </chapter>

<!-- 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
-->