Présentation

• PHPCS (ou PHP_CodeSniffer) est un outil permettant de vérifier la qualité d'un code par rapport à des patterns prédéfinies.
• PSR-12 est un ensemble de patterns définissant les bonnes pratiques de codage déterminées par un ensemble de développeurs représentant une majorité de CMS, framework, projets PHP (open-source).
• PHPCompatibility est un ensemble de patterns permettant de détecter les incompatibilités avec les nouvelles versions de PHP.

Avantages

• Ces outils permettent de s'assurer d'une hygiène de développement et une standardisation des fichiers facilitant leur reprise et évolution ultérieure quelque soit le développeur ou l'IDE.
• La détection automatisée d'incohérences dans le code peut prévenir des erreurs telle l'oubli d'un point-virgule.
• La gestion des fonctions deprecated permet également d'anticiper les mises à jour de PHP et de détecter de futures erreurs.

Mise en oeuvre simple

• Récupérer les fichiers dans /folder/ (/folder/phpcs.phar et /folder/PHPCompatibility-x.y.z/PHPCompatibility)
• Ajouter PHPCompatibility à PHPCS : php /folder/phpcs.phar --config-set installed_paths /folder/PHPCompatibility-x.y.z/PHPCompatibility
• Lancer PHPCS avec les patterns à utiliser php /folder/phpcs.phar --standard=PHPCompatibility /folder/with/php/files ou php /folder/phpcs.phar --standard=PSR12 /folder/with/php/files

Créer un jeu de règles (ruleset)

Pour définir l'ensemble de nos règles directement :

• Créer un fichier /folder/myRuleset.xml :

  <?xml version="1.0"?>
  <ruleset name="myRuleset">
  <description>Toutes mes règles PHPCS.</description>
  <!-- Inclure PSR-12 -->
  <rule ref="PSR12" />
  <!-- Inclure PHPCompatibility -->
  <rule ref="PHPCompatibility"/>
  </ruleset>

• php /folder/phpcs.phar --standard=/folder/myRuleset.xml /folder/with/php/files

Exclure des règles

Certaines règles peuvent ne pas convenir au projet, il est possible de les ignorer :

• Déterminer la règle posant souci : php /folder/phpcs.phar -s --standard=/folder/myRuleset.xml /folder/with/php/files. Le nom de la règle causant l'avertissement est désormais affichée (exemple : (Generic.Files.LineEndings.InvalidEOLChar))
• Modifier le fichier myRuleset.xml pour ignorer spécifiquement cette règle

  ...
  <!-- Inclure PSR-12 -->
  <rule ref="PSR12">
      <!-- Exclure les CRLF gérés par git => core.autocrlf=true ) -->
              <exclude name="Generic.Files.LineEndings.InvalidEOLChar" />
  </rule>
  ...

Automatisation des vérifications sur GitHub

Ces vérifications peuvent être effectuées automatiquement lors de l'envoi de code sur GitHub.

• Créer un fichier /.github/workflows/main.yml

  > # This is a basic workflow to help you get started with Actions
  > 
  > name: CI
  > 
  > # Controls when the action will run. 
  > on:
  >   # Triggers the workflow on push or pull request events but only for the main branch
  >   push:
  >     branches: [ main ]
  >   pull_request:
  >     branches: [ main ]
  > 
  >   # Allows you to run this workflow manually from the Actions tab
  >   workflow_dispatch:
  > 
  > # A workflow run is made up of one or more jobs that can run sequentially or in parallel
  > jobs:
  >   # This workflow contains a single job called "build"
  >   build:
  >     # The type of runner that the job will run on
  >     runs-on: ubuntu-latest
  > 
  >     # Steps represent a sequence of tasks that will be executed as part of the job
  >     steps:
  >       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
  >       - uses: actions/checkout@v2
  > 
  >       - name: Setup PHP
  >         uses: shivammathur/setup-php@v2
  >         with:
  >           php-version: '7.4'
  >           tools: cs2pr, phpcs
  > 
  >       - name: Run phpcs
  >         run: phpcs -q --standard=myRuleset.xml --report=checkstyle $GITHUB_WORKSPACE | cs2pr

Sources

• https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-Ruleset