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 :

Enregistre le standard Wyzen (et Slevomat) dans phpcs via --config-set installed_paths
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)
Réécrit sept scripts dans votre composer.json (écrasement systématique à chaque install/update) :
- lint — analyse complète (erreurs + warnings)
- lint:errors — erreurs uniquement, sans warnings (-n)
- lint:pre-commit — corrige puis vérifie les fichiers stagés (pour hook git)
- lint:fix-staged — phpcbf sur les fichiers stagés (--filter=GitStaged)
- lint:check-staged — phpcs -n sur les fichiers stagés (--filter=GitStaged)
- lint:fix — correction automatique sur tout le projet
- lint:register — réenregistre les standards dans phpcs (utile hors Docker)

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/

# Via les scripts Composer (ajoutés automatiquement dans votre composer.json)
composer lint                # toutes les violations (erreurs + warnings)
composer lint:errors         # erreurs uniquement (-n, sans warnings)
composer lint:fix            # correction automatique sur tout le projet
composer lint:pre-commit     # fix + check sur les fichiers stagés (hook git)
composer lint:register       # réenregistrer les standards (utile hors Docker)

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 (matrice + intégration 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 :

vérifie et installe phpvm, composer.phar et la version PHP si absents (bootstrap automatique)
installe les dépendances dans envs/<version>/vendor/ si le dossier est absent
vérifie que les extensions PHP requises par PHPUnit sont chargées
lance PHPUnit
enregistre le standard Wyzen dans phpcs (--config-set installed_paths)
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 bin/test-integration.sh vérifie le comportement du plugin Composer dans un projet client réel, indépendamment des suites PHPUnit.

Ce qu'il fait

Copie tests/integration/project/ dans /tmp/wyzen-phpcs-integration-test
Réécrit le path repository avec le chemin absolu du repo local
Lance composer require wyzen-packages/phpcs-common-rules:dev-main sans Packagist (source locale uniquement)
Vérifie les assertions (voir ci-dessous)
Lance composer reinstall pour tester l'idempotence
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.lint` et `scripts["lint:fix"]` 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 bin/test-integration.sh

# Conserver le projet dans /tmp après un échec (pour inspecter)
bash bin/test-integration.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.

S'assurer que la branche main est à jour et que tous les jobs test:php* passent
Dans GitLab → CI/CD → Pipelines, ouvrir le pipeline de main
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)
│   └── test-integration.sh      ← Test d'intégration end-to-end (install dans un projet fictif)
├── 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/             ← Projet fictif utilisé par bin/test-integration.sh
│   └── 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 la matrice + le test d'intégration avant chaque commit
├── .gitlab-ci.yml
├── composer.json
└── phpunit.xml.dist

wyzen-packages / phpcs-common-rules

Maintainers

Package info

Statistics

Security

README

Installation dans un projet

Prérequis

1. Autoriser les plugins Composer ⚠️ obligatoire

2. Installer le package

3. Utiliser le standard

4. Configuration via `phpcs.xml` (recommandé)

Développement du package

Prérequis

1. phpvm

2. Versions PHP

3. Composer

Mise en place

Lancer les tests

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

Une seule version

Forcer la réinstallation des dépendances

Ce que testent les suites

Test d'intégration end-to-end

Ce qu'il fait

Assertions vérifiées

Lancer le test

Publier une nouvelle version

Architecture du package

wyzen-packages / phpcs-common-rules

Maintainers

Package info

Statistics

Security

README

Installation dans un projet

Prérequis

1. Autoriser les plugins Composer ⚠️ obligatoire

2. Installer le package

3. Utiliser le standard

4. Configuration via phpcs.xml (recommandé)

Développement du package

Prérequis

1. phpvm

2. Versions PHP

3. Composer

Mise en place

Lancer les tests

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

Une seule version

Forcer la réinstallation des dépendances

Ce que testent les suites

Test d'intégration end-to-end

Ce qu'il fait

Assertions vérifiées

Lancer le test

Publier une nouvelle version

Architecture du package

4. Configuration via `phpcs.xml` (recommandé)