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, PHP 7) strlen -- Obtém o tamanho da string Descrição strlen ( string $string ) : int Retorna o tamanho da string dada.
Parte | Descrição |
---|---|
strlen | Nome da função. |
(PHP 4, PHP 5, PHP 7) | strlen() está disponível em todas as versões do PHP 4, 5 e 7 |
( string $string ) |
O primeiro (e neste caso, o único) parâmetro/argumento para esta
função é chamado string , e é uma
string.
|
int | Tipo do valor que esta função retorna, que é um int (isto é, o comprimento de uma string é medido em números). |
Poderíamos reescrever a definição da função acima de uma maneira genérica:
nome da função ( tipo do parâmetro nome do parâmetro ) : tipo retornado
Muitas funções recebem múltiplos parâmetros, tais como a função in_array(). Seu protótipo segue abaixo:
in_array ( mixed $needle, array $haystack , bool $strict = false ) : bool
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 têm valores
padrão (default). Se o valor padrão é desconhecido, então é mostrado um ?
. O exemplo
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:
preg_match ( string $pattern , string $subject , array &$matches = null, int $flags = 0 , int $offset = 0 ) : int|false
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, PHP 7)
Isto significa que esta função só está disponível a partir da versão PHP 4.3.0.