functions.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: b8f3ae7da35b99b3137ff59aa5d86110dde607f4 Maintainer: leonardolara Status: ready --><!-- CREDITS: fabioluciano,ae,geekcom,lhsazevedo,leonardolara -->
 <chapter xml:id="language.functions" xmlns="http://docbook.org/ns/docbook">
  <title>Funções</title>

  <sect1 xml:id="functions.user-defined">
   <title>Funções definidas pelo usuário</title>

   <para>
    Uma função é definida pelo uso da palavra-chave <literal>function</literal>,
    um nome, uma lista de parâmetros (que pode estar vazia) separados por vírgulas
    (<literal>,</literal>) entre parênteses, seguidos pelo corpo da
    função entre chaves, como a seguir:
   </para>
   <example>
    <title>Declarando uma nova função chamada <literal>foo</literal></title>
    <programlisting role="php">
<![CDATA[
<?php
function foo($arg_1, $arg_2, /* ..., */ $arg_n)
{
    echo "Exemplo de função.\n";
    return $valor_retornado;
}
?>
]]>
    </programlisting>
   </example>
   <note>
    <para>
     A partir do PHP 8.0.0, a lista de parâmetros pode ter uma vírgula no final:
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
function foo($arg_1, $arg_2,) { }
?>
]]>
      </programlisting>
     </informalexample>
    </para>
   </note>

   <simpara>
    Qualquer código PHP válido pode aparecer dentro do corpo de uma função, mesmo outras
    funções e definições de
    <link linkend="language.oop5.basic.class">classes</link>.
   </simpara>
   <para>
    Nomes de funções seguem as mesmas regras que outros nomes no PHP. Um
    nome de função válido começa com uma letra ou um sublinhado, seguido,
    seguido por qualquer número de letras, números ou sublinhado. Com uma expressão
    regular, seria expressado com:
    <code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>.
   </para>
   &tip.userlandnaming;
   <simpara>
    As funções não precisam ser criadas antes de serem referenciadas,
    <emphasis>exceto</emphasis> quando uma função é condicionalmente definida
    como mostrado nos dois exemplos abaixo.
   </simpara>
   <para>
    Quando uma função é definida condicionalmente como nos dois
    exemplos abaixo, sua definição precisa ser processada <emphasis>antes</emphasis>
    de ser chamada.
   </para>
   <para>
    <example>
     <title>Funções definidas condicionalmente</title>
     <programlisting role="php">
<![CDATA[
<?php

$makefoo = true;

/* Nos nao podemos chamar foo() daqui
   porque ela ainda não existe,
   mas nos podemos chamar bar() */

bar();

if ($makefoo) {
  function foo()
  {
    echo "Eu não existo até que o programa passe por aqui.\n";
  }
}

/* Agora nos podemos chamar foo()
   porque $makefoo foi avaliado como true */

if ($makefoo) foo();

function bar()
{
  echo "Eu existo imediatamente desde o programa começar.\n";
}

?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    <example>
     <title>Funções dentro de funções</title>
     <programlisting role="php">
<![CDATA[
<?php
function foo()
{
  function bar()
  {
    echo "Eu não existo até foo() ser chamada.\n";
  }
}

/* Nós não podemos chamar bar() ainda
   porque ela ainda não foi definida. */

foo();

/* Agora nós podemos chamar bar(),
   porque o processamento de foo()
   tornou a primeira acessivel */

bar();

?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Todas as funções e classes no PHP tem escopo global - elas podem
    ser chamadas fora de uma função mesmo que tenham sido definidas dentro e vice-versa.
   </para>
   <simpara>
    O PHP não suporta sobrecarga de funções, e também não é possível cancelar ou
    alterar a definição de funções previamente declaradas.
   </simpara>
   <note>
    <simpara>
     Nomes de funções são case-insensitive para caracteres ASCII <literal>A</literal> até <literal>Z</literal>, mas é melhor chamar
     as funções da mesma forma que elas aparecem nas declarações.
    </simpara>
   </note>
   <simpara>
    Ambos <link linkend="functions.variable-arg-list">número variável de argumentos
    </link> e <link linkend="functions.arguments.default">argumentos
    padrões</link> são suportados em funções. veja também as referências
    das funções
    <function>func_num_args</function>,
    <function>func_get_arg</function> e
    <function>func_get_args</function> para mais informações.
   </simpara>

   <para>
    É possível chamar funções recursivas no PHP.
    <example>
     <title>Funções Recursivas</title>
     <programlisting role="php">
<![CDATA[
<?php
function recursion($a)
{
    if ($a < 20) {
        echo "$a\n";
        recursion($a + 1);
    }
}
?>
]]>
     </programlisting>
    </example>
   <note>
    <simpara>
     Chamadas recursivas a funções/métodos acima de 100-200 níveis podem
     exaurir a pilha e causar o término do script. Especificamente,
     recursão infinita é considerada um erro de programação.
    </simpara>
   </note>
   </para>

  </sect1>

  <sect1 xml:id="functions.arguments">
   <title>Parâmetros e argumentos de funções</title>

   <simpara>
    Os parâmetros de uma função são declarados em sua assinatura.
    Informações podem ser passadas para funções através da lista de argumentos,
    que é uma lista de expressões delimitadas por vírgulas. Os argumentos são
    avaliados da esquerda para a direita, e o resultado é atribuído aos parâmetros da
    função, antes que a função seja efetivamente chamada
    (avaliação <emphasis>ansiosa</emphasis>).
   </simpara>

   <!-- Note: this paragraph feels like it should be moved to the syntax part? -->
   <para>
    O PHP suporta a passagem de argumentos por valor (o padrão), <link
    linkend="functions.arguments.by-reference">passagem por
    referência</link> e <link
    linkend="functions.arguments.default">valores padrões de
    argumentos</link>. <link linkend="functions.variable-arg-list">Lista de argumentos de
    tamanho variável</link> e <link linkend="functions.named-arguments">argumentos nomeados</link>
    também são suportados.
   </para>
   <note>
    <para>
     A partir do PHP 7.3.0, é possível ter uma vírgula no final da lista de
     argumentos para chamadas de função:
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
$v = foo(
    $arg_1,
    $arg_2,
);
?>
]]>
      </programlisting>
     </informalexample>
    </para>
   </note>

   <para>
    A partir do PHP 8.0.0, a lista de parâmetros de uma função pode incluir uma vírgula final, que
    será ignorada. Isto é particularmente útil nos casos em que a lista de parâmetros é
    longa ou contém nomes de variáveis longos, tornando conveniente listar os parâmetros verticalmente.
   </para>
   <example>
    <title>Parâmetros de função com uma vírgula final</title>
    <programlisting role="php">
<![CDATA[
<?php
function takes_many_args(
    $primeiro,
    $segundo,
    $uma_variavel_com_nome_longo,
    $parametro_com_default = 5,
    $de_novo = 'argumento padrão', // Essa vírgula final não era permitida antes do PHP 8.0.0.
)
{
    // ...
}
?>
]]>
    </programlisting>
   </example>

   <sect2 xml:id="functions.arguments.by-reference">
    <title>Passando argumentos por referência</title>

    <simpara>
     Por padrão, argumentos de função são passados por valor (de forma que se
     você mudar o valor do parâmetro dentro da função, ele não é alterado fora
     da função). Para permitir que uma função modifique os
     seus argumentos, eles devem ser passados por referência.
    </simpara>
    <para>
     Para ter um argumento para uma função sempre passado por referência, adicione
     antes dele um "e comercial" (&amp;) ao nome do parâmetro na definição da função:
    </para>
    <para>
     <example>
      <title>Passando argumentos de função por referência</title>
      <programlisting role="php">
<![CDATA[
<?php
function add_some_extra(&$string)
{
    $string .= ' e alguma coisa mais.';
}
$str = 'Isto é uma string,';
add_some_extra($str);
echo $str;    // imprime 'Isto é uma string, e alguma coisa mais.'
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     É um erro passar uma expressão constante como argumento em um parâmetro que espera ser passado por referência.
    </para>
   </sect2>
   <sect2 xml:id="functions.arguments.default">
    <title>Valores padrão de parâmetros</title>

    <para>
     Uma função pode definir valores padrão para parâmetros usando sintaxe similar
     à atribuição de uma variável. O padrão é usado apenas quando o argumento do parâmetro não
     é passado. Observe que passar &null; <emphasis>não</emphasis>
     atribui o valor padrão.
    </para>
    <para>
     <example>
      <title>Utilizando parâmetros padrão em funções</title>
      <programlisting role="php">
<![CDATA[
<?php
function makecoffee($type = "cappuccino")
{
    return "Fazendo uma xícara de café $type.\n";
}
echo makecoffee();
echo makecoffee(null);
echo makecoffee("espresso");
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Fazendo uma xícara de café cappuccino.
Fazendo uma xícara de café.
Fazendo uma xícara de café espresso.
]]>
      </screen>
     </example>
    </para>
    <para>
     Valores padrões de parâmetro podem ser valores escalares, <type>array</type>s,
     o tipo especial &null; e, a partir do PHP 8.1.0, objetos usando a
     sintaxe <link linkend="language.oop5.basic.new">new ClassName()</link>.
    </para>
    <para>
     <example>
      <title>Usando tipos não escalares como valores padrões</title>
      <programlisting role="php">
<![CDATA[
<?php
function fazercafe($tipos = array("cappuccino"), $cafeteira = NULL)
{
    $dispositivo = is_null($cafeteira) ? "mãos" : $cafeteira;
    return "Fazendo uma xícara de ".join(", ", $tipos)." com $dispositivo.\n";
}
echo fazercafe();
echo fazercafe(array("cappuccino", "lavazza"), "chaleira");?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Fazendo uma xícara de cappuccino com mãos.
Fazendo uma xícara de cappuccino, lavazza com chaleira.
]]>
      </screen>
     </example>
    </para>
    <para>
     <example>
      <title>Usando objetos como valores padrão (a partir do PHP 8.1.0)</title>
      <programlisting role="php">
<![CDATA[
<?php
class CafeteiraPadrao {
    public function preparar() {
        return 'Fazendo café.\n';
    }
}
class CafeteiraChique {
    public function preparar() {
        return 'Preparando um belo café só para você.\n';
    }
}
function fazercafe($cafeteira = new CafeteiraPadrao)
{
    return $cafeteira->preparar();
}
echo fazercafe();
echo fazercafe(new CafeteiraChique);
?>
]]>
      </programlisting>

      &example.outputs;
      <screen>
<![CDATA[
Fazendo café.
Preparando um belo café só para você.
]]>
      </screen>
     </example>
    </para>
    <simpara>
     O valor padrão precisa ser uma expressão constante, não (por
     exemplo) uma variável, um membro de classe ou uma chamada de função.
    </simpara>
    <para>
     Observe que quaisquer parâmetros opcionais devem ser especificados após os
     parâmetros obrigatórios, caso contrário, eles não podem ser omitidos das chamadas.
     Considere o seguinte exemplo:
    </para>
    <para>
     <example>
      <title>Uso incorreto de parâmetros padrão de função</title>
      <programlisting role="php">
<![CDATA[
<?php
function fazeriogurte($recipiente = "tigela", $sabor)
{
    return "Fazendo um(a) $recipiente de iogurte de $sabor.\n";
}

echo fazeriogurte("framboesa"); // "framboesa" é $recipiente, não $sabor
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Fatal error: Uncaught ArgumentCountError: Too few arguments
 to function fazeriogurte(), 1 passed in example.php on line 42
]]>
      </screen>
     </example>
    </para>
    <para>
     Agora, compare o que está acima com este:
    </para>
    <para>
     <example>
      <title>Uso correto de parâmetros padrão de função</title>
      <programlisting role="php">
<![CDATA[
<?php
function fazeriogurte($sabor, $recipiente = "tigela")
{
    return "Fazendo um(a) $recipiente de iogurte de $sabor.\n";
}

echo fazeriogurte("framboesa"); // "framboesa" é $sabor
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Fazendo um(a) tigela de iogurte de framboesa.
]]>
      </screen>
     </example>
    </para>
    <para>
     A partir do PHP 8.0.0, <link linkend="functions.named-arguments">argumentos nomeados</link>
     podem ser usados para pular vários parâmetros opcionais.
    </para>
    <para>
     <example>
      <title>Uso correto de parâmetros padrão de função</title>
      <programlisting role="php">
<![CDATA[
<?php
function fazeriogurte($recipiente = "tigela", $sabor = "framboesa", $estilo = "Grego")
{
    return "Fazendo um(a) $recipiente de iogurte $estilo de $sabor.\n";
}

echo fazeriogurte(estilo: "natural");
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Fazendo um(a) tigela de iogurte natural de framboesa.
]]>
      </screen>
     </example>
    </para>
    <para>
     A partir do PHP 8.0.0, declarar parâmetros obrigatórios após parâmetros opcionais
     está <emphasis>descontinuado</emphasis>. Isso geralmente pode ser resolvido descartando
     o valor padrão, pois nunca será usado.
     Uma exceção a essa regra são parâmetros no formato
     <code>Type $param = null</code>, onde o padrão &null; torna o tipo implicitamente
     anulável. Este uso foi descontinuado a partir do PHP 8.4.0, e um
     <link linkend="language.types.declarations.nullable">tipo anulável</link> explícito
     deve ser usado.
     <example>
      <title>Declarando parâmetros opcionais após parâmetros obrigatórios</title>
      <programlisting role="php">
<![CDATA[
<?php

function foo($a = [], $b) {}     // Padrão não utilizado; descontinuado a partir do PHP 8.0.0
function foo($a, $b) {}          // Funcionalmente equivalente, sem aviso de descontinuação

function bar(A $a = null, $b) {} // A partir do PHP 8.1.0, $a é implicitamente requerido
                                 // (porque vem antes do parâmetro requerido),
                                 // porém implicitamente anulável (descontinuado a partir do PHP 8.4.0),
                                 // porque o valor padrão do parâmetro é null
function bar(?A $a, $b) {}       // Recomendado

?>
]]>
      </programlisting>
     </example>
    </para>
    <note>
     <simpara>
      A partir do PHP 7.1.0, omitir um parâmetro que não especifica um padrão
      lança um <classname>ArgumentCountError</classname>; em versões anteriores
      isso emitia um Aviso.
     </simpara>
    </note>
    <note>
     <simpara>
      Parâmetros que esperam o argumento por referência podem ter um valor padrão.
     </simpara>
    </note>
   </sect2>

   <sect2 xml:id="functions.variable-arg-list">
    <title>Número variável de argumentos</title>

    <simpara>
     O PHP suporta argumentos em quantidade variável em
     funções definidas pelo usuário, utilizando o token
     <literal>...</literal>.
    </simpara>

    <para>
     Listas de parâmetros podem conter o token
     <literal>...</literal> para indicar que a função aceita um
     número variável de argumentos. Os argumentos serão passados
     na variável informada como um &array;:

     <example>
      <title>Utilizando <literal>...</literal> para acessar argumentos variáveis</title>
      <programlisting role="php">
<![CDATA[
<?php
function sum(...$numbers) {
    $acc = 0;
    foreach ($numbers as $n) {
        $acc += $n;
    }
    return $acc;
}

echo sum(1, 2, 3, 4);
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
10
]]>
      </screen>
     </example>
    </para>

    <para>
     Você também pode utilizar <literal>...</literal> quando chamando funções para
     transformar uma variável <type>array</type>, <classname>Traversable</classname> ou
     literal em uma lista de argumentos.

     <example>
      <title>Utilizando <literal>...</literal> para fornecer argumentos</title>
      <programlisting role="php">
<![CDATA[
<?php
function add($a, $b) {
    return $a + $b;
}

echo add(...[1, 2])."\n";

$a = [1, 2];
echo add(...$a);
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
3
3
]]>
      </screen>
     </example>
    </para>

    <para>
     Podem ser especificados parâmetros posicionais antes do indicador.
     <literal>...</literal>. Nesse caso comente os argumentos finais,
     que não pareiam com um argumento posicional, serão adicionados ao
     array gerado por <literal>...</literal>.
    </para>

    <para>
     É também possível adicionar uma
     <link linkend="language.types.declarations">dica de tipo</link> antes do indicador
     <literal>...</literal>. Se presente, todos os argumentos
     capturados por <literal>...</literal> deverão conformar com o tipo do parâmetro.

     <example>
      <title>Argumentos variáveis com dica de tipo</title>
      <programlisting role="php">
<![CDATA[
<?php
function total_intervals($unit, DateInterval ...$intervals) {
    $time = 0;
    foreach ($intervals as $interval) {
        $time += $interval->$unit;
    }
    return $time;
}

$a = new DateInterval('P1D');
$b = new DateInterval('P2D');
echo total_intervals('d', $a, $b).' days';

// Isto falhará, já que null não é um objeto DateInterval.
echo total_intervals('d', null);
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
3 days
Catchable fatal error: Argument 2 passed to total_intervals() must be an instance of DateInterval, null given, called in - on line 14 and defined in - on line 2
]]>
      </screen>
     </example>
    </para>

    <para>
     Finalmente, também podem ser passados argumentos variáveis
     <link linkend="functions.arguments.by-reference">por referência</link> ao
     prefixar <literal>...</literal> com um
     <literal>&amp;</literal>.
    </para>

   </sect2>

   <sect2 xml:id="functions.named-arguments">
    <title>Argumentos nomeados</title>

    <para>
     O PHP 8.0.0 introduziu os argumentos nomeados como uma extensão aos
     parâmetros posicionais. Argumentos nomeados permitem a passagem de argumentos para uma
     função utilizando-se os nomes dos parâmetros ao invés das posições deles.
     Isto torna o significado do argumento auto documentável, e torna os argumentos
     independentes da ordem, além de permitir pular argumentos opcionais.
    </para>

    <para>
     Argumentos nomeados são passados ao prefixar o valor com o nome do parâmetro
     e dois-pontos. Usar palavras reservadas como nomes de parâmetros é permitido.
     O nome do parâmetro precisa ser um identificador e uma resolução dinâmica
     não é permitida.
    </para>

    <example>
     <title>Sintaxe dos argumentos nomeados</title>
     <programlisting role="php">
<![CDATA[
<?php
minhaFuncao(nomeParametro: $valor);
array_foobar(array: $value);

// NÃO suportado
nome_funcao($variavelQueGuardaNomeDoParametro: $valor);
?>
]]>
     </programlisting>
    </example>

    <example>
     <title>Comparando argumentos posicionais e nomeados</title>
     <programlisting role="php">
<![CDATA[
<?php
// Utilizando argumentos posicionais:
array_fill(0, 100, 50);

// Utilizando argumetos nomeados:
array_fill(start_index: 0, count: 100, value: 50);
?>
]]>
     </programlisting>
    </example>

    <para>
     A ordem em que argumentos nomeados são passados não importa.
    </para>

    <example>
     <title>Mesmo exemplo com argumentos em ordem diferente</title>
     <programlisting role="php">
<![CDATA[
<?php
array_fill(value: 50, count: 100, start_index: 0);
?>
]]>
     </programlisting>
    </example>

    <para>
     Argumentos nomeados podem ser combinados com argumentos posicionais. Nesse caso,
     os argumentos nomeados precisam estar depois dos argumentos posicionais.
     Também é possível especificar somente alguns dos argumentos opcionais de
     uma função, independente da ordem.
    </para>

    <example>
     <title>Combinando argumentos posicionais e nomeados</title>
     <programlisting role="php">
<![CDATA[
<?php
htmlspecialchars($string, double_encode: false);
// Mesmo que
htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', false);
?>
]]>
     </programlisting>
    </example>

    <para>
     Passar o mesmo argumento mais de uma vez resulta em Uma
     exceção <classname>Error</classname>.
    </para>

    <example>
     <title>Erro lançado ao passar um argumento ao mesmo parâmetro nomeado múltiplas vezes</title>
     <programlisting role="php">
<![CDATA[
<?php

function foo($param) { ... }

foo(param: 1, param: 2);
// Error: Named parameter $param overwrites previous argument

foo(1, param: 2);
// Error: Named parameter $param overwrites previous argument

?>
]]>
     </programlisting>
    </example>

    <para>
     A partir do PHP 8.1.0, é possível usar argumentos nomeados após desempacotar os argumentos.
     Um argumento nomeado <emphasis>não deve</emphasis> sobrepor argumentos já desempacotados.
    </para>

    <example>
     <title>Usando argumentos nomeados após desempacotar</title>
     <programlisting role="php">
<![CDATA[
<?php
function foo($a, $b, $c = 3, $d = 4) {
  return $a + $b + $c + $d;
}

var_dump(foo(...[1, 2], d: 40)); // 46
var_dump(foo(...['b' => 2, 'a' => 1], d: 40)); // 46

var_dump(foo(...[1, 2], b: 20)); // Fatal error. Named parameter $b overwrites previous argument
?>
]]>
     </programlisting>
    </example>

   </sect2>
  </sect1>

  <sect1 xml:id="functions.returning-values">
   <title>Retornando valores</title>

   <para>
    Os valores podem ser retornados utilizando a instrução opcional return. Qualquer
    tipo pode ser retornado, incluindo arrays e objetos. Isto faz com que
    as função termine sua execução imediatamente e passa o controle de volta para
    a linha de onde ela foi chamada. Veja a documentação da função <function>return</function>
    para maiores informações.
   </para>

   <note>
    <para>
     Se <function>return</function> for omitido então o valor &null; será
     retornado.
    </para>
   </note>

   <sect2>
    <title>Sintaxe do return</title>
    <para>
     <example>
      <title>O uso de <function>return</function></title>
      <programlisting role="php">
<![CDATA[
<?php
function quadrado($num)
{
    return $num * $num;
}
echo quadrado(4); // imprime '16'.
?>
]]>
      </programlisting>
     </example>
    </para>

    <para>
     Você não pode retornar múltiplos valores a partir de uma função, mas
     resultados similares podem ser obtidos retornando um array.
    </para>
    <para>
     <example>
      <title>Retornando um array para devolver vários valores</title>
      <programlisting role="php">
<![CDATA[
<?php
function primeiros_numeros()
{
    return [0, 1, 2];
}
// Desconstruir o array coleta cada item individualmente
[$zero, $one, $two] = primeiros_numeros();

// Anteriormente ao 7.1.0 a única alternativa era usar list()
list($zero, $one, $two) = primeiros_numeros();

?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     Para retornar uma referência de uma função, use o operador de referência &amp;
     em ambas a declaração da função e quando definindo o valor para a
     variável.
    </para>
    <para>
     <example>
      <title>Retornando uma referência de uma função</title>
      <programlisting role="php">
<![CDATA[
<?php
function &retorna_referencia()
{
    return $alguma_referencia;
}

$nova_referencia =& retorna_referencia();
?>
]]>
      </programlisting>
     </example>
    </para>
    <simpara>
     Para mais detalhes sobre referências, leia a seção <link
     linkend="language.references">Referências</link>.
    </simpara>
   </sect2>
  </sect1>

  <sect1 xml:id="functions.variable-functions">
   <title>Funções variáveis</title>

   <para>
    O PHP suporta o conceito de funções variáveis. Isto significa que se
    um nome de variável tem parênteses no final dela, o PHP procurará
    uma função com o mesmo nome, qualquer que seja a avaliação da variável,
    e tentará executá-la. Entre outras coisas, isto pode
    ser usado para implementar callbacks, tabelas de função e assim por diante.
   </para>
   <para>
    Funções variáveis não funcionam com construtores de linguagem como
    <function>echo</function>, <function>print</function>,
    <function>unset</function>, <function>isset</function>,
    <function>empty</function>, <function>include</function>,
    <function>require</function> e outras assim. Utilize uma função de wrapper
    para usar quaisquer um destes construtores como uma função variável.
   </para>
   <para>
    <example>
     <title>Exemplo de funções variáveis</title>
     <programlisting role="php">
<![CDATA[
<?php
function foo() {
    echo "Chamou foo()<br>\n";
}

function bar($arg = '')
{
    echo "Chamou bar(); com argumento '$arg'.<br />\n";
}

// Essa é uma função wrapper para echo()
function echoit($string)
{
    echo $string;
}

$func = 'foo';
$func();        // Chama foo()

$func = 'bar';
$func('test');  // Chama bar()

$func = 'echoit';
$func('test');  // Chama echoit()
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Um método de um objeto também pode ser chamado com a sintaxe de funções variáveis.
    <example>
     <title>Exemplo de chamada de um método variável</title>
     <programlisting role="php">
<![CDATA[
<?php
class Foo
{
    function MetodoVariavel()
    {
        $name = 'Bar';
        $this->$name(); // Isto chama o método Bar()
    }

    function Bar()
    {
        echo "Bar foi chamada!";
    }
}

$foo = new Foo();
$funcname = "MetodoVariavel";
$foo->$funcname();  // Isto chama $foo->MetodoVariavel()

?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Quando chamando métodos estáticos, uma chamada de função tem preferência que uma propriedade estática.
    <example>
     <title>Método variávei com propriedades estáticas</title>
     <programlisting role="php">
<![CDATA[
<?php
class Foo
{
    static $variable = 'propriedade estática';
    static function Variable()
    {
        echo 'Método chamado';
    }
}

echo Foo::$variable; // Isto imprime 'propriedade estática'. Ele busca $variable no escopo da classe.
$variable = "Variable";
Foo::$variable();  // Isto chama $foo->Variable(), lendo a $variable no escopo da chamada.

?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    <example>
     <title>Callables complexos</title>
     <programlisting role="php">
<![CDATA[
<?php
class Foo
{
    static function bar()
    {
        echo "bar\n";
    }
    function baz()
    {
        echo "baz\n";
    }
}

$func = array("Foo", "bar");
$func(); // prints "bar"
$func = array(new Foo, "baz");
$func(); // prints "baz"
$func = "Foo::bar";
$func(); // prints "bar"
?>
]]>
     </programlisting>
    </example>
   </para>

   <sect2 role="seealso">
    &reftitle.seealso;
    <para>
     <simplelist>
      <member><function>is_callable</function></member>
      <member><function>call_user_func</function></member>
      <member><function>function_exists</function></member>
      <member><link linkend="language.variables.variable">variáveis variáveis</link></member>
     </simplelist>
    </para>
   </sect2>
  </sect1>

  <sect1 xml:id="functions.internal">
   <title>Funções internas (built-in)</title>

   <para>
    O PHP vem por padrão com muitas funções e construtores. Também existem
    funções que necessitam que uma extensão específica esteja compilada, se não
    erros fatais "undefined function" (função não definida) irão aparecer. Por exemplo, para usar
    as funções <link linkend="ref.image">image</link> como
    <function>imagecreatetruecolor</function>, o PHP deve ser compilado com suporte
    <productname>GD</productname>. Ou, para usar
    <function>mysqli_connect</function>, PHP deve ser compilado com suporte
    <link linkend="book.mysqli">MySQLi</link>. Existem muitas funções do núcleo
    que são incluídas em cada versão do PHP, como
    <link linkend="ref.strings">string</link> e
    <link linkend="ref.var">variable</link>. Uma chamada a
    <function>phpinfo</function> ou
    <function>get_loaded_extensions</function> irá mostrar quais extensões estão
    carregadas no PHP. Note também que várias extensões são ativadas por padrão e que
    o manual do PHP é dividido por extensão. Veja
    <link linkend="configuration">configuração</link>,
    <link linkend="install">instalação</link>, e os capítulos
    individuais das extensões para como configurar o PHP.
   </para>
   <para>
    A leitura e entendimento de um protótipo de função é explicado na
    seção do manual intitulada
    <link linkend="about.prototypes">como ler uma definição de função</link>.
    É importante perceber o que a função retorna ou se a função trabalha
    diretamente no valor passado como argumento. Por exemplo,
    <function>str_replace</function> irá retornar a string modificada enquanto
    <function>usort</function> trabalha na própria variável passada no
    argumento. Cada página do manual também contém informações específicas de cada
    função, como: parâmetros da função, mudanças de comportamento,
    valores de retorno tanto para sucesso e erros, como outras informações disponíveis.
    O conhecimento destas diferenças importantes é crucial para escrever corretamente seu código PHP.
   </para>
   <note>
    <simpara>
     Se os parâmetros dados a uma função não forem o que ela espera, como
     passar um <type>array</type> onde uma <type>string</type> é esperada,
     o valor de retorno da função é indefinido. Neste caso provavelmente
     irá retornar &null; mas isto é apenas uma convenção, e
     você não pode depender disso.
     A partir do PHP 8.0.0, uma exceção <classname>TypeError</classname> é lançada
     nesses casos.
    </simpara>
   </note>
   <note>
    <para>
     Tipos escalares para funções embutidas são anuláveis por padrão no modo coercivo.
     A partir do PHP 8.1.0, passar &null; para um parâmetro de uma função interna que não é declarado anulável
     é desencorajado e emite um aviso de descontinuação no modo coercitivo para alinhar com o comportamento de funções definidas pelo usuário,
     onde tipos escalares precisam ser marcados como anuláveis explícitamente.
    </para>

    <para>
     Por exemplo, a função <function>strlen</function> expera que o parâmetro <literal>$string</literal>
     seja uma &string; não anulável.
     Por razões históricas, o PHP permite a passagem de &null; para esse parâmetro no modo coercivo, e o parâmetro é
     implicitamente convertido para <type>string</type>, resultando em um valor <literal>""</literal>.
     Em contrapartida, um <classname>TypeError</classname> é emitido no modo estrito.
    </para>

    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
var_dump(strlen(null));
// "Deprecated: Passing null to parameter #1 ($string) of type string is deprecated" as of PHP 8.1.0
// int(0)

var_dump(str_contains("foobar", null));
// "Deprecated: Passing null to parameter #2 ($needle) of type string is deprecated" as of PHP 8.1.0
// bool(true)
?>
]]>
     </programlisting>
    </informalexample>
   </note>

   <sect2 role="seealso">
    &reftitle.seealso;
    <para>
     <simplelist>
      <member><function>function_exists</function></member>
      <member><link linkend="funcref">A referência das funções</link></member>
      <member><function>get_extension_funcs</function></member>
      <member><function>dl</function></member>
     </simplelist>
    </para>
   </sect2>
  </sect1>

  <sect1 xml:id="functions.anonymous">
   <title>Funções anônimas</title>

   <simpara>
    Funções anônimas, também conhecidas como <literal>closures</literal>, permitem a criação
    de funções que não tem o nome especificado. Elas são mais úteis
    como o valor de parâmetros <type>callable</type>,
    mas podem ter vários outros usos.
   </simpara>
   <simpara>
    Funções anônimas são implementadas utilizando a classe
    <link linkend="class.closure"><classname>Closure</classname></link>
   </simpara>

   <example>
    <title>Exemplo de função anônima</title>
    <programlisting role="php">
<![CDATA[
<?php
echo preg_replace_callback('~-([a-z])~', function ($match) {
    return strtoupper($match[1]);
}, 'hello-world');
// outputs helloWorld
?>
]]>
    </programlisting>
   </example>

   <simpara>
    Closures também podem ser utilizadas como valores de variáveis; o PHP automaticamente
    converte expressões assim em instâncias da classe interna
    <classname>Closure</classname>. Definindo um closure
    a uma variável usa a mesma sintaxe que qualquer outra definição, incluindo
    o ponto-e-vírgula:
   </simpara>

   <example>
    <title>Exemplo de como definir uma função anônima para uma variável</title>
    <programlisting role="php">
<![CDATA[
<?php
$greet = function($name) {
    printf("Hello %s\r\n", $name);
};

$greet('World');
$greet('PHP');
?>
]]>
    </programlisting>
   </example>

   <simpara>
    Closures também podem herdar variáveis do escopo pai. Essas
    variáveis precisam ser referenciadas utilizando a instrução <literal>use</literal>.
    A partir do PHP 7.1, essas variáveis não devem incluir &link.superglobals;,
    <varname>$this</varname>, ou variáveis com o mesmo nome como um parâmetro.
    A declaração de tipo de retorno de uma função deve ser posicionada
    <emphasis>depois</emphasis> de uma instrução <literal>use</literal>.
   </simpara>

   <example>
    <title>Herdando variáveis do escopo anterior</title>
    <programlisting role="php">
<![CDATA[
<?php
$message = 'hello';

// Sem "use"
$example = function () {
    var_dump($message);
};
$example();

// Inherit $message
$example = function () use ($message) {
    var_dump($message);
};
$example();

// Herdando valor da variável quando a função é definida,
// não quando é chamada
$message = 'world';
$example();

// Reseta mensagem
$message = 'hello';

// Herdando por referência
$example = function () use (&$message) {
    var_dump($message);
};
$example();

// O valor modificado no escopo pai
// reflete quando a função é chamada
$message = 'world';
$example();

// Closures também aceitam argumentos normais
$example = function ($arg) use ($message) {
    var_dump($arg . ' ' . $message);
};
$example("hello");

// Declaração de tipo de retorno após a instrução 'use'
$example = function () use ($message): string {
    return "hello $message";
};
var_dump($example());
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Notice: Undefined variable: message in /example.php on line 6
NULL
string(5) "hello"
string(5) "hello"
string(5) "hello"
string(5) "world"
string(11) "hello world"
string(11) "hello world"
]]>
    </screen>
   </example>

   <para>
    A partir do PHP 8.0.0 a lista de variáveis herdadas no escopo podem incluir uma vírgula
    final, que será ignorada.
   </para>
   <simpara>
    Herdar variáveis do escopo pai <emphasis>não</emphasis>
    é o mesmo que usar variáveis globais.
    Variáveis globais existem no escopo global, o qual é o mesmo não
    importa a função sendo executada. O escopo pai de um closure é a função
    no qual o closure foi declarado (não necessariamente a função a partir do
    qual ele foi chamado). Veja o exemplo a seguir:
   </simpara>

   <example>
    <title>Closures e escopo</title>
    <programlisting role="php">
<![CDATA[
<?php
// Um exemplo básico de carrinho de compras que contém uma lista de produtos
// e a quantidade de cada produto. Inclui um método que
// calcula o preço total dos itens no carrinho utilizando uma
// closure como função de retorno.
class Cart
{
    const PRICE_BUTTER  = 1.00;
    const PRICE_MILK    = 3.00;
    const PRICE_EGGS    = 6.95;

    protected $products = array();

    public function add($product, $quantity)
    {
        $this->products[$product] = $quantity;
    }

    public function getQuantity($product)
    {
        return isset($this->products[$product]) ? $this->products[$product] :
               FALSE;
    }

    public function getTotal($tax)
    {
        $total = 0.00;

        $callback =
            function ($quantity, $product) use ($tax, &$total)
            {
                $pricePerItem = constant(__CLASS__ . "::PRICE_" .
                    strtoupper($product));
                $total += ($pricePerItem * $quantity) * ($tax + 1.0);
            };

        array_walk($this->products, $callback);
        return round($total, 2);
    }
}

$my_cart = new Cart;

// Adiciona alguns itens no carrinho
$my_cart->add('butter', 1);
$my_cart->add('milk', 3);
$my_cart->add('eggs', 6);

// Exibe o total com uma taxa de venda de 5%.
print $my_cart->getTotal(0.05) . "\n";
// O resultado é 54.29
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Vinculação automática do <literal>$this</literal></title>
    <programlisting role="php">
<![CDATA[
<?php

class Test
{
    public function testing()
    {
        return function() {
            var_dump($this);
        };
    }
}

$object = new Test;
$function = $object->testing();
$function();

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
object(Test)#1 (0) {
}
]]>
    </screen>
   </example>

   <para>
    Quando declarada no contexto de uma classe, a classe corrente é
    automaticamente vinculada a ela, tornando <literal>$this</literal> disponível
    dentro do escopo da função. Se essa vinculação automática da classe
    corrente não for o comportamento esperado,
    <link linkend="functions.anonymous-functions.static">funções anônimas estáticas</link>
    podem ser utilizadas.
   </para>

   <sect2 xml:id="functions.anonymous-functions.static">
    <title>Funções anônimas estáticas</title>
    <para>
     Funções anônimas podem ser declaradas estaticamente. Evita
     que a classe corrente seja automaticamente vinculada a
     ela. Objetos também podem não ser vinculados a ela em tempo de execução.
    </para>
    <para>
     <example>
      <title>Tentando utilizar o <literal>$this</literal> de dentro de uma função anônima estática</title>
      <programlisting role="php">
<![CDATA[
<?php

class Foo
{
    function __construct()
    {
        $func = static function() {
            var_dump($this);
        };
        $func();
    }
};
new Foo();

?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Notice: Undefined variable: this in %s on line %d
NULL
]]>
      </screen>
     </example>
    </para>

    <para>
     <example>
      <title>Tentando vincular um objeto a uma função anônima estática</title>
      <programlisting role="php">
<![CDATA[
<?php

$func = static function() {
    // corpo da função
};
$func = $func->bindTo(new stdClass);
$func();

?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Warning: Cannot bind an instance to a static closure in %s on line %d
]]>
      </screen>
     </example>
    </para>
   </sect2>

   <sect2 role="changelog">
    &reftitle.changelog;
    <para>
     <informaltable>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>&Version;</entry>
         <entry>&Description;</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>8.3.0</entry>
         <entry>
          Closures criadas a partir de <link linkend="language.oop5.magic">métodos
          mágicos</link> podem aceitar parâmetros nomeados.
         </entry>
        </row>
        <row>
         <entry>7.1.0</entry>
         <entry>
          Funções anônimas podem não incluir &link.superglobals;,
          <varname>$this</varname>, ou qualquer variável com o mesmo nome como um
          parâmetro.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </informaltable>
    </para>
   </sect2>

   <sect2 role="notes">
    &reftitle.notes;
    <note>
     <simpara>
      É possível utilizar <function>func_num_args</function>,
      <function>func_get_arg</function> e <function>func_get_args</function>
      dentro de closures.
     </simpara>
    </note>
   </sect2>

  </sect1>
  <sect1 xml:id="functions.arrow">
   <title>Arrow Functions</title>

   <simpara>
    Arrow functions foram introduzidos a partir do PHP 7.4 como uma sintaxe mais concisa para
    <link linkend="functions.anonymous">funções anônimas</link>.
   </simpara>
   <simpara>
    Funções anônimas e arrow functions são implementadas usando a classe
    <link linkend="class.closure"><classname>Closure</classname></link>.
   </simpara>

   <simpara>
    Arrow functions tem a forma básica
    <code>fn (argument_list) =&gt; expr</code>.
   </simpara>

   <simpara>
    Arrow functions possuem a mesmas características das
    <link linkend="functions.anonymous">funções anônimas</link>,
    exceto que o uso de variáveis do escopo pai é sempre automático.
   </simpara>

   <simpara>
    Quando uma variável usada na expressão é definida no escopo pai
    ele será implicitamente capturado por valor.
    No exemplo a seguir, as funções <varname>$fn1</varname> e
    <varname>$fn2</varname>comportam-se da mesma maneira.
   </simpara>

   <para>
    <example>
     <title>Arrow functions capturam variáveis por valor automaticamente</title>
     <programlisting role="php">
<![CDATA[
<?php

$y = 1;

$fn1 = fn($x) => $x + $y;
// Equivalente ao usar $y por valor:
$fn2 = function ($x) use ($y) {
    return $x + $y;
};

var_export($fn1(3));
?>
]]>
     </programlisting>
     &example.outputs;
     <screen>
<![CDATA[
4
]]>
      </screen>
    </example>
   </para>
   <simpara>
    Isso também funciona se as arrow de functions estiverem aninhadas:
   </simpara>
   <para>
    <example>
     <title>Arrow functions capturam variáveis por valor automaticamente, mesmo quando aninhadas</title>
     <programlisting role="php">
<![CDATA[
<?php

$z = 1;
$fn = fn($x) => fn($y) => $x * $y + $z;
// Outputs 51
var_export($fn(5)(10));
?>
]]>
     </programlisting>
    </example>
   </para>
   <simpara>
    Da mesma forma que funções anônimas,
    a sintaxe das arrow functions permitem assinaturas de função arbitrária,
    incluindo parâmetros e tipos de retorno, valores padrão, variadics,
    bem como por referência passando e retornando.
    Todos os exemplos válidos de arrow functions:
   </simpara>
   <para>
    <example>
     <title>Exemplos de arrow functions</title>
     <programlisting role="php">
<![CDATA[
<?php

fn(array $x) => $x;
static fn($x): int => $x;
fn($x = 42) => $x;
fn(&$x) => $x;
fn&($x) => $x;
fn($x, ...$rest) => $rest;

?>
]]>
     </programlisting>
    </example>
   </para>
   <simpara>
    Arrow functions usam vinculação de variável por valor.
    Isso é aproximadamente equivalente a realizar um <code>use($x)</code> para cada
    variável <varname>$x</varname> usada dentro da arrow function.
    Uma passagem de variável por valor, significa que não é possível modificar quaisquer valores
    do escopo externo.
    <link linkend="functions.anonymous">Funções anônimas</link>
    podem ser usadas em vez disso para passagem de variável por referência.
   </simpara>
   <para>
    <example>
     <title>Valores do escopo externo não podem ser modificados por arrow functions</title>
     <programlisting role="php">
<![CDATA[
<?php

$x = 1;
$fn = fn() => $x++; // Não tem efeito
$fn();
var_export($x);  // Imprime 1

?>
]]>
     </programlisting>
    </example>
   </para>

   <sect2 role="changelog">
    &reftitle.changelog;
    <para>
     <informaltable>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>&Version;</entry>
         <entry>&Description;</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>7.4.0</entry>
         <entry>
          Arrow functions tornou-se disponível.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </informaltable>
    </para>
   </sect2>

   <sect2 role="notes">
    &reftitle.notes;
    <note>
     <simpara>
      É possível usar <function>func_num_args</function>,
      <function>func_get_arg</function>, e <function>func_get_args</function>
      de dentro de uma arrow functions.
     </simpara>
    </note>
   </sect2>
  </sect1>

  <sect1 xml:id="functions.first_class_callable_syntax">
   <title>Sintaxe de Callable de Primeira Classe</title>

   <para>
    A sintaxe de callable de primeira classe é introduzida a partir do PHP 8.1.0, como uma maneira de criar <link linkend="functions.anonymous">funções anônimas</link> a partir de <link linkend="language.types.callable">callable</link>.
    Ela substitui a sintaxe de callable existente usando strings e arrays.
    A vantagem dessa sintaxe é que ela é acessível à análise estática, e usa o escopo no ponto onde o callable é adquirido.
   </para>

   <para>
    A sintaxe <code>CallableExpr(...)</code> é usada para criar um objeto <classname>Closure</classname> a partir de callable. <code>CallableExpr</code> aceita qualquer expressão que possa ser diretamente chamada na gramática do PHP:
    <example>
     <title>Sintaxe de callable de primeira classe simples</title>
     <programlisting role="php">
<![CDATA[
<?php

class Foo {
   public function metodo() {}
   public static function metodoestatico() {}
   public function __invoke() {}
}

$obj = new Foo();
$strClasse = 'Foo';
$strMetodo = 'metodo';
$strMetodoestatico = 'metodoestatico';


$f1 = strlen(...);
$f2 = $obj(...);  // objeto invocável
$f3 = $obj->metodo(...);
$f4 = $obj->$strMetodo(...);
$f5 = Foo::metodoestatico(...);
$f6 = $strClasse::$strMetodoestatico(...);

// Callable tradicional usando string, array
$f7 = 'strlen'(...);
$f8 = [$obj, 'metodo'](...);
$f9 = [Foo::class, 'metodoestatico'](...);
?>
]]>
     </programlisting>
    </example>
   </para>

   <note>
    <para>
      As <code>...</code> são parte da sintaxe, e não uma omissão.
    </para>
   </note>

   <para>
    <code>CallableExpr(...)</code> tem a mesma semântica que <methodname>Closure::fromCallable</methodname>.
    Isto é, That is, ao contrário de callable usando string e array, <code>CallableExpr(...)</code> respeita o escopo no ponto onde ela é criada:
    <example>
     <title>Comparação de escopo de <code>CallableExpr(...)</code> e callable tradicional</title>
     <programlisting role="php">
<![CDATA[
<?php

class Foo {
    public function obterMetodoPrivado() {
        return [$this, 'metodoPrivado'];
    }

    private function metodoPrivado() {
        echo __METHOD__, "\n";
    }
}

$foo = new Foo;
$metodoPrivado = $foo->obterMetodoPrivado();
$metodoPrivado();
// Fatal error: Call to private method Foo::metodoPrivado() from global scope
// Isso acontece porque a chamada é realizada fora de Foo e a visibilidade será verificada a partir desse ponto.

class Foo1 {
    public function obterMetodoPrivado() {
        // Usa o escopo onde o callable é adquirido.
        return $this->metodoPrivado(...); // Idêntico a Closure::fromCallable([$this, 'metodoPrivado']);
    }

    private function metodoPrivado() {
        echo __METHOD__, "\n";
    }
}

$foo1 = new Foo1;
$metodoPrivado = $foo1->obterMetodoPrivado();
$metodoPrivado();  // Foo1::metodoPrivado
?>
]]>
     </programlisting>
    </example>

   </para>

   <note>
    <para>
     Criação de objetos por essa sintaxe (por exemplo <code>new Foo(...)</code>) não é suportada, porque a sintaxe <code>new Foo()</code> não é considerada uma chamada.
    </para>
   </note>

   <note>
    <para>
     A sintaxe de chamável de primeira classe não pode ser combinada com o <link linkend="language.oop5.basic.nullsafe">operador nullsafe</link>. Ambos os resultados a seguir resultam em um erro de tempo de compilação:
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
$obj?->metodo(...);
$obj?->prop->metodo(...);
?>
]]>
      </programlisting>
     </informalexample>
    </para>
   </note>
  </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
-->