Retrouvez cet article dans : Linux Magazine 101

Dans cet article, je vous présente PHPCheckstyle, un outil permettant de vérifier que votre code PHP respecte bien les conventions de codage que vous avez pu établir. En parallèle, je vous présenterai PHP_Beautifier, une bibliothèque PHP permettant de programmer des scripts de reformatage de code.

Lorsque l’on développe une application, et d’autant plus en équipe, il est essentiel d’avoir un code homogène. Pour cela, la première des choses à faire est de définir une convention de codage... mais l’erreur est humaine et il est possible de passer outre certaines règles. PHPCheckStyle est un outil permettant de vérifier que votre code respecte bien les conventions de codage que vous aurez définies au préalable en indiquant vos erreurs et leurs solutions dans un fichier HTML. S’adressant à la communauté des développeurs PHP, il a été basé sur la convention de codage PEAR [1] et pourra être adapté, dans une certaine mesure, en fonction des besoins. Si vous devez reprendre le développement d’un projet n’ayant suivi aucune convention de codage, PHPCheckStyle vous indiquera de nombreuses « erreurs ». Vous pourrez alors avoir besoin d’un outil de reformatage de code tel que PHP_Beautifier. Dans cet article, nous verrons comment utiliser et paramétrer ces deux outils.

1. De l’intérêt des conventions de codage

Avant d’entrer dans le vif du sujet, je voudrais souligner l’importance de définir (et bien sûr de respecter) des conventions de codage, et ce, d’autant plus, dans un langage permissif tel que le PHP. Pour beaucoup de gens, il peut sembler inutile ne serait-ce que d’indenter de manière très stricte leur code. Plutôt que d’essayer de vous convaincre à grand renfort d’arguments sur la lisibilité et la maintenabilité, il me semble plus simple de vous proposer un exemple de code totalement déstructuré.

01: <?php
02: $tab=array(‘A’=>5,’B’=>2,’C’=>7,’D’=>array(‘cle1’=>’A’,’cle2’=>’B’,’cle3’=>’C’));
03: for($i=0;i<10;$i++)
04: if ($tab[$tab[‘D’][‘cle2’]]==$i) echo ‘Trouvé !’;
05: ?>

Voici le même code correctement indenté :

	01: <?php
02:
03:   $tab = array(
04:     ‘A’ => 5,
05:     ‘B’ => 2,
06:     ‘C’ => 7,
07:     ‘D’ => array(

	08:              ‘cle1’ => ‘A’,
09:              ‘cle2’ => ‘B’,
10:              ‘cle3’ => ‘C’
11:            )
12:   );
13:
14:   for ($i = 0; i < 10; $i++)
15:   {
16:     if ($tab[$tab[‘D’][‘cle2’]] == $i)
17:     {
18:       echo ‘Trouvé !’;
19:     }
20:   }
21: ?>

Si vous êtes l’auteur du premier morceau de code et que votre développement n’a pas été effectué depuis plus de deux semaines, vous devriez pouvoir vous rappeler de ce que vous avez voulu écrire. Dans tous les autres cas, la compréhension de ces 5 lignes vous prendra beaucoup plus de temps que si elles avaient été correctement indentées (voir les 20 lignes du deuxième exemple). Bien sûr, certains pourront affirmer avec raison que le premier fichier, plus compact, occupera moins d’espace disque et sera exécuté plus rapidement. Si vous recherchez à minimiser la taille de vos fichiers, rien ne vous empêche d’avoir deux versions de vos codes :

• une version contenant les codes sources ;
• une version de production qui sera « optimisée » (suppression des commentaires et des espaces/tabulations d’indentation). À ce propos, vous pourrez voir la fonction php_strip_whitespace() [2].

2. PHPCheckStyle

Dans cette partie, je vais vous présenter PHPCheckStyle depuis son installation, son utilisation, jusqu’à la façon de l’adapter (dans la mesure du possible) à vos conventions.

2.1 Installation

Tout d’abord, il va falloir récupérer PHPCheckStyle sous la forme d’un fichier zippé (spikephpcheckstyle-0.6.zip) sur le site : http://developer.spikesource.com/wiki/index.php/Projects:phpcheckstyle.
Pour avoir accès à cet outil depuis n’importe quel répertoire, nous allons l’installer en tant que root dans /opt/phpcheckstyle.

cp spikephpcheckstyle-0.6.zip /opt
cd /opt
unzip spikephpcheckstyle-0.6.zip
mv spikephpcheckstyle-0.6 phpcheckstyle
rm spikephpcheckstyle-0.6.zip

Cet outil est codé en PHP et le fichier principal à lancer ne porte pas un nom particulièrement explicite : run.php. Nous allons le renommer :

    mv /opt/phpcheckstyle/run.php /opt/phpcheckstyle/phpcheckstyle.php

Nous pouvons maintenant créer un alias qui nous permettra d’exécuter PHPCheckStyle depuis n’importe quel répertoire. Pour cela, nous allons modifier le fichier de configuration de votre shell. Je donne un exemple ici pour un shell bash (fichier .bashrc de votre répertoire personnel /home/mon_login). Pour un autre type de shell, il vous suffira de modifier le fichier approprié (.cshrc pour du csh, etc.). Dans le fichier correspondant à votre shell, nous allons ajouter la ligne suivante :

     alias phpcheckstyle=’php /opt/phpcheckstyle/phpcheckstyle.php’

Pour activer la modification, nous devons exécuter :

    source .bashrc

L’installation est achevée et nous pourrons faire appel à PHPCheckStyle de n’importe quel emplacement en invoquant phpcheckstyle. Nous allons maintenant voir comment utiliser cet outil.

2.2 Vérification du code

Pour tester PHPCheckStyle, nous allons créer un petit script PHP d’exemple qui ne respecte pas les conventions de codage PEAR (ces conventions correspondent au paramétrage par défaut de PHPCheckStyle). Voici le fichier teststyle.php :

01: <?PHP
02:   echo ‘Fichier de test pour PHPCheckStyle<br />’;
03:   for ($_i=0; $_i<10; $_i++)
04:   {
05:     echo ‘Compteur : ‘.$_i.’<br />’;
06:   }
07: ?>

Pour lancer la vérification sur ce fichier, il faut exécuter :

phpcheckstyle --src teststyle.php

PHPCheckStyle va créer, dans le répertoire courant, un répertoire style-report/ qui contiendra le rapport sous forme de page HTML (index.html). Si vous désirez stocker les résultats dans un autre répertoire que le répertoire par défaut (./style-report/), vous pouvez le spécifier grâce au paramètre --outdir. Par exemple, pour stocker le rapport de notre programme dans /home/reports/, nous exécuterons :

	phpcheckstyle --src teststyle.php --outdir /home/reports

Vous trouverez en figure 1 la page de résultat produite.

Figure 1 : Page de résultat de PHPCheckStyle sur l’exemple teststyle.php

Cette page nous signale 10 erreurs ou non-respects de la convention de codage et nous indique comment y remédier. Voici le résumé des erreurs rencontrées :

• en ligne 1, il aurait fallu écrire PHP en minuscules ;
• en ligne 3, il aurait fallu mettre des espaces avant et après les caractères « = » et « < » ;
• en ligne 4, l’accolade ouvrante aurait dû se trouver à la fin de la ligne 3 (les conventions PEAR utilisent la notation Kernighan et Ritchie) ;
• enfin, en ligne 5, les opérateurs de concaténation « . » auraient dû être précédés et suivis d’un caractère d’espacement.

Il ne s’agit bien sûr que d’un exemple des divers messages d’avertissement que PHPCheckStyle peut afficher. En corrigeant ces erreurs, la page de rapport nous indique que tout est maintenant correct (voir figure 2).

Figure 2 : Page de résultat de PHPCheckStyle sur l’exemple teststyle.php après correction

 Pour traiter un répertoire contenant un projet et donc de nombreux fichiers PHP, il suffira d’invoquer PHPCheckStyle en indiquant le nom du répertoire :
phpcheckstyle --src projet

La page de résultat comprendra alors des informations sur le nombre de fichiers analysés et décrira pour chacun d’eux les erreurs relevées.
Voyons maintenant comment paramétrer PHPCheckStyle en fonction de nos propres conventions.

2.3 Configuration

Le fichier de configuration de PHPCheckStyle se trouve dans le fichier XML pear.cfg.xml. Pour notre installation, il s’agira de /opt/phpcheckstyle/config/pear.cfg.xml.
Les règles de vérification sont définies dans des balises <test> dont l’attribut name définit le nom. Lorsque ces règles admettent des propriétés spéciales, elles sont ajoutées dans des balises <property>. Notons ici qu’il n’est malheureusement pas possible de créer de nouvelles règles, mais seulement de les désactiver et pour certaines de les adapter.
Dans le tableau suivant, nous listons les différentes règles que vous pourrez trouver dans le fichier de configuration. Pour chacune d’entre elles, si vous souhaitez la désactiver, il vous suffira de commenter les lignes.

Cet outil permet donc de vérifier qu’un programme respecte bien les conventions de codage. Toutefois, il vous oblige à corriger manuellement vos erreurs.
Il existe des outils de formatage automatique qui, loin de réaliser tout le travail à votre place, vous économisent néanmoins quelques remaniements. Ces outils sont surtout utiles lors de la reprise d’un code existant n’ayant suivi aucune convention. Dans la suite de cet article, je vous présente PHP_Beautifier [3], une bibliothèque PHP permettant de créer des scripts de reformatage de code.

3. Un formateur de code : PHP_Beautifier

En guise de préambule à cette partie, je tiens à attirer votre attention sur le fait que l’on pourrait penser que les outils de formatage de code servent à s’affranchir définitivement des conventions de codage (puisque ces derniers se chargent du formatage), mais attention :

• D’une part, tous les outils de formatage ont des limites : vous devrez de toute façon retravailler le code après leur passage.
• D’autre part, prendre l’habitude de mal présenter son code est une très mauvaise habitude : pendant au moins toute la phase de conception, vous travaillerez avec un code moins lisible (même si, dans un court laps de temps, vous arrivez à vous relire) et vous serez donc moins efficace.

Ceci étant dit, je vais vous présenter l’un de ces formateurs de code, le projet PHP_Beautifier hébergé par PEAR. Il est à noter que ce projet est encore en version bêta et pâtit donc encore de quelques défauts (les fichiers très volumineux provoquent des erreurs, le code HTML enfoui n’est pas indenté, etc.). Quoi qu’il en soit, comme dit précédemment, cet outil ne peut remplacer votre propre expertise et vous devrez forcément retoucher le code généré.
Pour installer PHP_Beautifier (version 0.1.13 bêta), vous devez disposer de l’installateur PEAR, sinon, il vous faudra le récupérer pour votre version de Linux (apt-get install pear pour Debian). Il suffit ensuite de taper :

	pear install PHP_Beautifier-0.1.13

Vous venez d’installer la bibliothèque PHP_Beautifier. Encore faut-il maintenant l’utiliser. Imaginons que nous disposions du code non formaté suivant :

01: <?PHP
02:     $var=4;
03:   if ($var == 3) echo $var;
04:   for ($i=1;$i<10; $i++) {echo $i; }
05: ?>

Souhaitant formater ce code en utilisant les normes PEAR. Nous allons créer un script utilisant la bibliothèque PHP_Beautifier. Puisque la documentation disponible sur le site officiel [4] est très complète, mais totalement dénuée d’exemples, je vous propose d’en analyser un que nous appellerons beautify_php :

01: #!/usr/bin/php -q
02: <?php
03:   require_once ‚PHP/Beautifier.php‘;
04:
05:   // On récupère le nom du fichier
06:   if ($argc != 2)
07:   {
08:     die(‘Syntaxe: PHPBeautifier <nom_fichier>’ . «\n»);
09:   }
10:   $_file = $argv[1];
11:   if (!is_file($_file))
12:   {
13:     die(‘Nom de fichier incorrect’ . «\n»);
14:   }
15:
16:   try
17:   {
18:     $_beauty = new PHP_Beautifier();
19:     $_beauty->setIndentNumber(2);
20:     $_beauty->setIndentChar(‘ ‘);
21:     $_beauty->setNewLine(“\n”);
22:     $_beauty->addFilter(‘ArrayNested’);
23:     $_beauty->addFilter(‘IndentStyles’, array(‘style’ => ‘bsd’));
24:     $_beauty->addFilter(‘Pear’, array(‘add_header’ => ‘php’));
25:     $_beauty->setInputFile($_file);
26:     $_beauty->setOutputFile(‘beautified_’ . $_file);
27:     $_beauty->process();
28:     $_beauty->save();
29:   }
30:   catch (Exception $e)
31:   {
32:     echo $e;
33:   }
34: ?>

Comme l’indique la ligne 1, ce code est écrit en PHP CLI (ligne de commandes pour PHP). Il vous suffira de rendre le script exécutable (chmod u+x beautify_php) pour pouvoir le lancer directement en mode console. Modifiez le chemin vers votre interpréteur PHP si celui-ci ne correspond pas à celui spécifié en ligne 1. Par la suite, nous déclarons que nous allons utiliser la bibliothèque PHP_Beautifier en ligne 3 puis, dans les lignes 5 à 14, on récupère le nom du fichier qui sera passé en argument et on gère les erreurs. Le cœur du script se trouve dans les lignes 18 à 28 :

• en ligne 18, on crée un objet PHP_Beautifier ;
• la ligne 19 définit le nombre de caractères définissant une indentation et la ligne 20 définit le caractère qui représentera cette indentation. J’ai défini ici une indentation comme étant deux caractères espace (la norme PEAR est de quatre espaces) ;
• la ligne 21 définit le caractère de saut à la ligne (ici le saut à la ligne standard : \n) ;
• en ligne 22, on active l’indentation des structures de table. En effet, un tableau écrit sous la forme :

  array(‘A’=>’elt1’,’B’=>array(‘B1’=>’E1’,’B2’=>’E2’));

sera réécrit sous la forme :

  array(
    ‘A’ => ‘elt1’,
    ‘B’ => array(
      ‘B1’ => ‘E1’,
      ‘B2’ => ‘E2’
    )
  );

• en ligne 23, on définit le style d’indentation des structures (position des accolades après une boucle for par exemple). De nombreux styles sont disponibles [5] dont ‘k&r’ pour Kernighan et Ritchie. Préférant la notation BSD, je l’ai activée grâce au paramètre ‘bsd’ ;
• en ligne 24, on active le formatage avec les conventions PEAR. Le second paramètre array(‘add_header’ => ‘php’) est optionnel. Il permet d’ajouter automatiquement des commentaires en début de fichier. Il s’agit ici du fichier de licence PHP disponible dans /usr/share/php/data/PHP_Beautifier/licenses/php.txt (d’autres fichiers de licence sont disponibles : PEAR, BSD, APACHE et LGPL). Vous pourrez bien sûr modifier le contenu de ce fichier ou en créer un nouveau en cas de besoin.
• enfin, dans les lignes 25 à 28, on définit le fichier d’entrée (ligne 25), le fichier de sortie (ligne 26) et, enfin, on lance le reformatage du code et on le sauvegarde dans le fichier de sortie.

Le script s’utilise très simplement :

	beautify_php mon_fichier.php

Cette exécution va générer un nouveau fichier reformaté beautified_mon_fichier.php dans le répertoire courant. Sur l’exemple du code non formaté précédent, cela donne (les différences sont notées en rouge et les caractères espaces ajoutés sont notés □) :

01: <?php
02: $var□=□4;
03: if ($var == 3) echo $var;
04: for ($i□=□1;□$i□<□10; $i++)
05: {
06: ..echo $i;
07: ..□
08: }
09: ?>

Comme vous pouvez vous en rendre compte, le code généré doit être retravaillé :

• les indentations en début de ligne ont toutes été supprimées ;
• en ligne 3, le code echo $var; devrait se trouver à la ligne et entre accolades ;
• la ligne 7 est une ligne inutile.

Pour pouvoir utiliser ce script depuis n’importe quel répertoire, il suffit de le placer dans un répertoire figurant dans votre variable d’environnement PATH (modification du fichier .bashrc si vous utilisez un shell bash).

Enfin, pour vous montrer que l’utilisation de PHP_Beautifier ne résout pas tous les problèmes, je vous propose de lancer PHPCheckStyle sur le fichier généré par beautify_php lors de l’exemple précédent. Auparavant, on s’assurera bien sûr que le paramétrage des conventions dans PHPCheckStyle est cohérent avec celui de notre script PHP_Beautifier. Le résultat de l’analyse de PHPCheckStyle est présenté en figure 3.

On voit qu’une erreur est signalée en ligne 3 : le traitement suivant la condition if aurait dû être placé entre accolades... chose que PHP_Beautifier n’a pas vu !

Conclusion

En conclusion, dans cet article, je vous ai présenté deux outils complémentaires PHPCheckStyle et PHP_Beautifier. L’un permet de vérifier de manière systématique la bonne application des conventions de codage et l’autre permet de reformater rapidement un code.

Grâce à PHPCheckStyle, il est très simple de contrôler que chaque fichier de vos projets respecte bien les conventions de codage qui ont été mises en place. La correction se fait rapidement grâce aux indications fournies dans le rapport. Vous gagnerez énormément en lisibilité et le travail collaboratif en sera facilité. De plus, la mise en place de vérifications systématiques de nuit (grâce à un cron) vous permettra de maintenir un code propre pour un effort moindre.

Si vous reprenez un travail existant, PHP_Beautifier vous permettra de dégrossir le travail de remise en forme avant de pouvoir appliquer PHPCheckStyle. Pour terminer, j’insisterais à nouveau sur le fait que les normes de codages n’ont pas été conçues pour compliquer la vie du développeur... bien au contraire !

Bibliographie

• [1] http://pear.php.net/manual/fr/standards.php
• [2] http://fr.php.net/manual/fr/function.php-strip-whitespace.php
• [3] http://pear.php.net/package/PHP_Beautifier
• [4] http://beautifyphp.sourceforge.net/docs/
• [5] http://beautifyphp.sourceforge.net/docs/PHP_Beautifier/Filter/PHP_Beautifier_Filter_IndentStyles.html

  Retrouvez cet article dans : Linux Magazine 101