Cómo leer la definición de una función (prototipo)

Cada función en el manual está documentada para permitir una comprensión rápida. Saber descifrar el texto facilitará su aprendizaje. En lugar de depender de ejemplos listos para copiar/pegar, es más útil saber leer la definición de una función (prototipo). Así es cómo:

Nota: Prerrequisitos: Conocimientos básicos de los tipos.

Aunque PHP es un lenguaje sin tipado fuerte, un conocimiento básico de los tipos es esencial, ya que tienen significados importantes.

Las definiciones de funciones indican qué tipo de datos es devuelto. Examinemos la función strlen() como ejemplo:

strlen

(PHP 4, PHP 5, PHP 7)
strlen -- Devuelve el tamaño de la cadena

Descripción
strlen ( string $string ) : int

Devuelve el tamaño de la cadena $string.

Explicaciones de la definición de la función

Parte	Descripción
strlen	El nombre de la función.
(PHP 4, PHP 5, PHP 7)	strlen() está presente en todas las versiones de PHP 4, 5 y 7.
( string $string )	El primer (y aquí el único) parámetro a proporcionar a esta función es el parámetro string, que debe ser del tipo string.
int	Tipo de valor devuelto por esta función, que es, en este caso, un int (es decir, el tamaño de una cadena se mide por un número).

Podríamos reescribir este prototipo con una versión más genérica:

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

Varias funciones necesitan varios parámetros, como in_array(). Su prototipo es el siguiente:

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

¿Qué significa esto? in_array() devuelve un booléano true en caso de éxito (el parámetro needle se encontró en el array haystack) o false si ocurre un error (el parámetro needle no se encontró en el array haystack). El primer parámetro se llama needle y puede ser de diferentes tipos: por lo tanto, lleva la mención mixed. El parámetro needle (lo que estamos buscando) puede ser un valor escalar ( string, int, o float), o incluso un array. haystack (el array, en el que estamos buscando) es el segundo parámetro. El tercer parámetro, opcional, strict, es opcional. Todos los parámetros opcionales tienen un valor por defecto; si el valor por defecto es desconocido, se muestra como ?. El manual indica que el parámetro strict vale por defecto false. Consulte el manual de cada función para saber cómo funciona.

Además, el signo & (e comercial) añadido al principio del parámetro de una función permite pasar este parámetro por referencia, como en este ejemplo:

       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 más compleja sobre las versiones de PHP. Tomemos html_entity_decode() como ejemplo:

(PHP 4 >= 4.3.0, PHP 5, PHP 7)

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