Intervenir dans un programme de plus de 100 k lignes de code peut intimider. Par où commencer ? Comment éviter de casser quelque chose qui fonctionne déjà ? Comment être sûr que les modifications respectent les bonnes pratiques du projet ?

Avec MyClub, vous n'êtes pas seul face au code. Le projet vous guide, vous accompagne et vérifie votre travail. Voyons comment !

Une organisation simple

À la racine du dépôt GitHub, tout est déjà bien rangé :

.
├── dev
├── doc
├── LICENSE
├── README.md
└── WebSite

Difficile de faire plus explicite !

• WebSite contient l'application MyClub.
• dev regroupe les outils et les tests destinés aux développeurs.
• doc accueille la documentation.
• README.md présente le projet.
• LICENSE précise les conditions de réutilisation du logiciel.

Vous savez où chercher et où intervenir. Pas besoin de parcourir tout le code pour comprendre l'organisation générale.

Deux scripts pour tout vérifier

Avant de valider vos modifications, il suffit de lancer le script prévu à cet effet :

dev/tools/BeforeCommit.sh

Et MyClub se met au travail !

Le script exécute sept contrôles successifs.

1. phpcbf : remettre le code en forme

Corrige automatiquement les problèmes de présentation que l'outil sait réparer.

L'indentation, les espaces et d'autres détails de mise en forme sont normalisés.

Vous pouvez vous concentrer sur le fond plutôt que de perdre du temps à ajuster manuellement chaque fichier.

2. phpcs : contrôler les conventions

Vérifie que le code respecte les conventions retenues pour le projet.

Une présentation homogène rend les fichiers plus faciles à lire, à comprendre et à maintenir, même lorsqu'ils ont été écrits par des contributeurs différents.

3. PHPStan : détecter les erreurs de typage

PHPStan analyse le code sans avoir besoin d'exécuter tous les scénarios possibles.

Il peut notamment détecter des types incohérents, des valeurs potentiellement nulles ou des appels qui ne correspondent pas aux méthodes disponibles.

C'est un filet de sécurité supplémentaire, particulièrement utile lorsqu'on modifie une application de cette taille.

4. Vérifier la présence des tests

Le script vérifie que les classes qui accède aux données disposent des tests attendus.

Chaque classe  doit posséder une classe de test qui vérifie que toutes les tables et champs requétés sont bien toujours présent sdans la base de données.

5. PHPUnit : exécuter les tests

Les tests automatisés vérifient que les fonctionnalités se comportent comme prévu.

6. Coding standards check : les règles propres à MyClub

C'est ici que le projet va plus loin que les conventions générales de PHP.

Dans dev/test/CodingStandards/Rules/, on trouve notamment :

ApisRule.php
ControllersRule.php
DatabaseAccessRule.php
FinalClassesRule.php
FinalReadonlyRule.php
ObjectShapeDocblockRule.php
ReadonlyPropertiesRule.php
RuleInterface.php

Ces règles contrôlent des choix d'architecture et des bonnes pratiques propres à MyClub.

Par exemple :

• ApisRule les routes qui retourne du JSON sont de la forme /api/....
• ControllersRule contrôle des règles concernant les contrôleurs.
• DatabaseAccessRule respect la centralisation des accès aux bases de données.
• FinalClassesRule vérifie l'utilisation attendue du mot-clé final.
• FinalReadonlyRule contrôle des conventions autour des classes final et readonly.
• ObjectShapeDocblockRule vérifie certaines déclarations de formes de tableaux dans les annotations de types.
• ReadonlyPropertiesRule contrôle des règles concernant les propriétés en lecture seule.

Ce ne sont donc pas simplement des règles de présentation. Elles permettent de transformer des décisions d'architecture en contrôles automatiques.

Une règle documentée est utile. Une règle vérifiée automatiquement est encore plus efficace !

7. Vérifier le cache des scripts JavaScript

Le dernier contrôle vérifie que les scripts JavaScript utilisent le filtre |version.

Ce mécanisme permet de faire évoluer la version des ressources et d'éviter que le navigateur conserve indéfiniment une ancienne version d'un script après une mise à jour.

Et ensuite ?

Si tous les contrôles passent, le script affiche : All checks passed, ready for commit.

Vous pouvez alors préparer votre commit avec davantage de confiance.

Si un contrôle échoue, vous disposez d'une indication concrète sur ce qu'il faut corriger avant d'aller plus loin.

8. Les tests fonctionnels : vérifier l'application en conditions réelles

Les contrôles précédents vérifient la qualité du code et exécutent les tests automatisés. Mais il reste une question essentielle : est-ce que l'application fonctionne correctement lorsqu'on l'utilise réellement ?

MyClub dispose d'un outil pour aller beaucoup plus loin : FlightRouteTester.php.

Démarrer le serveur de développement

Dans un premier terminal, depuis le répertoire dev du projet, on lance le serveur local :

./StartPhpServer.sh

Le script prépare l'environnement avant de démarrer le serveur :

• il vide le cache Latte ;
• il nettoie les journaux Tracy ;
• il configure les permissions des fichiers SQLite ;
• il vérifie que les bases de données sont accessibles en écriture ;
• il démarre le serveur PHP sur http://localhost:8000.

Un environnement de développement prêt à l'emploi, sans devoir refaire manuellement toutes ces opérations !

Lancer les tests des routes

Dans un deuxième terminal, on exécute :

cd ~/Clones/GitHub/MyClub/dev/test
php FlightRouteTester.php --stop

Le programme parcourt les scénarios de test définis pour les routes de l'application. Il vérifie notamment les réponses obtenues selon les requêtes, les paramètres et les autorisations des utilisateurs.

L'intérêt est considérable : une route ne doit pas seulement fonctionner pour un webmaster connecté. Elle doit également se comporter correctement lorsqu'un membre dispose de droits limités, lorsqu'un visiteur n'est pas connecté ou lorsque les paramètres transmis sont invalides.

Une réponse HTTP 403, par exemple, n'est pas nécessairement une erreur : elle peut être précisément le résultat attendu lorsqu'un utilisateur n'a pas l'autorisation d'effectuer une action.

Le résultat attendu

Voici un exemple de résultat obtenu après l'exécution de la suite complète :

================================================================================
TEST SUMMARY
================================================================================
Total tests executed: 6000
Success: 6000
Failures: 0
Others: 0

================================================================================
VALIDATION ERRORS:
================================================================================
Parameter errors: 0
Response errors: 0
Data errors: 0
Authentication errors: 0

Breakdown by HTTP status code:
  200: 2004
  403: 3476
  400: 502
  303: 18

============================================================
Tests finished
Total time: 418.68 s (6.98 min)
============================================================

En un peu moins de sept minutes, l'outil a vérifié un grand nombre de scénarios couvrant les routes de MyClub.

Le plus important n'est pas d'obtenir uniquement des réponses 200. C'est d'obtenir la réponse attendue pour chaque scénario, y compris lorsque l'accès doit être refusé.

Les compteurs d'errreurs doivent tous être à zéro.

Un filet de sécurité à l'échelle de l'application

Ces tests complètent les tests unitaires. Ils permettent de détecter des régressions qui pourraient passer inaperçues lorsqu'on ne vérifie qu'une classe isolée.

Ils ne prouvent pas que chaque combinaison imaginable est exempte de défauts, mais ils donnent une couverture fonctionnelle importante et reproductible.

Et surtout, ils permettent de vérifier que les règles d'accès ne sont pas seulement documentées : elles sont réellement mises à l'épreuve.

Avant de contribuer à MyClub, vous pouvez donc vérifier votre travail à plusieurs niveaux : style du code, typage, architecture, tests unitaires et tests fonctionnels sur les routes.

C'est cela, travailler sur des rails !

Et si vous n'êtes pas encore un expert de MyClub ?

Vous n'avez pas besoin de connaître immédiatement toutes les lignes du projet.

Vous pouvez commencer par un défaut à corriger, une petite amélioration, un test manquant ou une règle de codage à renforcer. L'essentiel est de comprendre la partie sur laquelle vous intervenez et de vérifier que votre modification respecte le fonctionnement existant.

Les outils automatisés prennent en charge une partie des vérifications répétitives. Ils ne remplacent ni votre réflexion ni la revue du code, mais ils vous aident à travailler plus sereinement.

À vous de contribuer !

Les règles actuelles ne sont certainement pas les dernières.

Quelles bonnes pratiques de codage PHP souhaiteriez-vous voir contrôlées automatiquement dans MyClub ?

Une règle concernant les contrôleurs ? La séparation des responsabilités ? Les accès aux données ? Les types ? Les tests ? La sécurité ?

Il y a probablement encore de nombreuses règles pertinentes à ajouter.

Si vous avez une idée, une expérience à partager ou l'envie de proposer une nouvelle règle, n'hésitez pas à participer !

MyClub est un logiciel libre sous licence GPL-3.0. Son code est ouvert, ses contrôles sont visibles et chacun peut contribuer à améliorer le projet.

Avec MyClub, les rails sont en place. À nous de les améliorer ensemble !