Funções PHP: Entendendo e Usando no Seu Código

Uma função é um bloco de código nomeado que executa uma tarefa específica. As funções são um dos blocos de construção mais importantes em PHP: elas permitem escrever uma lógica uma vez e reutilizá-la em qualquer lugar, em vez de copiar o mesmo código em vários locais. Esta página aborda como definir e chamar funções, como passar argumentos (incluindo padrões, com declaração de tipo, por referência e de comprimento variável), como os valores de retorno funcionam e as regras de escopo que determinam quais variáveis uma função pode ver.

O que é uma Função PHP?

Uma função PHP é um bloco de código reutilizável que é executado somente quando você a chama. Você declara uma função com a palavra-chave function, seguida de um nome, um par de parênteses listando quaisquer parâmetros (as entradas que a função aceita) e um corpo entre { }. Uma função pode opcionalmente retornar um valor com a palavra-chave return.

A estrutura geral de uma função é assim:

function functionName($parameter1, $parameter2) {
    // code to run when the function is called
    return $result; // optional
}

Algumas regras de nomenclatura: o nome de uma função deve começar com uma letra ou sublinhado, pode conter letras, números e sublinhados, e não diferencia maiúsculas de minúsculas (sayHello() e SayHello() chamam a mesma função). Por convenção, a maior parte do código PHP moderno usa camelCase ou snake_case para funções definidas pelo usuário.

Por que Usar Funções PHP?

O uso de funções traz vários benefícios concretos:

• Reutilização. Escreva a lógica uma vez, chame quantas vezes precisar. Alterar o comportamento significa editar um único lugar em vez de caçar cada cópia.
• Legibilidade. Uma função bem nomeada (calculateTax()) informa ao leitor o que acontece sem que ele precise ler como.
• Modularidade. Dividir uma tarefa complexa em funções menores torna cada parte mais fácil de entender, testar e depurar.
• Menos bugs. Menos código duplicado significa menos lugares para o mesmo erro se esconder.

Como Definir e Chamar uma Função

Definir uma função não faz nada por si só — o corpo só é executado quando você a chama escrevendo seu nome seguido de parênteses. O exemplo abaixo define uma função sem parâmetros e a chama duas vezes.

<?php

function greet() {
    echo "Hello from a function!\n";
}

greet(); // call it
greet(); // call it again

?>

Saída:

Hello from a function!
Hello from a function!

Função Simples que Retorna um Valor

Uma função que não recebe parâmetros e retorna uma string:

Saída: Hello, World!

Parâmetros e Argumentos de Funções

Um parâmetro é a variável nomeada na definição da função; um argumento é o valor real que você passa ao chamá-la. PHP oferece várias maneiras de trabalhar com eles.

Passando Argumentos

A função a seguir recebe dois parâmetros e retorna a soma deles. Passamos 5 e 10 como argumentos.

Saída: 15

Valores Padrão de Parâmetros

Um parâmetro pode ter um valor padrão, usado quando o chamador omite esse argumento. Parâmetros com padrões devem vir após os obrigatórios.

<?php

function greet($name, $greeting = "Hello") {
    return "$greeting, $name!";
}

echo greet("Anna") . "\n";          // uses the default greeting
echo greet("Anna", "Welcome");      // overrides the default

?>

Saída:

Hello, Anna!
Welcome, Anna!

Declarações de Tipo

Você pode declarar o tipo esperado de cada parâmetro e do valor de retorno. Isso torna uma função autodocumentada e permite que o PHP lance um erro quando recebe o tipo errado.

<?php

function multiply(int $a, int $b): int {
    return $a * $b;
}

echo multiply(4, 3);

?>

Saída: 12

Passando Argumentos por Referência

Por padrão, PHP passa argumentos por valor — a função trabalha com uma cópia e a variável original não é alterada. Prefixe um parâmetro com & para passá-lo por referência, permitindo que a função modifique diretamente a variável do chamador.

<?php

function addOne(&$number) {
    $number++;
}

$count = 10;
addOne($count);
echo $count;

?>

Saída: 11

Listas de Argumentos de Comprimento Variável

Quando você não sabe quantos argumentos serão passados, o operador ... (splat) coleta todos eles em um array.

<?php

function sumAll(...$numbers) {
    return array_sum($numbers);
}

echo sumAll(1, 2, 3, 4, 5);

?>

Saída: 15

Retornando Valores

Uma função retorna um valor com a palavra-chave return. return também interrompe a função imediatamente — qualquer código após ela é ignorado. Uma função sem return (ou return; sem valor) retorna null. Para retornar vários valores de uma vez, retorne um array (ou um list() pode desempacotá-lo no lado receptor).

<?php

function minMax($a, $b) {
    if ($a < $b) {
        return [$a, $b]; // returns and exits here
    }
    return [$b, $a];
}

[$min, $max] = minMax(8, 3);
echo "Min: $min, Max: $max";

?>

Saída: Min: 3, Max: 8

Para uma análise mais aprofundada, consulte o capítulo sobre instrução return do PHP.

Escopo de Variáveis

Variáveis criadas dentro de uma função são locais a ela — não existem fora dela, e a função não pode ver variáveis definidas no escopo externo (global) a menos que você as importe com a palavra-chave global ou as passe como argumentos.

<?php

$message = "outside";

function showScope() {
    // $message from the global scope is NOT visible here
    $message = "inside";
    echo $message;
}

showScope();        // prints the local value
echo "\n";
echo $message;      // prints the global value, untouched

?>

Saída:

inside
outside

O escopo é uma fonte comum de confusão para iniciantes — o capítulo sobre escopo de variáveis PHP explica em detalhes global, static e variáveis locais. Veja também o capítulo sobre Variáveis PHP para o básico.

Erros Comuns a Evitar

• Chamar uma função antes que ela retorne o que você espera — lembre-se que return apenas devolve um valor; você ainda precisa usar echo ou armazená-lo. add(5, 10); sozinho não produz nada visível.
• Colocar um parâmetro padrão antes de um obrigatório — PHP exige que os padrões venham por último.
• Esperar que as alterações vazem para fora — sem &, modificar um parâmetro dentro de uma função não altera a variável do chamador.
• Redeclarar um nome de função — você não pode definir duas funções com o mesmo nome; o PHP lança um erro fatal.

Conclusão

As funções PHP são a base de um código organizado e reutilizável. Assim que você se sentir confortável definindo funções, passando argumentos (com padrões, tipos, referências e variadics), retornando valores e raciocinando sobre escopo, poderá dividir qualquer problema grande em partes limpas e testáveis. Em seguida, explore como trabalhar com Arrays PHP e Strings PHP, nos quais as funções frequentemente operam.

Prática