A instrução return em PHP

Suponha que temos uma função que exibe na tela o quadrado de um número passado:

php<?php
  function func($num) {
    echo $num * $num;
  }
  
  func(3); // exibirá 9
?>

Suponha que queremos não exibir o valor na tela, mas armazená-lo em uma variável, assim:

php<?php
  $res = func(3); // na variável $res agora temos 9
?>

Para isso, no PHP existe uma instrução especial return, que permite especificar o valor que a função retorna. A palavra retorna se refere ao valor que será armazenado na variável se a função chamada for atribuída a ela.

Então, vamos reescrever nossa função para que ela não exiba o resultado na tela, mas sim o retorne para a variável:

php<?php
  function func($num) {
    return $num * $num;
  }
?>

Agora vamos armazenar o resultado da função em uma variável:

php<?php
  $res = func(3);
?>

Depois que os dados são armazenados em uma variável, eles podem, por exemplo, ser exibidos na tela:

php<?php
  $res = func(3);
  echo $res; // exibirá 9
?>

Ou podemos primeiro modificar esses dados de alguma forma, e depois exibi-los na tela:

php<?php
  $res = func(3);
  $res = $res + 1;
  echo $res; // exibirá 10
?>

Também é possível realizar ações imediatas com o resultado da função antes de armazená-lo em uma variável:

php<?php
  $res = func(3) + 1;
  echo $res; // exibirá 10
?>

Podemos chamar nossa função várias vezes para números diferentes:

php<?php
  $res = func(2) + func(3);
  echo $res; // exibirá 13
?>

Podemos não armazenar o resultado em uma variável, mas sim exibi-lo imediatamente na tela:

php<?php
  echo func(3); // exibirá 9
?>