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.
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.