PHP : bonnes pratiques et conventions

Introduction

L'écosystème PHP est vaste et complet : beaucoup d'outils, frameworks et CSM sont disponibles, la communauté est importante et active, les entreprisent recrutent, les clients sont nombreux…. Dans un monde faisant intervenir autant d'acteurs, il est important de suivre certaines "normes" afin d'assurer la pérénité des projets (et du langage). Ces conventions ont pour but de fournir des bonnes pratiques afin d'homogénéiser les développements et de simplifier la maintenabilité du code. En effet, un projet PHP qui respecte les normes est plus facile à prendre en main par un nouveau développeur et ainsi plus simple à maintenirqu'un projet ne les respectant pas.

Il existe 3 grands standards PHP :

Je vais, dans cet article, parler de la convention PSR qui tend à devenir le standard respecté par Symfony notamment. 

Les normes PSR

PSR-0 : autoloading

L'objectif de la PSR-0 est de rendre standard le chargement des classes afin d'éviter les "include" et "require". Ce système d'autoloading repose sur la bonne utilisation des namespaces. Voici la liste des principales règles :

  • Les classes et les espaces de noms entièrement qualifiés doivent disposer de la structure suivante\<Nom du Vendor>\(<Espace de noms>\)*<Nom de la Classe>.
  • Chaque espace de noms doit avoir un espace de noms racine. ("Nom du Vendor").
  • Chaque espace de noms peut avoir autant de sous-espaces de noms qu'il le souhaite.
  • Chaque séparateur d'un espace de noms est converti en DIRECTORY_SEPARATOR lors du chargement à partir du système de fichiers.
  • Chaque "_" dans le nom d'une CLASSE est converti en DIRECTORY_SEPARATOR. Le caractère "_" n'a pas de signification particulière dans un espace de noms.
  • Les classes et espaces de noms complètement qualifiés sont suffixés avec ".php" lors du chargement à partir du système de fichiers.
  • Les caractères alphabétiques dans les noms de vendors, espaces de noms et noms de classes peuvent contenir n'importe quelle combinaison de minuscules et de majuscules.

Le fichier d'autoload généré est par Composer, par exemple, respecte cette norme.

PSR-1 : La norme de codage de base

La PSR-1  décrit les éléments standards de codage nécessaires pour assurer un niveau élevé d'interopérabilité technique pour le partage du code PHP. Cette norme concerne : les fichiers, les espaces de nom et noms des classes ainsi que les constantes de classe, propriétés et méthodes :

  • Les fichiers DOIVENT utiliser seulement les tags <?php et <?=.
  • Les fichiers de code PHP DOIVENT être encodés uniquement en UTF-8 sans BOM.
  • Les fichiers DEVRAIENT soit déclarer des symboles (classes, fonctions, constantes, etc.) soitcauser des effets secondaires (par exemple, générer des sorties, modifier paramètres .ini), mais NE DOIVENT PAS faire les deux.
  • Les espaces de noms et les classes DOIVENT suivre PSR-0.
  • Les noms des classes DOIVENT être déclarés comme StudlyCaps.
  • Les constantes de classe DOIVENT être déclarées en majuscules avec un sous-tiret en séparateurs.
  • Les noms des méthodes DOIVENT être déclarés comme camelCase.

Vous trouverez des exemples concrets ici : http://www.php-fig.org/psr/psr-1/fr/.
Personnellement je trouve que cette règle est importante est doit être respectée au maximum car elle améliore la lisibilité du code.

PSR-2 : Guide pour le style d'écriture de code

La norme PSR-2 complète la PSR-1 et décrit les bonnes pratiques en matière de programmation. Vous trouverez ci-dessous la vue d'ensemble des points décrit dans la documentation officielle :

  • Le code DOIT suivre les PSR-1.
  • Le code DOIT utiliser 4 espaces pour l'indentation et aucune tabulation.
  • Il NE DOIT PAS exister une limite stricte sur la longueur de la ligne, la limite acceptable DOIT être de 120 caractères; les lignes DEVRAIENT comprendre 80 caractères ou moins.
  • Il DOIT y avoir une ligne vide après la déclaration de l'espace de noms, et il   DOIT y avoir une ligne vide après le bloc de déclarations use.
  • L'ouverture des accolades pour les classes DOIT figurer sur la ligne suivante, les accolades de fermeture DOIVENT figurer sur la ligne suivante après le corps de la classe.
  • L'ouverture des accolades pour les méthodes DOIT figurer sur la ligne suivante, les accolades de fermeture DOIVENT figurer sur la ligne suivante après le corps de la méthode.
  • La visibilité DOIT être déclarée sur toutes les propriétés et méthodes; abstract et finaldoivent être déclarés avant la visibilité; static DOIT être déclaré après la visibilité.
  • La structure des mots-clés de contrôle DOIT avoir un espace après eux, les méthodes et les appels de fonction NE DOIVENT PAS en avoir.
  • L'ouverture des accolades pour les structures de contrôle DOIT figurer sur la même ligne, et la fermeture des accolades DOIT figurer sur la ligne suivante après le corps.
  • l'ouverture des parenthèses pour les structures de contrôle NE DOIT PAS contenir d'espace après eux, la fermeture de parenthèses pour les structures de contrôle NE DOIT PAS contenir d'espace avant.

Cette convention est souvent controversée car elle est considérée comme trop "rigide". De mon point de vue, il faut adopter une règle est la respecter. Ainsi, si vous intervenez sur des projets déjà avancés, calquez vous sur ce qui est déjà en place (notamment pour les accolades et l'indentation). Le principal étant simplement de rester cohérent avec l'implémentation déjà effectuée et la méthodologie adoptée par les développeurs travaillant sur le projet.

PSR-3 : Interface pour les logs

L'objectif de la PSR-3 est de définir comment seront gérés les logs de votre application. Comme dans la majorité des cas vous utilisez une librairie dédiée au log, le plus simple est d'en choisir une répondant à cette norme 😉 telle que Monolog par exemple. Voici les concepts de base :

  • L'interface LoggerInterface expose huit méthodes pour écrire les logs pour les huit RFC 5424levels (debug, info, notice, warning, error, critical, alert, emergency).
  • Un neuvième méthode, log, accepte un niveau de journalisation en tant que premier argument. L'appel de cette méthode avec l'une des constantes du niveau de journalisation DOIT avoir le même résultat que l'appel de la méthode de niveau spécifique. L'appel de cette méthode avec un niveau non défini par cette spécification DOIT lancer un Psr\Log\InvalidArgumentException si l'implémentation ne reconnaît pas le niveau. Les utilisateurs NE DEVRAIENT PAS utiliser de niveau personnalisé sans savoir avec certitude si l'implémentation le supporte.

PSR-4 : autoloading avancé

Cette norme complète la PSR-0. Alors que cette dernière se concentre principalement sur les namespaces et noms de classes, la PSR-4 fixe des règles concernant l'arborescence des fichiers. Vous trouverez plus d'informations ici : http://www.php-fig.org/psr/psr-4/.

Le fichier d'autoload généré par Composer, par exemple, respecte également cette norme (en plus de la PSR-0).

Quelques outils

PHP Coding Standards Fixer : développé parSensio Labs (Symfony) pour passer du code aux normes PSR

https://github.com/duodraco/phpcs-psr : un jeu de règles pour PHP Code Sniffer (phpcs)

Conclusion

Dans le cadre d'un processus d'intégration continu, vous pouvez envisager d'utiliser les hook de pré-commit afin de forcer les développeurs à respecter certaines des conventions ci-dessus. Ainsi, si le code n'est pas "PSR compliant",  le développeur devra l'adapter afin de pouvoir commiter.

Cet article est une simple introduction à la norme PSR. Si vous êtes pour ou contre les conventions, si vous souhaitez apporter des informations complémentaires, si vous préférez une autre convention que la PSR ou bien tout simplement si vous souhaitez vous exprimez : laissez un petit commentaire ci-dessous.

2 commentaires

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *

*

code