Como interpretar la definición de una función (prototipo)

Cada función en el manual está documentada para obtener una referencia rápida. Si sabemos como leer e interpretar el manual será mucho más fácil aprender PHP. En lugar de confiar en ejemplos o copiar y pegar, todo el mundo debería saber como interpretar una definición de funciones (prototipos). Empecemos:

Nota: Prerrequisitos: Comprensión básica de los diferentes tipos

Aunque PHP es un lenguaje de programación relajado (en lo referente a los tipos de variables/valores), es importante entender, básicamente, estos diferentes tipos, ya que son importantes.

Las definiciones de funciones nos dicen que tipo de valores son valores de retorno. Usemos la definición de la función strlen() en nuestro primer ejemplo:

strlen

(PHP 4, PHP 5)
strlen -- Obtiene longitud de un string

Descripción
int strlen ( string $string )

Devuelve longitud de un string

**Explicación de la definición de una función**
Parte	Descripción
strlen	El nombre de la función.
(PHP 4, PHP 5)	strlen() está disponible en todas las versiones de PHP 4, PHP 5
int	Tipo de valor devuelto por esta función, en este caso un entero (ejemplo: la longitud de un string se mide en números).
( string $string )	El primer (sólo para este caso) parámetro o argumento para esta función se llama `string`, y es de tipo string.

Podríamos escribir la definición de esta función de un modo genérico:

      tipo de retorno    nombre función    ( tipo de parámetro   nombre parámetro )

Muchas funciones tiene múltiples parametros, por ejemplo in_array(). Su prototipo sería:

      boleano in_array ( mixto $aguja, array $pajar [, boleano $estricto = FALSE])

¿Qué significa? in_array() devuelve un valor booleano, TRUE si termina con éxito (Si la aguja fue encontrada en el pajar) o FALSE en caso de error (si la aguja no fue encontrada en el pajar). El primer parámetro se llama aguja y puede ser de muchos tipos, así que lo llamamos "mixto". Este mixtoaguja (que es lo que estamos buscando) bien puede ser un valor escalar (string, integer, o float), o un array. El pajar (el array en el que buscamos) es el segundo parámetro. El tercero es un parámetro opcional y lo llamamos estricto. Todos los parámetros opcionales están entre [ paréntesis ]. El manual muestra que el parámetro estricto es por defecto booleano FALSE. Vea la página del manual de cada función para informarse de cómo funcionan.

Además, el símbolo & (et) antepuesto a un parámetro de función permite que dicho parámetro sea pasado por referencia, como se muestra abajo:

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

En este ejemplo se puede ver que el tercer parámetro opcional &$matches será pasado por referencia.

También hay funciones con información PHP mucho más compleja. Toma html_entity_decode() como ejemplo:

(PHP 4 >= 4.3.0, PHP 5)

Esto significa que esta función solo está disponible desde la versión PHP 4.3.0.