Aller au menu - Aller au contenu

Icône Utilisez la documentation PHP !

Par Avatar Mathieu Nebra (M@teo21)
Mise à jour : 03/04/2010
Difficulté : Facile Facile Creative Commons BY-NC-SA
133 390 visites depuis 7 jours, dont 321 sur ce chapitre classé 2/786
Un des gros avantages en PHP, c'est sa documentation très complète, gratuite, disponible sur Internet, et traduite dans de très nombreuses langues (dont le français :D ).

Pourtant, quand quelqu'un nous dit "La solution à ton problème se trouve dans la doc", on a tendance à tremblotter un peu. On pense que la doc est une sorte de pavé mal construit, illisible, dans lequel on a toutes les chances de se perdre.
C'est un tort. Comme je vous l'ai dit, la documentation PHP est particulièrement complète et bien organisée, qui plus est traduite en français. Tout y est.

Certes, je ne vous cacherai pas que pour apprendre à programmer en PHP, la doc n'est pas ce qui se fait de plus accueillant. Mais lorsque vous commencez à réellement pratiquer le PHP, vous allez vite avoir besoin d'un support plus complet que ce cours (eh oui, la doc restera toujours plus complète que ce tutoriel ^^ ).

C'est là que la documentation entre en jeu. Le but de cette annexe est de vous montrer comment la doc fonctionne, pour que vous soyiez ensuite capables de trouver l'information que vous cherchez tous seuls, sans mon aide. ;)
Retour en haut
Sommaire du chapitre :
Icône du chapitre
Chapitre précédent Sommaire Chapitre suivant
Retour en haut

Accéder à la doc

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 :

http://www.php.net/manual/fr/funcref.php

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 :

Liste des fonctions classées par thème

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 ! :p
Ne prenez pas peur si vous ne comprenez même pas 1 thème sur 10 (je suis comme vous si ça peut vous rassurer), 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, vous pouvez y voir les thèmes "Mail" et "Mathématiques". 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 propose une petite introduction que je vous recommande de lire à chaque fois, ainsi que la liste des fonctions

Certains thèmes de fonctions ne sont pas activés avec PHP. C'est le cas par exemple de la librairie GD pour créer des images.
Si c'est le cas, on vous indique qu'il faut "activer" la librairie, comme je vous ai appris à le faire dans le chapitre sur la librairie GD.
D'autres fonctions appartiennent à des extensions qu'il faut installer manuellement.


En ce qui concerne les fonctions mathématiques, elles 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" :

Quelques fonctions 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 souhaite obtenir directement la description d'une fonction.

Par exemple, supposons que vous souhaitiez générer un nombre aléatoire entre 0 et 100. Vous savez que la fonction s'appelle mt_rand parce que quelqu'un en a parlé sur des forums.

Cette information est normalement suffisante, vous avez le nom de la fonction, vous n'avez plus qu'à vous documenter.

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

php.net/nom_de_la_fonction


Il est inutile d'écrire http://www. devant, il sera rajouté tout seul. C'est plus rapide de s'en passer.


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 :

Accès direct à la documentation depuis la barre d'adresse du navigateur


Lorsque vous validez cette adresse, vous arrivez directement sur la page qui présente la fonction mt_rand ! :D
Plutôt rapide et pratique non ? ^^
Retour en haut

Présentation d'une fonction

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 :

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 :

Code : Autre
1
2

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 :

Code : PHP
1
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é 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 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 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 :

Code : Autre
1

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 savoir le faire maintenant, rendez-vous sur php.net/date pour avoir la description de la fonction.

Le mode d'emploi indique ceci :

Code : PHP
1
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ère 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 int dé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 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 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 :

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. :)
Retour en haut
La documentation PHP est vraiment un outil précieux, bien fait (il faut dire ce qui est), mais pas forcément très "parlant".
Si, pour apprendre à se servir d'une fonction rien ne vaut un bon tuto, vous en arriverez forcément un jour à un stade où personne ne pourra vraiment vous aider, personne sauf la doc.

Apprenez dès aujourd'hui à vous en servir, car c'est grâce à elle que vous apprendrez le plus de choses une fois que vous aurez fini de lire les tutoriels du Site du Zéro. ;)
Chapitre précédent Sommaire Chapitre suivant
Retour en haut

Partager

Retour en haut
10 commentaires pour "Utilisez la documentation PHP !"
Note moyenne : 3.61 / 4 (2518 votes)
Pseudo Commentaire
Hors ligne mdodobe # Posté le 15/12/2009 à 16:31:49
Flux RSS
close

Ville : Bamako
Pays : Mali

 pouve me aide
<code type="css"></code><position valeur="centre"></position><flottant valeur="droite"></flottant><taille valeur="gros"></taille><couleur nom="bleu"></couleur><police nom="times"></police><attention></attention><information></information><question></question><erreur></erreur><math></math><titre1></titre1><titre2></titre2><secret></secret>null<image></image><citation></citation>
<barre></barre><souligne></souligne><italique></italique><gras></gras>
 
Hors ligne Extaze # Posté le 15/04/2010 à 14:35:23
I am You and what i see is Me
Avatar

Avis : Très bon

Ville : Maisons-laffitte
Pays : France métropolitaine

 Pour ceux qui voudrait "automatiser" la recherche de fonctions sur php.net, mettez ce lien en marque-pages:
Code : JavaScript
1
javascript:if(window.getSelection){var%20str='http://fr.php.net/'+window.getSelection();}else%20if(document.getSelection){var%20str='http://fr.php.net/'+document.getSelection();}else{var%20str='http://fr.php.net/'+document.selection.createRange().text;}document.location=str;

Puis, sélectionnez du texte sur la page, puis, faites un CTRL+Clic ;)
#LGDF: zingwai vaincra !
 
Hors ligne arnolem # Posté le 18/05/2010 à 12:02:10

Pour ceux que ça pourrais intéresser, il existe une extension Google Chrome permettant de rechercher dans la documentation PHP depuis un simple plugin.

Le plugin est téléchargeable depuis : https://chrome.google.com/extensions/d [...] gpiochncgdnhd

La news est ici : http://www.alsacreations.com/actu/lire [...] e-chrome.html
^^
Hors ligne G.Alex-713 # Posté le 19/07/2011 à 12:37:08
Gallae ex
Avatar

Ville : Paris
Pays : France métropolitaine

 Si la doc de Qt et SDL en C/C++ était aussi claire... *bave*
tt ceux qui viennent içi sachez que vous ne trouverez jamais plus clair que ça et profitez en parce qu'un jour vous voudrez faire de la programmation et vous vous retrouverez devant une doc en noir et blanc, pas claire du tout, en anglais et avec plein de trucs bizarres en peu partout...
Hors ligne Zazor # Posté le 18/03/2012 à 18:09:11

Avis : Mitigé

je ne comprend pas comment faire un espace membre avec tout sa et pourtant j'ai tout lu

Voir tous les commentaires