Utilisez la documentation PHP !

La documentation, c'est bien beau, mais c'est où ? Comment y accéder ?
Pour cela, on a 2 possibilités, tout dépend de ce que vous voulez faire :

• Voir la liste des fonctions classées par thème : si vous ne savez pas exactement quelle fonction vous cherchez, si vous voulez flâner un peu et que vous voulez avoir la liste des fonctions classées par catégories... C'est la première méthode que vous utiliserez.
• Accéder à la présentation d'une fonction dont on connaît le nom : si vous connaissez le nom d'une fonction, mais que vous ne savez pas vous en servir, c'est cette seconde méthode que l'on utilisera. C'est la méthode la plus simple, la plus rapide, et la plus fréquemment utilisée.

Je vais vous détailler maintenant chacune de ces méthodes pour accéder à la doc. Vous utiliserez l'une ou l'autre en fonction de vos besoins.

Liste des fonctions classées par thème

Vous devriez mettre cette adresse dans les favoris pour ne jamais l'oublier :


C'est le sommaire des fonctions PHP, en français.
Si vous vous rendez sur la page, vous devriez voir quelque chose qui ressemble à ceci :


Ce que vous voyez là, c'est la liste des "thèmes" de fonctions. Comme vous pouvez le voir, y'en a un sacré paquet
Ne prenez pas peur si vous ne comprenez même pas 1 thème sur 10 (parce que c'est pareil pour moi ). Mais faites l'effort de lire un peu tout ce qu'il y a, et repérez s'il y a un thème qui vous intéresse plus particulièrement qu'un autre.

Par exemple, sur le screenshot que j'ai pris ci-dessus, on peut voir les thèmes "Mail" et "Mathématiques" (c'est à peu près les deux seuls que je comprends ;))
Supposons que je sois intéressé par les fonctions mathématiques de PHP. Je clique sur "Mathématiques".

Là, une nouvelle page s'ouvre. On vous présente un peu le thème, il n'y a pas grand chose de très intéressant pour le moment.


Bon, les fonctions mathématiques sont toujours activées par défaut, donc pas de problème de ce côté-là.
Descendez plus bas dans la page (parfois vous devez descendre très très bas), jusqu'à l'endroit marqué "Table des matières". C'est là que ça nous intéresse : il y a la liste des fonctions du thème "mathématiques" :


A gauche, vous avez le nom de la fonction, et à droite un très bref descriptif de ce qu'elle fait.
Si vous cliquez sur un nom de fonction, vous accédez à la présentation de la fonction. Nous verrons comment fonctionne cette page dans la seconde partie de cette annexe.

Ici par exemple, je peux être intéressé par le calcul d'un logarithme népérien (fonction "log"). Et si les maths et vous ça fait deux, il y a quand même quelques fonctions qui devraient vous intéresser : max qui retourne le nombre le plus grand, ou mt_rand qui génère un nombre aléatoire.

Accès direct à une fonction

Il est fréquent que vous connaissiez le nom d'une fonction, mais que vous ne sachiez pas vous en servir.
Là, il n'est plus question de "flâner" parmi les thèmes de fonctions pour en repérer une intéressante : on veut aller directement aux explications sur cette fonction.

Par exemple, supposons que vous souhaitiez générer un nombre aléatoire entre 0 et 100. Vous avez beau être très fort en PHP, vous ne pouvez pas forcément savoir quelle est la fonction qui permet de le faire.
Ni une ni deux, vous vous rendez sur les forums du Site du Zér0 (:P) et vous posez la question.
Peu de temps après, quelqu'un vous répond juste "mt_rand".

Cette information est normalement suffisante, vous avez le nom de la fonction, vous allez vous documenter dessus.

Pour accéder directement à la présentation d'une fonction, tapez l'adresse suivante dans votre navigateur :



Si la fonction existe, vous tombez directement sur la présentation de la fonction (sinon, on vous dit que la fonction n'existe pas et on vous propose d'autres fonctions qui ont à peu près le même nom).

Si je veux tout savoir sur mt_rand donc, je tape ceci dans la barre d'adresse de mon navigateur :


Tapez ensuite "Entrée", et ni une ni deux, vous voici sur la page qui présente la fonction mt_rand !
Plutôt rapide et pratique non ?

Je suppose maintenant que vous avez repéré la fonction qui vous intéressait. 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 :


J'ai rajouté quelques commentaires pour que vous compreniez bien à quoi sert chaque ligne.
Ce qui nous intéresse le plus là-dedans, c'est le "Mode d'emploi de la fonction". 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 ceci :

int mt_rand ([ int min, int max])

Examinons toutes les infos qu'il y a là-dedans :

• 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é 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 dans le chapitre "Les Array II : le Retour", 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 librairie 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 entre 5 et 15 par exemple.

Cependant, il faut savoir que certains paramètres ne sont pas toujours obligatoires. Ces paramètres "facultatifs" sont mis entre crochets.



Tout à fait, d'ailleurs c'est écrit dans la doc :


Citation

Comme quoi, il suffit de lire

Un autre exemple : date

Bon time est un cas simple. Je vais maintenant vous montrer une fonction un peu plus compliquée que vous connaissez sûrement si vous avez lu le chapitre sur les Dates en PHP : date
Comme vous devez savoir le faire maintenant, rendez-vous sur php.net/date pour avoir la description de la fonction.

Le mode d'emploi indique ceci :


La fonction renvoie une chaîne de caractères (string) : c'est la date.
On doit lui donner obligatoirement une chaîne de caractère appelée "format" (pour demander le mois, l'année etc... vous vous souvenez ?)
Et il y a un int qui est facultatif : c'est le timestamp.

Si votre mémoire est encore fraîche, vous vous souvenez que date("Y"); renvoie l'année actuelle. Mais si vous rajoutez un timestamp (ce qui n'est pas obligatoire), alors c'est l'année correspondant au timestamp qui sera renvoyée.

Faites donc toujours bien attention : certains paramètres sont obligatoires, d'autres pas (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 qu'il 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 montrer les cas particuliers (où la fonction réagit un peu différemment)

Par exemple, pour mt_rand on a :


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