Bonnes Pratiques PHP : Écrire du Code Propre et Lisible

Quand on débute en PHP, on écrit souvent du code qui fonctionne... mais qui devient illisible après quelques semaines. Dans cet article, je vous guide pas à pas à travers les conventions PHP qui feront de vous un développeur professionnel.

Pourquoi des conventions ?

Imaginez que vous travaillez sur un projet avec 5 autres développeurs. Si chacun nomme ses variables différemment, le code devient un cauchemar à maintenir. Les PSR (PHP Standards Recommendations) sont des règles adoptées par la communauté PHP pour que tout le monde parle le même langage.

Règle d'or : Écrivez votre code comme si la personne qui va le maintenir est un psychopathe violent qui connaît votre adresse.

Le nommage explicite : la base de tout

Le plus grand piège des débutants : utiliser des noms courts pour "gagner du temps". Regardez cet exemple :

// Code de débutant (à éviter)
$u = getUsers();
$d = new DateTime();
$n = 0;

foreach ($u as $x) {
    if ($x['active']) {
        $n++;
    }
}

Après 2 semaines, vous ne saurez plus ce que fait ce code. Voici la version professionnelle :

// Code professionnel (à adopter)
$activeUsers = getUsers();
$currentDate = new DateTime();
$activeUserCount = 0;

foreach ($activeUsers as $user) {
    if ($user['active']) {
        $activeUserCount++;
    }
}

Le code se lit maintenant comme une phrase en anglais. Pas besoin de commentaires pour comprendre ce qu'il fait.

Évitez les abréviations ambiguës

// Mauvais : que signifie "num" ?
$userNum = 42;

// Bon : c'est clair
$userPhoneNumber = "06 12 34 56 78";
$numberOfUsers = 42;
$userIdentifier = 42;

Les conventions de nommage PHP

PHP utilise différentes conventions selon le type d'élément. Voici le récapitulatif complet :

1. Variables et fonctions : camelCase

Le camelCase commence par une minuscule, puis chaque nouveau mot commence par une majuscule (comme les bosses d'un chameau).

// Variables en camelCase
$firstName = "Jean";
$lastName = "Dupont";
$isLoggedIn = true;
$totalOrderAmount = 150.99;

// Fonctions en camelCase
function calculateTotalPrice(array $items): float
{
    $total = 0;
    foreach ($items as $item) {
        $total += $item['price'] * $item['quantity'];
    }
    return $total;
}

function isUserAdmin(int $userId): bool
{
    return in_array($userId, [1, 2, 3]);
}

2. Tableaux associatifs : snake_case

Les clés des tableaux utilisent le snake_case (mots séparés par des underscores).

// Structure d'un utilisateur
$user = [
    'id' => 1,
    'first_name' => 'Marie',
    'last_name' => 'Martin',
    'email_address' => 'marie@example.com',
    'created_at' => '2024-01-15 10:30:00',
    'is_verified' => true,
];

// Structure d'une commande
$order = [
    'order_number' => 'CMD-2024-001',
    'total_amount' => 299.99,
    'shipping_address' => [
        'street_name' => '15 rue de la Paix',
        'postal_code' => '75001',
        'city_name' => 'Paris',
    ],
];

3. Constantes : MAJUSCULES

Les constantes s'écrivent en MAJUSCULES avec des underscores.

// Constantes globales
define('MAX_LOGIN_ATTEMPTS', 5);
define('DEFAULT_LANGUAGE', 'fr');
define('API_BASE_URL', 'https://api.example.com');

// Utilisation
if ($loginAttempts >= MAX_LOGIN_ATTEMPTS) {
    echo "Compte bloqué après " . MAX_LOGIN_ATTEMPTS . " tentatives.";
}

4. Classes : PascalCase

Les noms de classes utilisent le PascalCase (chaque mot commence par une majuscule).

// Fichier: User.php
class User
{
    private string $firstName;
    private string $email;
    
    public function __construct(string $firstName, string $email)
    {
        $this->firstName = $firstName;
        $this->email = $email;
    }
}

// Fichier: OrderManager.php  
class OrderManager
{
    public function processOrder(Order $order): bool
    {
        // ...
    }
}

// Fichier: EmailNotificationService.php
class EmailNotificationService
{
    public function sendWelcomeEmail(User $user): void
    {
        // ...
    }
}

Les accolades : où les placer ?

Cette question génère des débats passionnés ! En PHP, la convention PSR-12 est claire :

Classes et fonctions : accolade à la ligne suivante

class Product
{
    private string $name;
    private float $price;
    
    public function __construct(string $name, float $price)
    {
        $this->name = $name;
        $this->price = $price;
    }
    
    public function getPriceWithTax(float $taxRate): float
    {
        return $this->price * (1 + $taxRate);
    }
}

Structures de contrôle : accolade sur la même ligne

function processItems(array $items): array
{
    $results = [];
    
    foreach ($items as $item) {
        if ($item['stock'] > 0) {
            $results[] = $item;
        } else {
            echo "Produit en rupture : " . $item['name'];
        }
    }
    
    return $results;
}

Toujours utiliser des accolades

Même pour une seule instruction, utilisez des accolades. Cela évite des bugs subtils.

// Dangereux (à éviter)
if ($isAdmin)
    deleteAllUsers();  // Une erreur d'indentation peut être fatale

// Sécurisé (à adopter)
if ($isAdmin) {
    deleteAllUsers();
}

Les constantes : vos alliées contre les bugs

Utiliser des constantes plutôt que des valeurs "magiques" rend votre code plus sûr et plus lisible.

Le problème des valeurs magiques

// Code fragile avec des "magic numbers"
if ($order->status === 1) {
    // C'est quoi 1 ? Personne ne sait...
}

if ($order->status === 2) {
    // Et 2 ? Mystère...
}

// Pire : une faute de frappe silencieuse
if ($user->role === 'admni') {  // Faute non détectée !
    grantAllAccess();
}

La solution : les constantes de classe

class Order
{
    public const STATUS_PENDING = 'pending';
    public const STATUS_PAID = 'paid';
    public const STATUS_SHIPPED = 'shipped';
    public const STATUS_DELIVERED = 'delivered';
    public const STATUS_CANCELLED = 'cancelled';
    
    private string $status;
    
    public function __construct()
    {
        $this->status = self::STATUS_PENDING;
    }
    
    public function markAsPaid(): void
    {
        $this->status = self::STATUS_PAID;
    }
    
    public function canBeCancelled(): bool
    {
        return in_array($this->status, [
            self::STATUS_PENDING,
            self::STATUS_PAID,
        ]);
    }
}

// Utilisation claire et sécurisée
$order = new Order();

if ($order->status === Order::STATUS_PENDING) {
    echo "Commande en attente de paiement";
}

// Si vous faites une faute, PHP génère une erreur
if ($order->status === Order::STATUS_PNEDING) {  // ERREUR détectée !
    // ...
}

Les mots-clés : quelques règles simples

class UserService
{
    // Toujours déclarer la visibilité (public, protected, private)
    private UserRepository $repository;
    
    // abstract et final AVANT la visibilité
    // static APRÈS la visibilité
    public static function getInstance(): self
    {
        // ...
    }
    
    // true, false, null en minuscules
    public function findUser(int $id): ?User
    {
        $user = $this->repository->find($id);
        
        if ($user === null) {
            return null;
        }
        
        if ($user->isActive === false) {
            return null;
        }
        
        return $user;
    }
}

Récapitulatif : la checklist du code propre

• Variables et fonctions : camelCase ($userName, getUserById())
• Clés de tableaux : snake_case ('first_name', 'created_at')
• Constantes : MAJUSCULES (MAX_RETRY, API_URL)
• Classes : PascalCase (UserController, OrderService)
• Nommage explicite : pas d'abréviations, noms descriptifs
• Accolades obligatoires : même pour une ligne
• Constantes vs valeurs magiques : toujours préférer les constantes

Pour aller plus loin

Ces conventions sont issues des standards PSR-1 et PSR-12. Je vous recommande de :

• Installer un linter comme PHP CS Fixer ou PHP_CodeSniffer
• Configurer votre IDE pour formater automatiquement le code
• Consulter php-fig.org pour les standards officiels

Dans le prochain article, nous aborderons le typage strict et les comparaisons sécurisées pour écrire du code encore plus robuste.