Pratique de MySQL et PHP- P48 ppt

5.1 Choix des outils 213 5.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 W EBSCOPE. 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 ; 214 Chapitre 5. Organisation du développement 3. 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 *etv´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 5.1 Choix des outils 215 * @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 W EB- S COPE, 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 W EBSCOPE 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 216 Chapitre 5. Organisation du développement Ce 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 class Addition { public function ajout ($a , $b) { return $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. 5.1 Choix des outils 217 Exemple 5.2 exemples/PremierTest.php : Une seconde classe, qui teste la première <?php /∗∗ Test de la classe addition ∗ ∗ / require_once ( ’PHPUnit/Framework.php ’); require_once ("Addition.php"); class PremierTest extends PHPUnit_Framework_Testcase { public function testAjout() { $addition = new Addition() ; $this−>assertEquals (2, $addition−>ajout(1, 1)); $this−>assertNotEquals(3, $addition−>ajout (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 . 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. appelle la m´ethode connect() de la classe *etv´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 5.1. 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