Bonnes pratiques PHP - PSR-1 et PSR-4

31 août 2020 - : PHP Tutoriel - : 0 commentaire - Tutoriel Généralités PHP

Dernière modification le 2 septembre 2020

Dans tout langage de développement, nous avons des bonnes et des mauvaises pratiques.

Cet article a pour but de lister les différentes recommandations émises dans des standards appelés PSR (PHP Standards Recommendations) et maintenus par le PHP Framework Interop Group (PHP-FIG).

Ces standards sont des prescriptions, pas des obligations, mais leur utilisation est une bonne pratique.

Les standards PSR ont tous un objectif particulier comme indiqué dans la liste ci-dessous

Numéro Titre Statut
0 Autoloading Standard Déprécié
1 Basic Coding Standard Accepté
2 Coding Style Guide Déprécié
3 Logger Interface Accepté
4 Autoloading Standard Accepté
5 PHPDoc Standard Brouillon
6 Caching Interface Accepté
7 HTTP Message Interface Accepté
8 Huggable Interface Abandonné
9 Security Advisories Abandonné
10 Security Reporting Process Abandonné
11 Container Interface Accepté
12 Extended Coding Style Guide Accepté
13 Hypermedia Links Accepté
14 Event Dispatcher Accepté
15 HTTP Handlers Accepté
16 Simple Cache Accepté
17 HTTP Factories Accepté
18 HTTP Client Accepté
19 PHPDoc tags Brouillon

Dans ce tutoriel, nous allons traiter PSR-1 et PSR-4

PSR-1 - Standard de base de codage

Cette section liste ce qui doit être condidéré comme un standard de codage qui est requis pour garantir un haut niveau d'intéropérabilité pour le code PHP partagé.

Les mots-clés “DOIT”, “NE DOIT PAS”, “REQUIS”, “PEUT”, “POURRAIT NE PAS”, “DEVRAIT”, “NE DEVRAIT PAS”, “RECOMMANDE” et “OPTIONNEL” dans ce document correspondent à la terminologie décrite dans la RFC 2119.

Résumé

  • Les fichiers DOIVENT utiliser uniquement les balises <?php et <?= .

  • Les fichiers DOIVENT utiliser uniquement du code PHP en UTF-8 sans BOM.

  • Les fichiers DEVRAIENT déclarer des symboles (classes, fonctions, constantes, etc.) OU causer un effet de bord (générer une sortie, modifier les paramètres .ini, etc.) mais ne DEVRAIENT PAS faire les deux.

  • Les Namespaces et classes DOIVENT suivre un PSR “autoloading” [PSR-0, PSR-4].

  • Les noms de classes DOIVENT être déclarés en UpperCamelCase.

  • Les constantes de classes DOIVENT être déclarées en majuscules avec un séparateur underscore.

  • Les noms de Méthodes DOIVENT être déclarés en camelCase.

Fichiers

Balises PHP

Le code PHP DOIT utiliser la balise longue <?php ?> ou la balise courte echo <?= ?> ; Il NE DOIT PAS utiliser d'autre variation.

Encodage de caractères

Le fichier PHP DOIT utiliser UNIQUEMENT l'encodage UTF-8 sans BOM.

Effets de bord

Un fichier DEVRAIT déclarer de nouveaux symboles (classes, fonctions, constantes, etc.) et ne pas causer d'autre effet de bord, ou il DEVRAIT exécuter de la logique avec effet de bord, mais NE DEVRAIT PAS faire les deux.

Les termes “effet de bord” signifient l'exécution de logique qui n'est pas directement liée à une déclaration de classe, fonction, constante...etc., seulement en incluant le fichier.

“Effets de bord” inclut mais n'est pas limité à : génération de sortie, utilisation explicite de require ou include, se connecter à un service externe, modifier les paramètres ini, émettre des erreurs ou exceptions, modifier des variables globales ou statiques, lire ou écrire dans un fichier...

L'exemple ci-dessous est un exemple contenant déclaration et effet de bord, un exemple de ce qu'il faut éviter :

<?php
// effet de bord : modification des paramètres ini
ini_set('error_reporting', E_ALL);

// effet de bord : chargement d'un fichier
include "file.php";

// effet de bord : génère une sortie
echo "<html>\n";

// déclaration
function foo()
{
    // code de la fonction
}

L'exemple suivant correspond à un fichier qui contient des déclarations mais pas d'effets de bord :

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

// déclaration conditionnelle n'est *pas* un effet de bord
if (! function_exists('bar')) {
    function bar()
    {
        // code de la fonction
    }
}

Noms de Namespace et Class

Les Namespaces et classes DOIVENT suivre un PSR "autoloading” [PSR-0, PSR-4].

Cela signifie que chaque classe est un fichier par lui-même, et se trouve dans un namespace d'au moins un niveau, un nom de "vendor".

Les noms de classes DOIVENT être déclarés en UpperCamelCase.

Par exemple:

<?php
namespace Vendor\Model;

class Foo
{
}

Constantes, Propriétés et Méthodes de classes

Le terme “classe” se réfère à toutes les classes, interfaces et traits.

Constantes

Les constantes de classes DOIVENT être déclarées en majuscules avec séparateur underscore. Par exemple :

<?php
namespace Vendor\Model;

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

Propriétés

Le guide officiel évite de façon volontaire toute recommandation concernant l'utilisation de $UpperCamelCase, $camelCase, ou $under_score pour les noms de propriétés.

Quel que soit la convention de nommage utilisée, elle DEVRAIT être appliquée avec cohérence dans un contexte donné. Ce contexte peut être au niveau "vendor", package, classe, ou méthode.

L'usage le plus répandu est l'utilisation de $camelCase

Méthodes

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

PSR-2

Il existait le PSR-2, qui indiquait quelques bonnes pratiques de codage pour les variables et fonctions. Ce standard a été déprécié à ce stade.

PSR-4 - Autoloader

Les mots-clés “DOIT”, “NE DOIT PAS”, “REQUIS”, “PEUT”, “POURRAIT NE PAS”, “DEVRAIT”, “NE DEVRAIT PAS”, “RECOMMANDE” et “OPTIONNEL” dans ce document correspondent à la terminologie décrite dans la RFC 2119.

Résumé

Cette PSR décrit une spécification pour mettre en place l'autoloading de classes depuis un chemin de fichiers. Il est totalement interoperable, et peut être utilisé en complément de tout autre standard d'autoloading, incluant PSR-0. Cette PSR décrit également où placer les fichiers qui seront chargés automatiquement en accord avec la spécification.

Spécification

  1. Le terme “classe” se réfère à toutes les classes, interfaces et traits, et autres structures similaires.

  2. Un nom de classe totalement qualifié a la forme suivante :

    \<NamespaceName>(\<SubNamespaceNames>)*\<ClassName>
    
    1. Un nom de classe totalement qualifié DOIT avoir un namespace principal, également appelé “vendor namespace”.

    2. Un nom de classe totalement qualifié PEUT avoir un ou plusieurs nom de "sous namespaces".

    3. Un nom de classe totalement qualifié DOIT se terminer par un nom de classe.

    4. Les underscores n'ont pas de signification dans le nom de classe totalement qualifié.

    5. Les caractères alphabétiques dans le nom de classe totalement qualifié PEUVENT être toute combinaison de majuscules et minuscules.

    6. Tous les noms de classes DOIVENT être référencés dans un modèle sensible à la casse.

  3. Lors du chargement d'un fichier qui correspond à un nom de classe totalement qualifié…

    1. Une série continue d'un ou plusieurs namespaces et sous namespaces, sans compter le séparateur d'espace de noms principal, dans le nom de classe pleinement qualifié (un «préfixe d'espace de noms») correspond à au moins un «répertoire de base».

    2. Les noms de sous-namespaces contigus après le «préfixe d'espace de noms» correspondent à un sous-répertoire dans un «répertoire de base», dans lequel les séparateurs d'espaces de noms représentent des séparateurs de répertoires. Le nom du sous-répertoire DOIT correspondre à la casse des noms de sous-namespaces.

    3. Le nom de la classe correspond à un nom de fichier se terminant par .php. Le nom de fichier DOIT correspondre à la casse du nom de classe.

  4. Les implémentations d'autoloader NE DOIVENT PAS lancer d'exceptions, NE DOIVENT PAS déclencher d'erreurs de quelque niveau que ce soit et NE DEVRAIENT PAS renvoyer de valeur.

Exemples

Le tableau ci-dessous indique le chemin de fichier correspondant à un nom de classe totalement qualifié, préfixe de namespace, et dossier de base.

Nom de classe totalement qualifié

Préfixe de Namespace Dossier de base Chemin du fichier
\Acme\Log\Writer\File_Writer Acme\Log\Writer ./acme-log-writer/lib/ ./acme-log-writer/lib/File_Writer.php
\Aura\Web\Response\Status Aura\Web /path/to/aura-web/src/ /path/to/aura-web/src/Response/Status.php
\Symfony\Core\Request Symfony\Core ./vendor/Symfony/Core/ ./vendor/Symfony/Core/Request.php
\Zend\Acl Zend /usr/includes/Zend/ /usr/includes/Zend/Acl.php

Obtenir de l'aide

Pour obtenir de l'aide, vous pouvez accéder au serveur Discord pour une entraide par chat.

Partager

Partager sur Facebook Partager sur Twitter Partager sur LinkedIn

Commentaires

Pas encore de commentaire

Obtenir de l'aide

Il n'est plus possible d'ajouter de commentaires.

Pour obtenir de l'aide, vous pouvez accéder au serveur Discord pour une entraide par chat