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, PHP 7)
strlen -- Obtiene longitud de un string

Descripción
strlen ( string $string ) : int

Devuelve la longitud del string dado.

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

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

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

      in_array ( mixed $needle, array $haystack , bool $strict = false ) : bool

¿Qué significa? in_array() devuelve un valor boolean, true si termina con éxito (Si la needle fue encontrada en el haystack) o false en caso de error (si la needle no fue encontrada en el haystack). El primer parámetro se llama needle y puede ser de muchos tipos, así que lo llamamos "mixed". Este mixed needle (que es lo que estamos buscando) bien puede ser un valor escalar (string, integer, o float), o un array. El haystack (el array en el que buscamos) es el segundo parámetro. El tercero es un parámetro opcional y lo llamamos strict. 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:

       preg_match ( string $pattern , string $subject , array &$matches = null,
       int $flags = 0 , int $offset = 0 ) : int|false

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, PHP 7)

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