Funções parâmetros e retorno

Neste capítulo você vai dar um nome a uma tarefa e usar seu resultado sem depender de uma variável externa.

Seu ponto de partida

Estude depois do capítulo 09. O exemplo deste capítulo é 10-funcoes-parametros, no pacote que acompanha o volume. Copie a pasta inicio para um diretório de prática e preserve o original. A raiz do exemplo é a referência concluída desta etapa. Sua cópia permite experimentar sem perder a referência.

Execute o PHP na raiz da sua cópia com php -S 127.0.0.1:8000 -t public. Abra http://127.0.0.1:8000/. Não abra PHP por duplo clique nem use o servidor de Python. Encerre com Ctrl+C antes de trocar de etapa.

Como praticar

Leia a explicação e digite ou confira o código indicado. Mude uma coisa. Antes de conferir, anote sua previsão. Salve, recarregue e compare. Se não acontecer o esperado, investigue o erro antes de avançar. Cada experiência parte dos valores da referência. Depois de conferir, desfaça somente a mudança desse experimento antes de começar a próxima lição. Você pode parar depois de uma lição e retomar mais tarde.

Defina uma tarefa pequena

Uma função reúne instruções sob um nome. Definir a função não executa seu corpo. A chamada pede a execução. O parâmetro é o nome local que recebe o valor enviado na chamada.

A referência calcula vagas restantes com dois inteiros. Os tipos int documentam a entrada e o retorno. Strict_types no início do arquivo torna certas verificações de tipos mais rigorosas nas chamadas deste arquivo. Não assuma que isso valida dados vindos de formulários.

Faça no seu exemplo

Em public/index.php, localize o bloco indicado. A referência completa acompanha esta etapa.

function restantes(int $total, int $ocupadas): int
{
    return $total - $ocupadas;
}

Mude uma coisa e preveja

Troque somente o total da chamada de 12 para 10.

Anote o que você acha que vai acontecer antes de salvar e recarregar.

Recarregue e confira

O resultado passa de 9 para 7.

Se não acontecer

Se nada aparecer, confira se chamou a função e mostrou seu retorno. A definição sozinha não produz saída.

Retornar não é imprimir

Return devolve um valor para quem chamou e encerra a função. Echo escreve na resposta. Uma função que calcula e retorna pode ser usada em vários lugares sem imprimir onde você não pretendia.

Guarde o retorno numa variável antes de mostrar. Isso permite usar o mesmo resultado numa frase e numa comparação sem duplicar o cálculo.

Faça no seu exemplo

Em public/index.php, localize o bloco indicado. A referência completa acompanha esta etapa.

$livres = restantes(12, 3);

Mude uma coisa e preveja

Troque somente ocupadas na chamada para 12.

Anote o que você acha que vai acontecer antes de salvar e recarregar.

Recarregue e confira

A variável livres vale zero. O parágrafo mostra zero sem uma impressão inesperada antes do HTML.

Se não acontecer

Se houver texto acima do cabeçalho, confira se acrescentou echo dentro da função. Restaure return.

O parâmetro pertence à função

Uma variável criada fora da função não aparece automaticamente dentro dela. Os parâmetros tornam a dependência explícita. Evite global nesta tarefa: passe os dados que a função precisa.

O nome do parâmetro pode ser diferente do nome usado na chamada. O que importa é a posição e o valor enviado. A referência mantém nomes claros para facilitar a leitura.

Faça no seu exemplo

Em public/index.php, localize o bloco indicado. A referência completa acompanha esta etapa.

$totalDaOficina = 12;
$livres = restantes($totalDaOficina, 3);

Mude uma coisa e preveja

Troque somente totalDaOficina para 15.

Anote o que você acha que vai acontecer antes de salvar e recarregar.

Recarregue e confira

Livres passa a 12. A função continua com a mesma definição.

Se não acontecer

Se surgir variável indefinida dentro da função, use seus parâmetros total e ocupadas, como na referência.

A captura mostra um trecho da referência concluída. Abra e percorra o exemplo para conferir o restante. Experimentos temporários podem produzir outra aparência; restaure os valores indicados antes de comparar.

Atividades para fazer antes das respostas

Use uma nova cópia do exemplo. Tente aplicar o que aprendeu antes de consultar os comentários.

1. Calcule restantes para 8 e 2.

2. Explique a diferença entre definir e chamar.

3. Explique por que evitar global nesta tarefa.

Respostas comentadas

Compare sua explicação e o que realmente aconteceu. Outra solução pode funcionar se cumprir o objetivo e preservar o acesso ao conteúdo.

1. A chamada restantes(8, 2) retorna 6.

2. Definir registra a tarefa; chamar executa com os valores enviados.

3. Parâmetros deixam visíveis os dados necessários e tornam a tarefa mais fácil de testar.

Quando seguir

Você chama a função com novos dados e explica seu retorno. Se ainda precisa de ajuda, repita a experiência pequena antes de avançar.

O arquivo completo

Referência do exemplo 10-funcoes-parametros, reproduzida aqui para que você possa conferir sem sair da página.

public/index.php

<?php
declare(strict_types=1);
function restantes(int $total, int $ocupadas): int
{
    return $total - $ocupadas;
}
$totalDaOficina = 12;
$livres = restantes($totalDaOficina, 3);
?>
<!doctype html>
<html lang="pt-BR">
<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
<title>Livro de visitas de prática</title><link rel="stylesheet" href="estilos.css"></head>
<body><a class="pular" href="#conteudo">Pular para o conteúdo</a>
<header><p>Prática de PHP em pequenos passos</p><h1>Livro de visitas</h1>
<p>Conteúdo fictício. Somente neste computador.</p></header>
<main id="conteudo" tabindex="-1">
<h2>Uma tarefa com nome</h2><p>Vagas restantes: <?= $livres ?></p><p>Outro teste, 8 menos 2: <?= restantes(8, 2) ?></p>
</main><footer><p>Servidor de estudo em 127.0.0.1. Encerre com Ctrl+C.</p></footer></body></html>

public/estilos.css

* { box-sizing: border-box; }
body { margin: 0; background: #f4f7fb; color: #203246;
  font: 1.05rem/1.65 Arial, sans-serif; }
header, main, footer { max-width: 48rem; margin-inline: auto; padding: 1.5rem; }
header { padding-top: 2.5rem; }
h1 { font-size: clamp(1.8rem, 5vw, 2.7rem); line-height: 1.2; }
main { background: #fff; border-radius: .8rem; }
article { border-top: 1px solid #cad4df; padding-block: 1rem; }
a { color: #124e77; text-underline-offset: .2em; }
nav { display: flex; flex-wrap: wrap; gap: 1rem; }
label { display: block; font-weight: bold; }
input:not([type=hidden]), textarea { width: 100%; max-width: 34rem;
  border: 2px solid #718095; border-radius: .35rem; padding: .7rem;
  font: inherit; color: inherit; background: #fff; }
button { font: inherit; background: #124e77; color: white;
  border: 0; border-radius: .35rem; padding: .75rem 1.2rem; cursor: pointer; }
button:hover { background: #103b59; }
.mensagem { white-space: pre-wrap; overflow-wrap: anywhere; }
.erros { color: #8b142c; }
.ok { color: #175c30; font-weight: bold; }
:focus-visible { outline: 3px solid #b04d00; outline-offset: 3px; }
.pular { position: absolute; left: -10000px; }
.pular:focus { position: static; display: block; padding: 1rem; background: white; }
@media (max-width: 35rem) { header,main,footer { padding: 1rem; } }