Como ler uma definição de função (protótipo)

Cada função no manual é documentada para uma referência rápida. Saber como ler e entender o texto tornará a aprendizagem do PHP muito mais fácil. Mais do que simplesmente estudar exemplos ou copiar/colar, todos deveriam saber como ler as definições de funções (protótipos). Vamos começar:

Nota: Pré-requisito: Entendimento básico de tipos

Mesmo o PHP sendo uma linguagem fracamente tipada, é importante ter um entendimento básico dos tipos pois eles têm um importante significado.

Definições das funções nos dizem que tipo de valor é retornado. Vamos usar a definição da função strlen() como nosso primeiro exemplo:

strlen

(PHP 4, PHP 5)
strlen -- Obtém o tamanho da string

Descrição
int strlen ( string $string )

Retorna o tamanho da string dada.

Explicação de uma definição de função
Parte Descrição
strlen Nome da função.
(PHP 4, PHP 5) strlen() está disponível em todas as versões do PHP 4 e PHP 5
int Tipo do valor que esta função retorna, que é um integer (isto é, o comprimento de uma string é medido em números).
( string $string ) O primeiro (e neste caso, o único) parâmetro/argumento para esta função é chamado string, e é uma string.

Poderíamos reescrever a definição da função acima de uma maneira genérica:

      tipo retornado    nome da função    ( tipo do parâmetro   nome do parâmetro )

Muitas funções recebem múltiplos parâmetros, tais como a função in_array(). Seu protótipo segue abaixo:

      bool in_array ( mixed $needle, array $haystack [, bool $strict = FALSE ] )

O que isso significa? in_array() retorna um valor booleano, TRUE em caso de sucesso (se needle foi encontrado em haystack) ou FALSE em caso de falha (se needle não foi encontrado em haystack). O primeiro parâmetro é chamado needle e pode de ser de vários tipos diferentes, por isso nós o chamamos "mixed" (misto). Esse needle mixed (o que nós estamos procurando) pode ser tanto um valor escalar (string, inteiro, ou float) ou um array. haystack (o array onde nós estamos procurando) é o segundo parâmetro. O terceiro parâmetro opcional é chamado strict. Todos os parâmetros opcionais aparecem dentro de [ colchetes ]. O manual diz que o valor padrão do parâmetro strict é o booleano FALSE. Veja a página do manual de cada função para detalhes de como elas funcionam.

Além do mais o símbolo & (ampersand, e comercial) antes de um parâmetro de função permite ao parâmetro ser passado por referência, como no exemplo abaixo:

       int preg_match ( string $pattern , string $subject [, array &$matches
      [, int $flags = 0 [, int $offset = 0 ]]] )

Neste exemplo podemos ver que o terceiro parâmetro opcional &$matches será passado por referência.

Existem também funções com informações de versões do PHP mais complexas. Tome como exemplo html_entity_decode():

(PHP 4 >= 4.3.0, PHP 5)

Isto significa que esta função só está disponível a partir da versão PHP 4.3.0.