Bonnes pratiques PHP #1 un code propre qui respecte les standards

Il n’y a pas qu’une seule et unique façon d’utiliser PHP. Il existe des bonnes pratiques en matière de développement web, des conventions ont été créées pour permettre de favoriser la collaboration entre les développeurs.

Cet article (et les suivants) présente différentes recommandations conseillées dans les standards PSR (PHP Standards Recommendations) concernant les variables, les fonctions, les constantes et les classes.

Tu découvriras ou re-découvriras au fil de cet article les conventions de nommage essentielles à une meilleure lisibilité de ton code.

Au programme :

• Nommage explicite
• Conventions d’écriture des variables, fonctions, constantes et classes
• Mots clés
• Accolades et espaces
• Utilisation de constantes

Écriture et nommage des variables, fonctions, constantes et classes

Nommage explicite

Le nommage est une étape très importante quand on crée un programme informatique. Quand on débute, on a tendance à écrire des noms de variables ou de fonctions courts, condensés, pour « gagner du temps » ou parce qu’en se lisant sur l’instant, on sait très bien ce qu’il y a dans cette variable ou cette fonction. Mais avec le temps, on se rend compte qu’il est important de nommer explicitement les différents éléments d’un programme.

Souvent, une indication qu’une variable est mal nommée est la présence d’un commentaire qui explique ce qu’elle contient. Par exemple :

// Les utilisateurs validés
$users = getValidatedUsers(); 

// Plus loin dans le code, j'utilise $users
foreach ($users as $user) {
   // Je ne sais plus ici si ces users ont une spécificité particulière
}

// Alors que j'aurais pu les nommer directement : 
$usersValidated = getValidatedUsers();

Cet exemple un peu simple mais on se rend compte très vite qu’en respectant cette bonne pratique de nommage, on produit un code plus clair et plus lisible. Et l’excuse « c’est + long à taper » ne tient pas car tous les IDE proposent de l’autocomplétion !

De la même façon, n’utilise pas d’abréviation, qui laisse place à l’interprétation :

// Pas bien, plusieurs interprétation possible
$userNum;

// Bien, aucune interprétation possible
$userMobilePhoneNumber;

Cette bonne pratique vaut pour tous les éléments d’un programme PHP : variables, fonctions, propriétés, classes, constantes, etc.

Conventions d’écriture en PHP

Les noms des variables, des fonctions, des méthodes et des attributs sont écrits en camelCase.

$maSuperVariable = 3;
function sumAllNumbers(int $maximum) {...}

Les noms des clés dans un tableau sont écrits en snake_case. Le mot clé array n’est plus utilisé pour les tableaux.

$user = [
   'username' => 'monadresse@mail.com',
   'first_name' => 'John',
   'last_name' => 'Doe',
   'active' => 1
];

Les noms des constantes sont écrits en MAJUSCULE

define('LUCKY_NUMBER', 13);

Les noms des objets sont écrits en PascalCase. Chaque objet est stocké dans un fichier qui porte le même nom que l’objet et ne contient que cet objet.

class Hero
{
...
}

Mots-clés en PHP

En programmation orientée objet, la convention précise que la visibilité des propriétés et méthodes doit toujours être déclarée. Les mots-clés abstract et final doivent être déclarés avant la visibilité. Le mot-clé static lui doit être déclaré après la visibilité.

Les mots-clés true, false et null doivent toujours êtres écrits en minuscule.

Accolades et espaces en PHP

Selon la convention, les accolades en PHP sont à la ligne suivant la déclaration d’une classe, d’une fonction ou d’une méthode.

class Hero
{
    // Nom de mon Héros
    public string $name = '';
    
    // Constructeur
    public function __construct(string $name)
    {
        $this->name = $name;
    }
}

Les accolades en PHP sont à la suite, précédée d’un espace, pour un if, switch, while, foreach, match, etc. et sont obligatoires.

function calculSommeNombresPairs($maximum)
{
    $somme = 0;
    for ($i = 1; $i <= $maximum; $i++) {
        if ($i % 2 == 0) {
            $somme += $i;   
        }
    }

    return $somme;
}

On ne met pas d’espace entre le nom d’une fonction et l’appel de ses paramètres. Même chose à la création d’un objet. Seul echo fait exception.

$sum = calculSumPairNumbers(200);
echo $sum;

$hero = new Hero('Actarus');
echo $hero->getName();

Utilisation de constantes

Utilise des constantes pour réaliser des comparaisons de nombre ou de chaînes de caractères. Ce principe est très intéressant pour avoir un code beaucoup plus lisible. De plus, si tu fais une faute de frappe sur une constante, PHP déclenchera une erreur, alors que si tu fais une faute de frappe dans une chaîne de caractères, PHP ne déclenchera pas d’erreur :

// Je teste le statut d'une commande
if ($order['status'] == 1) {
    // Certaines instructions
}

if ($order['status'] == 2) {
    // D'autres instructions
}

// Préférez : (en ayant défini les constantes préalablement bien sûr)
if ($order['status'] == ORDER_STATE_OPEN) {
    // Certaines instructions pour une commande ouverte
}

if ($order['status'] == ORDER_STATE_PAYED) {
    // D'autres instructions pour une commande payée
}

// Pour rappel, création d'une constante
define('ORDER_STATE_OPEN', 'open');

Même principe dans les classes, où l’on peut créer des constantes

class Order
{
    // Une constante peut être public, protected ou private
    // Pas de type à spécifier
    public const STATE_OPEN = 'open';
    public const STATE_PAYED = 'payed';

    public string $state;

    public function randomFunction(): void
    {
        // On utilise self:: pour faire appel à une constante
        if ($this->state === self::STATE_OPEN) {
            // ...
        }
    }
}

Les constantes sont aussi très utiles pour tester/vérifier des valeurs de chaînes de caractères :

// Cette fois-ci je teste la présence d'un langage dans un tableau de compétences.
if (in_array('html', $skills)) {
    // Certaines instructions
}

// Le code ci-dessous n'est pas bon mais ne génère pas d'erreur :
if (in_array('hmtl', $skills)) {
    // Certaines instructions
}

// Alors qu'avec une constante, disons LANGAGE_HTML, ce code génère une erreur :
if (in_array(LANGAGE_HMTL, $skills)) {
    // Certaines instructions
}

Va + loin

D’autres ressources pour bien comprendre et connaître les conventions et bonnes pratiques liées à PHP :

• PSR – 1
• PHP The Right Way

Mettre en pratique

Tu peux choisir un challenge de programmation et appliquer ces bonnes pratiques dès maintenant !

On poursuit la série sur les bonnes pratiques en PHP

Bonnes pratiques PHP #2 typage, protection et comparaison stricte