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

Cada função do manual é documentada para referência rápida, e conhecendo como ler e entender o manual fará com que a utilização do PHP seja muito mais fácil. Mais do que simplesmente estudar exemplos ou copiar e colar, todos poderiam saber como ler as definições de função (protótipos). Vamos começar:

Nota: Pré-requisito: Conhecimento básico dos tipos

Mesmo sendo o PHP uma linguagem fracamente tipada, é importante ter um conhecimento básico dos tipo pois eles tem um significado importante.

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

    
strlen

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

Description
int strlen ( string $string )

Retorna o comprimento de uma dada string.

**Detalhamento da definição da função**
Parte	Descrição
strlen	Nome da função.
(PHP 4, PHP 5)	strlen() está disponível em todos os PHP 4, PHP 5 e PHP 6
int	Tipo do valor que esta função retorna, que no caso é um integer (no caso, o comprimento de uma string é medida em números).
( string $string )	O primeiro (e neste caso, o único) parâmetro/argumento da função strlen() é chamado `string`, e é uma string.

Nos podemos reescrever a definição de função acima de maneira genérica:

      tipo retornado    nome da função    ( parametro tipo   parametro tipo )

Muitas funções tem parâmetros múltiplos, como in_array(). Seu protótipo é como:

      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.