README

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

Installation dans un projet

Prérequis

• PHP ≥ 7.4
• Composer ≥ 2.2

1. Autoriser le plugin dealerdirect ⚠️ obligatoire

Depuis Composer 2.2, tout plugin tiers est bloqué silencieusement s'il n'est pas explicitement autorisé. Sans cette étape, le standard Wyzen ne sera pas enregistré dans PHPCS après l'install, même si le package est bien téléchargé.

Exécutez cette commande dans votre projet avant d'installer le package :

composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true

Cela ajoute automatiquement dans votre composer.json :

"config": {
    "allow-plugins": {
        "dealerdirect/phpcodesniffer-composer-installer": true
    }
}

2. Installer le package

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

L'installation fait automatiquement trois choses :

• enregistre le standard Wyzen dans PHPCS
• crée phpcs.xml.dist à la racine de votre projet s'il n'existe pas encore, ou injecte <rule ref="Wyzen"/> dans votre fichier existant
• ajoute les scripts phpcs et phpcbf dans votre composer.json

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é. Relancez :

composer config allow-plugins.wyzen/phpcs-common-rules 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.dist (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.

Règles SonarQube couvertes

¹ Le sens officiel de ces codes SonarQube diffère légèrement de leur usage ici — le mapping reflète l'intention de la règle dans le contexte Wyzen.

⚠️ S2010 est détectée mais non corrigée automatiquement par phpcbf : and/or et &&/|| n'ont pas la même précédence, la réécriture automatique changerait le comportement du code. Correction manuelle requise.

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.

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

Installer les cinq versions PHP couvertes par la matrice de tests 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 job de la version concernée échoue avec un message expliquant la commande d'installation.

3. Composer

Le script test-matrix.sh télécharge automatiquement composer.phar à la racine du projet si absent. 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 pour chaque version :

1. vérifie que les extensions PHP requises sont présentes
2. installe les dépendances dans envs/<version>/vendor/ si absent
3. enregistre le standard Wyzen dans phpcs
4. lance PHPUnit
5. 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

Publier une nouvelle version

1. Modifier le champ version dans composer.json à la racine ("version": "1.2.3")
2. Merger sur main

Le pipeline GitLab CI crée automatiquement le tag v1.2.3 et Packagist le détecte lors de son prochain crawl (toutes les heures environ).

Architecture du package

phpcs-common-rules/
├── Wyzen/
│   └── ruleset.xml              ← Le standard (référençable via --standard=Wyzen)
├── bin/
│   └── test-matrix.sh           ← Matrice de tests multi-versions PHP
├── 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
│   └── fixtures/
│       ├── clean.php            ← Fichier conforme (0 violation)
│       ├── violations/          ← 9 fixtures non conformes (une par règle)
│       └── fixed/               ← 8 résultats attendus après phpcbf
├── .gitlab-ci.yml
├── composer.json
└── phpunit.xml.dist