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

Cada função do manual é documentada para uma referência rápida. E conhecendo como ler e entender o texto vai fazer aprender PHP muito mais facilmente. 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 PHP sendo uma linguagem fracamente tipada, é importante ter um básico entendimento dos tipos pois eles tem um importante significado.

Definições das funções nos dizem que tipo de valor é retornado. Vamos usar a definição do 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 de uma dada string.

**Explicação da definição da 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 é medida 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 o in_array(). O protótipo segue abaixo:

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

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 (needle não foi encontrado em haystack). O primeiro parâmetro é chamado needle e pode de ser de vários tipos, por isso nós dizemos que ele é "mixed". Esse needle mixed (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 default do parâmetro strict é o booleano FALSE. Veja a página de do manual de cada função para detalhes de como elas funcionam.

Existem funções com informações de versões do PHP mais complexas. Veja html_entity_decode() como um exemplo:

(PHP 4 >= 4.3.0, PHP 5)

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