5.1.3 Production d’une documentation avec PhpDocLa communauté des développeurs PHP a produit de nombreux outils pour constituer des environnements logiciels de qualité.. Documenter du PH
Trang 15.1.3 Production d’une documentation avec PhpDoc
La communauté des développeurs PHP a produit de nombreux outils pour constituer des environnements logiciels de qualité Ces outils contribuent à faire de PHP un concurrent tout à fait présentable de langages anciens et éprouvés comme C++ ou Java La possibilité de produire une documentation directement à partir du code fait partie de ces acquis Dans le monde PHP, l’outil qui semble le plus utilisé est
PhpDocumentor http://www.phpdoc.org/ et c’est donc celui que je présente ensuite Cela étant des logiciels plus généralistes comme doxygen, qui s’applique également
au C, au C++, à Java et à beaucoup d’autres langages, produisent également un très beau travail
Documenter du PHP pour PhpDoc
PhpDoc produit un site HTML statique contenant une description technique extraites des fichiers PHP d’une application web La figure 5.5 montre un exemple d’une page PhpDoc produite automatiquement pour le site WEBSCOPE
Figure 5.5 — Exemple de page produite par PhpDoc
La documentation est basée sur la notion de DocBlock qui sert à documenter des
« éléments » du code Les éléments sont les fonctions, les variables, les classes, et tous les composants logiciels d’une application PHP Chaque DocBlock est simplement un commentaire de la forme /** */ (notez les deux étoiles initiales) constitué de trois parties aparaissant dans l’ordre suivant :
1 une description courte ;
2 une description longue ;
Trang 23 des balises choisies parmi un ensemble pré-défini et décrivant un des aspects
de l’élément documenté (par exemple, la balise @author indique l’auteur de l’élément)
La stratégie utilisée pour la documentation varie selon le type d’élément docu-menté Pour faire simple, limitons-nous ici au cas des classes PHP orientées-objet On peut les documenter à deux niveaux : la classe et la méthode (on pourrait envisager trois niveaux si on mettait plusieurs classes dans une page) Voici quelques exemples
de balises utiles dans ce contexte
• @category est le nom de l’application ;
• @package est une notion correspondant à un regroupement de classes parta-geant un même objectif (par exemple toutes les classes interagissant avec la base de données) ;
• @copyright est le nom du titulaire de la propriété intellectuelle ;
• @license est la licence d’exploitation ;
• @version est le numéro de version
Voici un exemple de DocBlock pour la classe BD de notre application
/**
* Classe abstraite d´ efinissant une interface g´ en´ erique d’acc` es ` a une BD
*
* Cette classe d´ efinit les m´ ethodes g´ en´ eriques d’acc` es ` a une base de donn´ ees
* quel que soit le serveur utilis´ e Elle est abstraite et doit ^ etre sp´ ecialis´ ee
* pour chaque syst` eme (MySQL, Oracle, etc.)
*
* @category Pratique de MySQL et PHP
* @package BD
* @copyright Philippe Rigaux
* @licence GPL
* @version 1.0.0
*/
Au niveau des méthodes, on peut ajouter la description du type et du rôle de chaque paramètre, ainsi que le type de la valeur retournée Les paramètres sont marqués par la balise @param, suivi du type et d’une phrase qui décrit le paramètre
La balise @tag suit a même convention Voici un exemple, toujours tiré de la classe BD
/**
* Constructeur de la classe
*
* Le constructeur appelle la m´ ethode connect() de la classe
* et v´ erifie que la connexion a bien ´ et´ e ´ etablie Sinon une
* exception est lev´ ee.
*
* @param string Login de connexion
* @param string mot de passe
Trang 3* @param string nom de la base
* @param string nom du serveur
* @return null
*/
function construct ($login, $mot_de_passe, $base, $serveur)
{
}
La production de cette documentation technique est particulièrement utile pour les bibliothèques, classes et fonctions utilitaires fréquemment appelées et pour les-quelles une description des modes d’appel est indispensable
Comment utiliser PhpDoc
PhpDoc s’installe très simplement comme une application PHP Récupérez sur
http://www.phpdoc.org/ le fichier archive et décompressez-le dans le répertoire htdocs.
Renommez le nouveau répértoire obtenu en phpdoc Vous pouvez maintenant y accéder à http://localhost/phpdoc.
Si vous voulez documenter une application, par l’exemple l’application WEB
-SCOPE, le plus simple, pour éviter de saisir systématiquement les paramètres de production de la documentation, est de créer un fichier de configuration à placer
dans users/ dans le répertoire phpdoc À titre d’illustration, voici un fichier de
confi-guration minimal permettant d’analyser l’application web WEBSCOPE et de placer
la documentation générée dans wsdoc.
;Titre g´ en´ eral
title = Documentation WebScope
;; Quelle est l’application ` a documenter
directory = /Applications/MAMP/htdocs/webscope
;; O` u ´ ecrire la documentation?
target = /Applications/MAMP/htdocs/wsdoc
;;Doit-on consid´ erer les fichiers cach´ es?
hidden = false
;; Doit-on montrer les ´ el´ ements priv´ es? (@access private)
parseprivate = off
;; Quel est le package principal?
defaultpackagename = WebScope
;; Fichiers ` a ignorer
ignore = *.tpl
;; Style de la documentation
output=HTML:Smarty:HandS
Trang 4Ce fichier de configuration apparaît alors dans la liste des choix quand on accède
à la page de configuration de PhpDoc Il ne reste plus ensuite qu’à l’afficher avec le navigateur web PhpDoc peut également engendrer d’autres formats, et notamment
le format DocBook qu’on peut ensuite transformer en PDF Toutes les documenta-tions techniques des composants PHP Open Source sont créées de cette manière (mais pas toujours avec PhpDoc, car, comme signalé ci-dessus, des logiciels comme
doxygen font un travail au moins équivalent et valent la peine d’être étudiés).
5.1.4 Tests unitaires avec PhpUnit
Vous devez bien entendu tester vos développements et vous assurer de leur correc-tion, en toutes circonstances Le test est une tâche fastidieuse mais nécessaire pour une production de qualité Le contrôle et la certification du logiciel constituent un
sujet extrêmement vaste Une première étape consiste à effectuer des test unitaires afin
de contrôler les briques de base d’une application, si possible de façon automatique
L’outil de test unitaire pour PHP s’appelle PhpUnit et constitue la déclinaison
pour PHP de JUnit (pour Java) ou CppUnit (pour C++) Son site d’accueil est
http://www.phpunit.de Ce qui suit constitue une brève introduction à son utilisation.
Il faut commencer par installer PhpUnit Le site donne deux procédures
d’ins-tallation : la première avec pear, un gestionnaire de composants PHP, la seconde par téléchargement et configuration Si pear n’est pas installé dans votre environnement,
suivez simplement les instructions sur le site de PHPUnit pour une installation directe
Dans les deux cas, on se retrouve avec un script PHP phpunit qui s’exécute en
ligne de commande (pas d’interface web) Commençons par un exemple trivial Nous avons créé une classe Addition avec une méthode ajout() dont le but est d’ajouter deux nombres Le code n’est pas trop compliqué :
Exemple 5.1 exemples/Addition.php:Une classe sans intérêt, mais à tester quand même
<? php
c l a s s A d d i t i o n {
p u b l i c f u n c t i o n a j o u t ( $a , $b )
{
r e t u r n $a + $b ;
}
}
? >
Maintenant nous allons créer un second script PHP qui va tester le premier Comme il s’agit d’un cas fictif, les deux scripts sont dans le répertoire de nos exemples, mais en général il faut bien entendu imaginer que l’application de test est séparée de celle qui est testée
Trang 5Exemple 5.2 exemples/PremierTest.php:Une seconde classe, qui teste la première
<? php
/ ∗ ∗ T e s t de l a c l a s s e a d d i t i o n
∗
∗ /
r e q u i r e _ o n c e ( ’ PHPUnit / Framework php ’ ) ;
r e q u i r e _ o n c e ( " A d d i t i o n php " ) ;
c l a s s P r e m i e r T e s t e x t e n d s P H P U n i t _ F r a m e w o r k _ T e s t c a s e {
p u b l i c f u n c t i o n t e s t A j o u t ( ) {
$ a d d i t i o n = new A d d i t i o n ( ) ;
$ t h i s−> a s s e r t E q u a l s ( 2 , $ a d d i t i o n −>a j o u t ( 1 , 1) ) ;
$ t h i s−>a s s e r t N o t E q u a l s ( 3 , $ a d d i t i o n −>a j o u t ( 2 , 2) ) ;
}
}
? >
La simplicité de l’exemple a le mérite de le rendre assez clair La classe de test instancie un objet de la class testée, exécute une méthode et effectue des contrôles sur le résultat obtenu On vérifie ici que 1 + 1 = 2 et que 2 + 2= 3 Il reste à lancer
le script phpunit sur cette classe de test.
> phpunit PremierTest
PHPUnit 3.3.1 by Sebastian Bergmann.
.
Time: 0 seconds
OK (1 test, 2 assertions)
Tout s’est bien passé Voici maintenant quelques explications PHPUnit s’appuie sur des conventions de nommage consistant à donner aux classes de test un nom se terminant par Test et aux méthodes de test un nom commençant par test La classe
de test ne doit pas être située dans le même répertoire que l’application : le but est
de lancer une application (de test) qui travaille sur une autre application (normale), cette dernière ne devant pas subir la moindre modification
Une classe de test hérite de PHPUnit_FrameworkTestCase Ce faisant elle
dispose de tout un ensemble d’assertions et de mécanismes pour exécuter les tests.
Le script phpunit reçoit le nom de la classe de test et exécute chacune des méthodes
de test À l’intérieur de chaque méthode de test, on place une liste d’assertions exprimant ce que le code testé doit faire et quels résultats il doit fournir Dans notre exemple trivial, on vérifie les résultats de deux additions Dans un exemple plus réaliste, il faut inclure toutes les assertions exprimant ce qui doit caractériser selon