README

Standard PHP_CodeSniffer commun aux projets Wyzen : PSR-12 + un jeu de règles reproduisant les contrôles SonarQube. Distribué sous forme de plugin Composer (composer-plugin), publié sur Packagist et versionné via les tags Git.

Installation dans un projet

Prérequis

• PHP ≥ 7.4
• Composer ≥ 2.2

1. Autoriser les plugins Composer ⚠️ obligatoire

Depuis Composer 2.2, tout plugin tiers est bloqué silencieusement s'il n'est pas explicitement autorisé. Sans cette étape, le plugin wyzen-packages/phpcs-common-rules ne s'exécutera pas et le standard Wyzen ne sera pas enregistré dans PHPCS.

Exécutez ces deux commandes dans votre projet avant d'installer le package :

composer config allow-plugins.wyzen-packages/phpcs-common-rules true
composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true

Cela ajoute automatiquement dans votre composer.json :

"config": {
    "allow-plugins": {
        "wyzen-packages/phpcs-common-rules": true,
        "dealerdirect/phpcodesniffer-composer-installer": true
    }
}

2. Installer le package

composer require --dev wyzen-packages/phpcs-common-rules

L'installation exécute automatiquement trois actions via le plugin Composer :

1. Enregistre le standard Wyzen (et Slevomat) dans phpcs via --config-set installed_paths
2. Crée ou met à jour phpcs.xml à la racine de votre projet :
   • si aucun fichier phpcs.xml / phpcs.xml.dist n'existe → crée phpcs.xml avec <rule ref="Wyzen"/>
   • si un fichier existe → injecte <rule ref="Wyzen"/> juste après <ruleset> (idempotent)
3. Injecte les scripts phpcs et phpcbf dans votre composer.json (pointant vers vendor/bin/)

Vérifier que le standard est bien enregistré :

vendor/bin/phpcs -i   # doit lister "Wyzen"

Si Wyzen n'apparaît pas, c'est que le plugin n'a pas tourné. Vérifiez les permissions et relancez :

composer config allow-plugins.wyzen-packages/phpcs-common-rules true
composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer install

3. Utiliser le standard

# Via vendor/bin directement
vendor/bin/phpcs src/
vendor/bin/phpcbf src/

# Ou via les scripts Composer (ajoutés automatiquement dans votre composer.json)
composer phpcs
composer phpcbf

4. Configuration via phpcs.xml (recommandé)

<?xml version="1.0"?>
<ruleset name="MonProjet">
    <file>src</file>
    <file>tests</file>
    <arg name="extensions" value="php"/>
    <arg name="colors"/>
    <arg value="sp"/>

    <exclude-pattern>*/vendor/*</exclude-pattern>

    <rule ref="Wyzen"/>

    <!-- Exemples de surcharges -->

    <!--
    Neutraliser une règle :
    <rule ref="Squiz.Operators.ValidLogicalOperators">
        <severity>0</severity>
    </rule>
    -->

    <!--
    Augmenter la limite de longueur de ligne :
    <rule ref="Generic.Files.LineLength">
        <properties>
            <property name="lineLimit" value="140"/>
            <property name="absoluteLineLimit" value="0"/>
        </properties>
    </rule>
    -->
</ruleset>

Toutes les surcharges placées après <rule ref="Wyzen"/> l'emportent sur le standard.

Développement du package

Prérequis

1. phpvm

phpvm est requis pour gérer les versions PHP en local. Le script test-matrix.sh l'utilise pour résoudre les binaires PHP et installer automatiquement les versions manquantes.

curl -fsSL https://raw.githubusercontent.com/Thavarshan/phpvm/main/bin/install.sh | bash
source ~/.bashrc   # ou ~/.zshrc

Vérifier l'installation :

phpvm --version

2. Versions PHP

Le script test-matrix.sh installe automatiquement les versions PHP manquantes via phpvm install. Si vous préférez les installer manuellement via le PPA ondrej/php (Ubuntu/Debian) :

sudo add-apt-repository ppa:ondrej/php
sudo apt-get update
sudo apt-get install -y \
  php7.4 php7.4-xml php7.4-mbstring \
  php8.2 php8.2-xml php8.2-mbstring \
  php8.3 php8.3-xml php8.3-mbstring \
  php8.4 php8.4-xml php8.4-mbstring \
  php8.5 php8.5-xml php8.5-mbstring

Les extensions xml et mbstring sont requises par PHPUnit. Sans elles, le script affiche la commande apt-get à exécuter et s'arrête sur la version concernée.

3. Composer

Le script test-matrix.sh télécharge automatiquement composer.phar à la racine du projet si absent ou si sa version est inférieure à 2.6 (requis pour PHP 8.5). Aucune installation manuelle n'est nécessaire.

Mise en place

git clone git@gitlab.com:wyzen-packages/phpcs-common-rules.git
cd phpcs-common-rules

# Activer le hook pre-commit (lance PHPUnit avant chaque commit)
git config core.hooksPath .githooks

Lancer les tests

Matrice complète (7.4, 8.2, 8.3, 8.4, 8.5)

bash bin/test-matrix.sh

Le script effectue pour chaque version :

1. vérifie et installe phpvm, composer.phar et la version PHP si absents (bootstrap automatique)
2. installe les dépendances dans envs/<version>/vendor/ si le dossier est absent
3. vérifie que les extensions PHP requises par PHPUnit sont chargées
4. lance PHPUnit
5. enregistre le standard Wyzen dans phpcs (--config-set installed_paths)
6. vérifie que phpcs -i liste bien Wyzen

Tableau récapitulatif version → OK/FAIL en fin d'exécution. Exit ≠ 0 si une version échoue.

Une seule version

bash bin/test-matrix.sh 8.3

Forcer la réinstallation des dépendances

bash bin/test-matrix.sh --install          # toutes les versions
bash bin/test-matrix.sh --install 8.3     # une version

Ce que testent les suites

Suite	Couverture
RulesetValidityTest	Le standard Wyzen est listé par phpcs -i, tous les sniffs sont chargés, un fichier propre produit 0 violation
RuleDetectionTest	Chacune des 9 règles SonarQube détecte bien sa fixture de violation
FixerTest	Les 8 règles auto-fixables produisent le résultat attendu ; S2010 reste non fixé après phpcbf

Test d'intégration end-to-end

Le script tests/integration/run.sh vérifie le comportement du plugin Composer dans un projet client réel, indépendamment des suites PHPUnit.

Ce qu'il fait

1. Copie tests/integration/project/ dans /tmp/wyzen-phpcs-integration-test
2. Réécrit le path repository avec le chemin absolu du repo local
3. Lance composer require wyzen-packages/phpcs-common-rules:dev-main sans Packagist (source locale uniquement)
4. Vérifie les assertions (voir ci-dessous)
5. Lance composer reinstall pour tester l'idempotence
6. Supprime le répertoire temporaire (sauf avec --keep)

Assertions vérifiées

#	Assertion
1	phpcs.xml créé à la racine (pas .dist) et contient <rule ref="Wyzen"/>
2	vendor/bin/phpcs et vendor/bin/phpcbf présents, exécutables, sans warning PHP
3	composer.json client : scripts.phpcs et scripts.phpcbf pointent vers vendor/bin/
4	vendor/bin/phpcs -i liste le standard Wyzen sans erreur
5	phpcs --standard=Wyzen fonctionne sans sniff manquant
6	Idempotence : <rule ref="Wyzen"/> présent exactement 1 fois après reinstall
7	Idempotence : scripts.phpcs présent exactement 1 fois dans composer.json
8	Idempotence : installed_paths ne contient pas de doublon wyzen-packages

Lancer le test

bash tests/integration/run.sh

# Conserver le projet dans /tmp après un échec (pour inspecter)
bash tests/integration/run.sh --keep

Dépendances : php ≥ 7.4, jq, et composer (global) ou .composer.phar à la racine du repo. .composer.phar est créé automatiquement par test-matrix.sh si vous l'avez déjà lancé.

Publier une nouvelle version

Le versioning est manuel via le pipeline GitLab CI. Aucune modification de composer.json n'est nécessaire — le CI gère le tag et l'incrément de version.

1. S'assurer que la branche main est à jour et que tous les jobs test:php* passent
2. Dans GitLab → CI/CD → Pipelines, ouvrir le pipeline de main
3. Déclencher manuellement l'un des jobs de versioning :
   • version:patch — bug fix (1.2.3 → 1.2.4)
   • version:minor — nouvelle fonctionnalité rétro-compatible (1.2.3 → 1.3.0)
   • version:major — changement cassant (1.2.3 → 2.0.0)

Le job crée automatiquement le tag Git correspondant. Packagist (wyzen-packages/phpcs-common-rules) le détecte lors de son prochain crawl (toutes les heures environ).

Prérequis CI : la variable GITLAB_TOKEN doit être configurée dans Settings → CI/CD → Variables avec un token ayant les droits write_repository.

Architecture du package

phpcs-common-rules/
├── Wyzen/
│   └── ruleset.xml              ← Le standard (référençable via --standard=Wyzen)
├── src/
│   └── Plugin.php               ← Plugin Composer : enregistre Wyzen, crée phpcs.xml, injecte les scripts
├── bin/
│   └── test-matrix.sh           ← Matrice de tests multi-versions PHP (bootstrap automatique)
├── envs/
│   ├── 7.4/                     ← Environnement isolé PHP 7.4 (composer.json, vendor/, phpunit.xml.dist)
│   ├── 8.2/
│   ├── 8.3/
│   ├── 8.4/
│   └── 8.5/
├── tests/
│   ├── PhpcsRunner.php          ← Helper : lance phpcs/phpcbf, parse le JSON
│   ├── RulesetValidityTest.php
│   ├── RuleDetectionTest.php
│   ├── FixerTest.php
│   ├── integration/             ← Tests d'intégration end-to-end (install dans un projet fictif)
│   └── fixtures/
│       ├── clean.php            ← Fichier conforme (0 violation)
│       ├── violations/          ← 9 fixtures non conformes (une par règle)
│       └── fixed/               ← 8 résultats attendus après phpcbf
├── .githooks/
│   └── pre-commit               ← Lance PHPUnit avant chaque commit
├── .gitlab-ci.yml
├── composer.json
└── phpunit.xml.dist