Comment lire la définition d'une fonction (prototype)

Chaque fonction dans le manuel est documentée pour permettre une compréhension rapide. Savoir décoder le texte rend l'apprentissage plus facile. Plutôt que de dépendre d'exemples prêts à copier/coller, il est plus utile de savoir lire la définition d'une fonction (prototype). Voici comment :

Note: Pré-requis : Connaissances de base des types.

Bien que PHP soit un langage sans typage fort, une connaissance de base des types est essentielle, car ils ont quand même des sens importants.

Les définitions de fonctions indiquent quel type de données est retourné. Examinons la fonction strlen() comme exemple :

strlen

(PHP 4, PHP 5, PHP 7)
strlen -- Retourne la taille de la chaîne

Description
strlen ( string $string ) : int

Retourne la taille de la chaîne $string.

Explications de la définition de la fonction

Partie	Description
strlen	Le nom de la fonction.
(PHP 4, PHP 5, PHP 7)	strlen() est présente dans toutes les versions de PHP 4, 5 et 7.
( string $string )	Le premier (et ici le seul) paramètre à fournir à cette fonction est le paramètre string, qui doit être du type chaîne de caractères.
int	Type de valeur retournée par cette fonction, qui est, en l'occurrence, un entier (c.-à-d. la taille d'une chaîne est mesurée par un nombre).

Nous pourrions réécrire ce prototype avec une version plus générique :

      nom de la fonction    ( type du paramètre   nom du paramètre ) : type de retour

Plusieurs fonctions ont besoin de plusieurs paramètres, comme in_array(). Son prototype est le suivant :

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

Qu'est-ce que cela signifie ? in_array() retourne un booléen true en cas de réussite (le paramètre needle a été trouvé dans le tableau haystack) ou false si une erreur survient (le paramètre needle n'a pas été trouvé dans le tableau haystack). Le premier paramètre s'appelle needle et il peut être de différents types : il porte donc la mention mixed. Le paramètre needle (ce que nous recherchons) peut être une valeur scalaire ( chaîne de caractères, entier, ou float), ou encore un array. haystack (le array, dans lequel nous recherchons) est le second paramètre. Le troisième paramètre, optionnel, strict, est optionnel. Tous les paramètres optionnels ont une valeur par défaut ; si la valeur par défaut est inconnue, elle est affichée en tant que ?. Le manuel indique que le paramètre strict vaut par défaut false. Se reporter au manuel de chaque fonction pour savoir comment elle fonctionne.

De plus, le signe & (é commercial) ajouté au début du paramètre d'une fonction permet de passer ce paramètre par référence, comme ceci :

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

Dans cet exemple, nous pouvons voir que le troisième paramètre optionnel &$matches va être passé par référence.

Il y a aussi des fonctions avec des informations plus complexes concernant les versions de PHP. Prenons html_entity_decode() comme exemple :

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

Cela signifie que cette fonction n'est disponible qu'à partir de PHP 4.3.0.