Télécharger la documentation pour une utilisation en local.

Pour parler clairement (pour ceux qui ne sont pas habitués à lire autant de mots en une seule fois), télécharger et enregistrer la documentation sur son disque dur, ou encore en 1337 5p34k ce qui donne (si je ne me trompe pas) 7313[|-|4|293|2 37 3|\||239!$7|23|2 14 |)()[(_)|v|3|\|747!()|\| $(_)|2 $()|\| |)!$(,)(_)3 |)(_)|2. Pour la suite de l'exposé, je vais continuer avec du français de base, ce qui ne comprennent pas sont priés d'utiliser un dictionnaire.
La documentation officielle de PHP est disponible, comme il se doit, sur le site même et tout aussi officiel de PHP soit PHP.net. Il suffit de cliquer sur le menu documentation (mot qui a la bonne idée de s'écrire de la même façon en français et en anglais et qui en plus garde le même sens), ce qui nous fait arriver sur cette page (remarque : le cas de la documentation en ligne sera traité plus plus loin).
Pour télécharger la documentation il faut cliquer sur documentation downloads ce qui nous fait enfin arriver sur la page de téléchargement multiformats. Je pense que vous allez utiliser la documentation en français. Et là, c'est affaire de goût :

  • soit vous préférez utiliser un fichier HTML unique de 1807Kb ce qui risque de provoquer des ralentissements si vous disposez d'une machine peu puissante,
  • soit vous préférez plusieurs fichiers HTML,
  • soit enfin vous préférez utiliser le format chm (plus de détail sur ce format pour les curieux). Il me semble qu'il s'agit du meilleur choix, même si c'est le fichier le plus gros des trois à télécharger. Le format CHM est lu sans problème sous windows, mais également sous linux, notamment grâce à l'utilisation du paquet gnochm.

Quel que soit le type de fichier choisi, en cliquant sur son lien, vous vous retrouverez sur une seconde page demandant depuis quel serveur vous souhaitez le télécharger. Normalement le site indique en haut de page le serveur (ou miroir) le plus approprié. Il suffit de cliquer et le téléchargement se lance. Les archives HTML sont au format .tar.gz, ce qui ne devrait pas poser de problème aux linuxiens, ni aux windowsiens s'ils ont un vrai logiciel de décompression.
Vous voilà prêt à effectuer des recherches dans cette documentation soit en parcourant les chapitres, soit en utilisant les utilitaires de recherche de votre navigateur internet (si vous avez téléchargés au format HTML) ou du logiciel de lecture du format CHM.

Utiliser la documentation en ligne.

On réalise les étapes précédentes mais en s'arrêtant à cette page. Le lien intitulé french renvoie vers la documentation du site PHP.net même et le lien special french renvoie sur le site de nexen. Là encore c'est une question de goût : moi je préfère rester sur le site officiel donc je ne vous parlerai que de celui-ci.
En cliquant sur french donc, vous arrivez sur cette page qui est, comme par miracle, normalement déjà en français. Si ce n'est pas le cas, regardez l'adresse de cette page dans votre butineur et enlevez le en présent en le remplaçant par fr et surtout, acceptez tous les cookies envoyés par PHP.net. Ainsi, en revenant ultérieurement sur ce site, vous serez automatiquement dirigés vers la documentation en français.

Voilà, on est devant une page de documentation, mais ce n'est pas pratique de faire des recherches dedans comme ça, par contre c'est très pratique pour consulter les différents chapitres. C'est alors que vous apercevez qu'en haut à droite de la page du site il y a un formulaire, et même que ce formulaire est présent dès la page d'accueil. Superbe transition qui me permet d'écrire un nouveau paragraphe.

Utiliser le formulaire en ligne de PHP.net

Le formulaire se décompose en deux champs :

  • le premier, un champ input de type texte dans lequel vous saisissez ce que vous voulez,
  • le second, une liste de sélection qui donne le choix entre function list (rechercher dans la liste des fonctions de PHP), whole site (rechercher sur tout le site), online documentation en (rechercher dans la documentation en ligne mais disponible en langue anglaise seulement), bug database (rechercher dans la base de données des bugs répertoriés), et enfin trois autres choix que je n'aborde pas car si vous êtes débutants, vous n'en avez aucune utilité : general mailing list, developer mailing list, documentation mailing list.

Exercice pratique : vous souhaitez connaître les caractéristiques de la fonction echo :

  • sélectionnez function list dans la liste de droite,
  • tapez echo dans la boite de formulaire de gauche,
  • appuyez sur la touche Entrée
  • vous devez être sur la page de documentation de la fonction echo affichée en français.

Simple non?

Alors un peu de fun maintenant, car en procédant comme précédemment, on est obligé d'aller sur le site de PHP.net et ça c'est mal car ça fait perdre du temps pour un développeur :)

Créer un plugin de recherche sur PHP.net

Dans un précédant billet, j'avais exposé comment modifier un plugin de recherche pour Mozilla Firefox (tm) concernant MySQL. Nous allons suivre la même méthode mais pour en créer très simplement un pour effectuer une recherche en français sur PHP.net.

Repérage des variables du formulaire du site de php.net

le code correspondant au formulaire sur la page d'accueil de PHP.net est le suivant :


<form method="post" action="/search.php" class="thin" name="topsearch">
  <input type="hidden" name="lang" value="fr" />
  <input class="small" type="text" name="pattern" value="" size="30" accesskey="s" />
  <select name="show" class="small">
   <option value="quickref" selected="selected">function list</option>
   <option value="wholesite">whole site</option>
   <option value="manual">online documentation en</option>
   <option value="bugdb">bug database</option>
   <option value="maillist">general mailing list</option>
   <option value="devlist">developer mailing list</option>
   <option value="phpdoc">documentation mailing list </option>
  </select>
  <input type="image" src="http://static.php.net/www.php.net/images/small_submit_white.gif" alt="search" align="bottom" />
</form>

Ce qui nous intéresse est :

  • la variable lang qui doit avoir la valeur fr,
  • la variable show qui peut prendre la valeur quickref car nous voulons rechercher dans la liste des fonctions de PHP ,ou wholesite... selon ce que vous voulez faire. Vous pouvez ainsi faire plusieurs fichiers de recherche si vous le désirez,
  • et bien sur l'attribut action du formulaire qui a pour valeur /search.php.
Création du fichier phpfr.src

#phpfr.src
<search
  version="7.1"
  name="PHP.net"
  action="http://www.php.net/search.php"
  searchForm="http://www.php.net/search.php
  method="GET">

    <input name="pattern" user>
    <input name="show" value="quickref">
    <input name="lang" value="fr">
    <interpret
       resultListStart="<div id=\"main\">"
       resultListEnd="</div>"
       resultItemStart="<div class=\"infos\">"
       resultItemEnd="</div></div>"
    >
</search>
Enregistrement manuel de ce fichier

On l'enregistre, comme indiqué dans la documentation soit dans /usr/lib/Mozilla/searchplugins ou encore /usr/lib/firefox-1.0.4/searchplugins/ (plusieurs possibilités selon votre système) sous linux, ou encore C:\Program Files\Mozilla.org\Mozilla\searchplugins\ sous windows... on redémarre éventuellement le navigateur et hop, miracle, en tapant echo dans la sidebar de recherche ça fonctionne.

Super, je sais chercher mais je ne sais pas quoi chercher car je ne connais pas le nom de la fonction à utiliser !

Savoir chercher dans la documentation

Là il s'agit d'un simple problème de logique et de méthode. C'est là qu'on se rend compte que ceux qui disent que pour programmer en PHP c'est facile il n'y a pas besoin de savoir programmer ont faux, en tout cas partiellement, car il faut un minimum de logique. C'est là également qu'on voit si vous comprenez ce que vous faites : si vous n'êtes pas capable d'exprimer clairement votre problème, alors il vaut mieux arrêter le PHP, mais si vous êtes capables d'exprimer votre problème, c'est que vous avez parfaitement compris le message d'erreur éventuel ou que vous savez exactement ce que vous voulez faire, et là, bien souvent, la réponse on la trouve tout seul (même si un coup de pouce ne fait jamais de mal, sous réserve d'avoir effectué des recherches sérieuses avant de poser sa question).

Exemple de problème : "existe t il un fonction qui revoit un true ou un false sur une chaîne qui serais numérique ?"

Et bien on utilise le formulaire de PHP.net (par exemple) on tape numérique dedans et on arrive à une liste de fonctions proposées. Là on se souvient qu'en anglais numérique s'écrit numeric et on voit qu'il y a une fonction is_numeric signifiant est numérique. Il suffit de cliquer et le tour est joué.

Autre difficulté : "j'ai un problème avec les headers (), je reçois le message d'erreur suivant : Warning: Cannot modify header information - headers already sent by (output started at /home/...conf.php:29) in /home/.../login.php on line 17"

Bon ben là il suffit d'aller voir la fonction header() dans la documentation (oui je n'ai pas mis le lien volontairement). Si on prend la peine de lire au delà des 3 premières lignes on tombe sur l'information suivante : N'oubliez jamais que header() doit être appelée avant que le moindre contenu ne soit envoyé, soit par des lignes HTML habituelles dans le fichier, soit par des affichages PHP.' Cela signifie que si on n'envoie quoi que ce soit au navigateur (espace, code html, utilisation des fonctions PHP require ou include..) il y aura une erreur... comme quoi la solution est simple.

Après, à force d'avoir effectué des recherches en s'acharnant, sinon on n'arrive à rien, on se rendra compte que certaines pages telles que la page Liste des token de l'analyseur et Variables pré-définies sont extrêmement utiles, car on y trouve la solution à une grande majorité des questions posées sur un forum.

Si vous avez bien lu ce billet, vous savez utiliser la documentation pour retrouver le nom d'une fonction qui vous intéresse, ou la signification d'un message d'erreur. Par contre, si vous cherchez un script tout fait, Google est là pour vous :). Vous avez également pu vous rendre compte que PHP, comme tout langage de programmation d'ailleurs, nécessite de posséder quelques bases d'anglais à la portée de tous ceux qui se donnent la peine de fournir des efforts.