Présentation d'une fonction



Je suppose maintenant que vous avez repéré la fonction qui vous intéresse. Vous tombez alors sur la page de présentation de la fonction.
On va prendre le cas de la fonction mt_rand : faites comme je vous ai dit plus haut pour accéder directement à la page concernant cette fonction.

La page de présentation d'une fonction a toujours la même forme, celle de la figure suivante.



Présentation de la fonction mt_rand



Ce qui nous intéresse le plus là-dedans, c'est le « mode d'emploi de la fonction ». Il correspond à ces lignes :

int mt_rand ( void )

int mt_rand ( int $min, int $max )


Ces lignes décrivent le mode d'emploi de mt_rand. Je vais vous apprendre à le déchiffrer, car lorsque vous saurez le lire, vous saurez utiliser n'importe quelle fonction PHP à l'aide de la doc' !


Apprendre à lire un mode d'emploi


Ici, le mode d'emploi indique qu'il y a deux façons d'utiliser la fonction : avec ou sans paramètres. Prenons le cas avec paramètres, plus complexe :

int mt_rand ( int $min, int $max )


Examinons toutes les infos que cet extrait de code renferme.

  • int : la fonction commence par le mot-clé int. Ce premier mot-clé indique ce que renvoie la fonction. On peut avoir entre autres les mots-clés suivants :
    • int : cela signifie que la fonction renvoie un nombre entier. mt_rand renvoie donc un nombre entier (-8, 0, 3, 12, etc.) ;
    • float : la fonction renvoie un nombre décimal (comme 15.2457) ;
    • number : la fonction renvoie un nombre qui peut être soit un entier (int) soit un décimal (float) ;
    • string : la fonction renvoie une chaîne de caractères, c'est-à-dire du texte. Par exemple « Bonjour » ;
    • bool : la fonction renvoie un booléen, c'est-à-dire vrai ou faux (true ou false) ;
    • array : la fonction renvoie un array (tableau de variables). Le plus simple en général, c'est de faire un print_r, comme je vous l'ai appris, pour voir tout ce que contient cet array ;
    • resource : la fonction renvoie une « ressource ». Une ressource est un type de données particulier, une sorte de super-variable. Il peut s'agir d'une image, d'un fichier, etc. Dans le chapitre sur la bibliothèque GD par exemple, on manipule une variable $image ;
    • void : la fonction ne renvoie rien du tout. C'est le cas des fonctions qui ne servent qu'à faire une action et qui n'ont pas besoin de renvoyer d'information ;
    • mixed : la fonction peut renvoyer n'importe quel type de données (un int, un string, ça dépend…).
  • mt_rand : là c'est tout simple, c'est le nom de la fonction.
  • (int $min, int $max) : entre parenthèses, il y a la liste des paramètres que l'on peut donner à la fonction. Ici, on peut donner deux entiers (int) : min et max. Ils servent à indiquer que vous voulez un nombre aléatoire compris entre 5 et 15 par exemple. La signification des paramètres est expliquée dans la section « Liste des paramètres » de la page.


Il est aussi possible d'appeler la fonction sans aucun paramètre, c'est ce que signifie la ligne suivante :

int mt_rand ( void )


Mais alors… Qu'est-ce que ça signifie si on n'envoie aucun paramètre ? Que va faire la fonction ?


C'est écrit sur la page :


Citation

Appelée sans les arguments optionnels min et max, mt_rand() retourne un nombre pseudo-aléatoire, entre 0 et RAND_MAX (un nombre maximum fixé par PHP). Pour obtenir un nombre entre 5 et 15 inclus, il faut utiliser mt_rand(5,15).

Comme quoi, il suffit de lire. ;-)


Un autre exemple : date

Comme vous devez maintenant savoir le faire, rendez-vous sur date pour avoir la description de la fonction.


Le mode d'emploi indique ceci :

string date ( string $format [, int $timestamp])


La fonction renvoie une chaîne de caractères (string) : c'est la date.
On doit lui donner obligatoirement une chaîne de caractères appelée format (pour demander le mois, l'année, etc. vous vous souvenez ?).


On notera qu'il y a un second paramètre entre crochets, ce qui signifie qu'il est facultatif. Il s'agit d'un intdénommé timestamp. Pour savoir ce qu'il signifie, lisez la description des paramètres.

Faites donc toujours bien attention : certains paramètres sont obligatoires, d'autres non (ils sont entre crochets), et la fonction réagit différemment selon les cas. En général, le texte descriptif de la fonction vous explique ce qui se passe si vous ne mettez pas les paramètres facultatifs.


Lisez les exemples !


Il y a toujours des exemples pour illustrer l'utilisation de la fonction. C'est très pratique car on vous montre de quelle manière utiliser la fonction, et on n'hésite pas à vous faire découvrir les cas particuliers où la fonction réagit un peu différemment.

Par exemple, pour mt_rand on a ce qui se trouve sur la figure suivante.



Exemples d'utilisation de mt_rand



Dans la mesure du possible, essayez de tester les exemples proposés. Il arrive souvent qu'on comprenne mieux avec des exemples que l'on essaie soi-même.

Créé avec HelpNDoc Personal Edition: Maximisez la protection de vos PDF en suivant ces étapes simples