PHP : bonnes pratiques et conventions :
======================================

`Blog Severin Bruhat :  <http://severin-bruhat.com/blog/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 repsecte 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 :

* `PEAR <http://pear.php.net/manual/fr/standards.php>`_
* `Zend <http://framework.zend.com/manual/1.12/fr/coding-standard.html>`_
* `PSR <http://www.php-fig.org/psr//>`_

Nous parlerons de la convention PSR qui tend à devenir le standard respecté par Hoa,CakePHP,Symfony notamment.

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 :

Vue d'ensemble
***************

* 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.) soit causer 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.


L'exemple suivant est un fichier qui contient des déclarations sans effets secondaires, c’est-à-dire, un exemple à émuler :

.. code-block:: php

    <?php
    // déclaration
    function foo()
    {
        // corps de la fonction
    }

    // une déclaration conditionnelle n'est pas un effet secondaire
    if (! function_exists('bar')) {
        function bar()
        {
            // corps de la fonction
        }
    }

Espaces de Nom et Noms des Classes
***********************************

Les espaces de noms et les classes DOIVENT suivre PSR-0.

* Cela signifie que chaque classe devra se trouver seule dans un fichier, et dans un espace de nom d'au moins un niveau : le nom d'un vendor de plus haut niveau.
* Les noms de classes DOIVENT être déclarés en StudlyCaps.
* Le code écrit pour PHP 5.3 et après, DOIT utiliser les espaces de noms formels.

**Par exemple :**
 .. code-block:: php

    <?php
    // PHP 5.3 et supérieur:
    namespace Vendor\Model;

    class Foo
    {
    }


Les Constantes
****************

Les constantes de classe DOIVENT être déclarées en majuscules avec un tiret bas séparateur. Par exemple :

.. code-block:: php

    <?php
    namespace Vendor\Model;

    class Foo
    {
        const VERSION = '1.0';
        const DATE_APPROVED = '2012-06-01';
    }

Les Propriétés
**************

Ce guide évite intentionnellement toute recommandation concernant l'utilisation des noms de propriétés $StudlyCaps, $camelCase ou $under_score.

Quelle que soit la convention de nommage utilisée, elle DOIT être appliquée de manière cohérente dans un cadre raisonnable. Cette portée peut être au niveau vendor, paquet, classe ou méthode.

Les Méthodes
************

Les noms de méthodes DOIVENT être déclarés ainsi camelCase().

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).