Widgets WordPress : commencer par les normes

Le but de cette série est de commencer à approfondir le travail avec la programmation orientée objet dans le contexte de WordPress.

Et puisque l’API WordPress Widgets est l’une des API qui utilise des pratiques orientées objet, c’est un point de départ logique. De plus, cela nous donnera quelques techniques fondamentales que nous pourrons utiliser pour les appliquer à des travaux futurs, car nous verrons comment créer davantage de projets orientés objet sur WordPress dans les futures séries.

Jusqu’à présent, nous avons couvert les éléments suivants :

1. Widgets WordPress: une approche orientée objet. L’API Widgets fournit un test décisif solide et un exemple de la façon de démarrer avec la programmation orientée objet dans WordPress.
2. Widgets WordPress: comment détecter la programmation orientée objet. Le but est de vous armer de tout ce dont vous avez besoin pour détecter les pratiques orientées objet.

Si vous n’êtes pas rattrapé, c’est le moment idéal pour le faire. Et si vous avez, alors vous vous souviendrez du dernier message, nous avons terminé avec la note suivante :

Autrement dit, nous allons revoir le WordPress Widget Boilerplate et je vais le refactoriser dans son état actuel pour adopter des normes PHP plus modernes.

Pour commencer à mettre à jour le WordPress Widget Boilerplate pour suivre lesdites normes, nous devons faire quelques choses :

1. créer une branche à partir du passe-partout existant,
2. installer des outils de qualité de code,
3. assurez-vous que notre IDE est correctement configuré,
4. et commencer à refactoriser le code selon ces normes.

Et c’est ce que nous allons commencer à faire avec ce post.

Commencer par les normes

Si vous êtes membre de ce site depuis un certain temps, vous savez que je préfère utiliser Visual Studio Code. Sinon, j’ai toute une série d’articles consacrés à la façon dont je l’utilise (et donc à la façon dont nous l’utiliserons tout au long de cette série d’articles).

Et si vous êtes intéressé par la couverture concernant les normes de codage, le débogage, les IDE, les environnements de développement, etc., consultez The Independent WordPress Developer.

Cependant, je suppose que si vous lisez ceci, vous avez lu le matériel ci-dessus ou vous êtes à l’aise de parcourir tout le matériel ci-dessus.

Cela dit, commençons.

Téléchargement du référentiel

La première chose que vous allez vouloir faire est de cloner une copie du référentiel. Je préfère le faire via la ligne de commande.

De plus, je pense aussi que cela vaut la peine de le faire contre la dernière version de WordPress. Si vous n’avez pas de copie de la copie principale de Subversion de WordPress, vous pouvez lire comment la configurer ici ; cependant, ceci est purement facultatif. Vous pouvez suivre le reste de ce tutoriel très bien avec n’importe quelle version de WordPress que vous souhaitez.

Faire cela,

1. Assurez-vous que vous êtes dans le répertoire des plugins de votre installation WordPress
2. Et puis entrez les commandes suivantes dans une copie de votre terminal

$ 

Cela créera un  répertoire WordPress-Widget-Boilerplate dans votre  répertoire de plugins. Vous pouvez y accéder en tapant simplement :

$ cd WordPress-Widget-Boilerplate

Les résultats du clonage du référentiel devraient ressembler à ceci :

Ensuite, vous devez vous assurer que vous passez à la  branche develop que j’ai créée. C’est vraiment facile à faire. Mais avant cela, pourquoi ne pas configurer le projet dans Visual Studio ?

Configuration du code Visual Studio

Les étapes de configuration du projet dans Visual Studio Code sont simples :

1. Faites glisser le répertoire du Boilerplate dans l’IDE,
2. Ouvrez la borne intégrée,
3. Échanger des succursales

Tout comme je l’ai fait ci-dessus, je vais fournir un screencast sur la façon de faire tout cela. Faire glisser un répertoire dans Visual Studio Code devrait être assez facile, mais échanger des branches sur la ligne de commande peut être un peu différent.

Tout d’abord, configurez le projet dans Visual Studio Code :

Notez ici que j’ouvre également le terminal intégré en appuyant sur le raccourci CMD+P (je suis sur macOS donc votre raccourci peut être différent). Ensuite, j’entre la commande pour vérifier la branche develop .

Une fois que vous avez fait cela, votre référentiel local devrait basculer vers la branche develop. Vous pouvez confirmer qu’il s’agit de la succursale à partir de laquelle vous travaillez en tapant :

$ git branch

Et puis revoir le contenu du terminal. Strictement parlant, développer doit être mis en évidence.

À ce stade, nous allons introduire quelques nouveaux fichiers dans le projet. À la fin de ce didacticiel, vous pouvez former un pull pour obtenir tout ce que je suis sur le point de documenter ici. Mais parce que le but de ce que nous faisons est double, il est important de s’assurer que nous le faisons dans le bon ordre car la première étape est quelque chose que j’utilise dans chaque projet pour WordPress à ce stade.

Donc, cela dit, jetons un coup d’œil.

Compositeur et qualité du code

La première chose que j’aime faire est de mettre en place une série d’outils pour faire respecter la qualité du code. Ceci est réalisé par une variété de packages Composer. Ceux-ci inclus:

• GrumPHP. Un outil de qualité de code PHP. Ne sous-estimez pas la clarté et la mesure dans laquelle ce référentiel regorge d’informations. Si jamais vous êtes bloqué avec l’un des autres outils mentionnés ici, consultez d’abord la documentation de ce référentiel.
• Fixateur PHP CS. Un outil pour résoudre automatiquement les problèmes de normes de codage PHP.
• PHP Parallèle Lint. Cet outil vérifie la syntaxe des fichiers PHP plus rapidement que la vérification en série avec une sortie plus sophistiquée.
• PHPMD. Cet utilitaire prend une base de code source PHP donnée et recherche plusieurs problèmes potentiels dans cette source
• Analyseur PHP. Un analyseur est utile pour l’analyse statique, la manipulation de code et, fondamentalement, toute autre application traitant du code par programmation.
• Gestionnaire de proxy. Cette bibliothèque vise à fournir une abstraction pour générer différents types de classes proxy.

Je veux être clair sur deux choses :

1. Les outils ci-dessus sont le strict minimum que j’utilise, et vous me verrez probablement utiliser des outils supplémentaires à l’avenir,
2. les outils ci-dessus aideront à appliquer les règles de qualité du code avant de vérifier le code dans un référentiel. Il est destiné à compléter la configuration de votre IDE.

Pour que ces outils soient configurés et exécutés dans le projet, nous devrons créer un  fichier composer.json qui ressemble à ceci :

{
    "name": "wordpress-widget-boilerplate/wordpress-widget-boilerplate",
    "description": "An organized, maintainable boilerplate for building widgets using WordPress best practices.",
    "type": "wordpress-plugin",
    "license": "GPL-3.0-or-later",
    "homepage": "https://github.com/tommcfarlin/WordPress-Widget-Boilerplate",
    "authors": [
      {
        "name": "Tom McFarlin",
        "email": "tom@pressware.co",
        "homepage": "https://pressware.co"
      }
    ],
    "support": {
      "issues": "https://github.com/tommcfarlin/WordPress-Widget-Boilerplate/issues"
    },
    "config": {
      "preferred-install": "dist",
      "platform": {
          "php": "7.1"
      }
    },
    "repositories": [
      {
        "type": "composer",
        "url": "https://wpackagist.org"
      }
    ],
    "require": {
      "php": "7.1",
      "composer/installers": "^1.4"
    },
    "require-dev": {
        "friendsofphp/php-cs-fixer": "^2.13.1",
        "jakub-onderka/php-parallel-lint": "^1.0.0",
        "phpmd/phpmd": "^v2.6.0",
        "nikic/php-parser": "^4.0",
        "ocramius/proxy-manager": "^2.0.0",
        "phpro/grumphp": "^0.13.1"
    },
    "scripts": {
      "test": [
        "./vendor/bin/grumphp run"
      ]
    },
    "minimum-stability": "stable"
  }

N’oubliez pas que vous pouvez le faire manuellement à la fin de cet article. Si, toutefois, vous souhaitez suivre, n’hésitez pas à le faire manuellement. Je ne voudrais jamais vous en décourager. 🙂

Une fois que vous avez créé le  fichier composer.json, vous devez vous assurer que vous exécutez la commande suivante depuis le terminal :

$ composer install

Cela peut prendre un certain temps; cependant, une fois que c’est fait, le message suivant devrait s’afficher :

Fais attention! GrumPHP renifle vos commits !

Pour lui donner un essai, entrez la commande suivante dans votre terminal :

$ vendor/bin/grumphp run

Selon la façon dont vous travaillez avec le projet, vous pouvez voir une sortie qui ressemble à ceci :

Mais il reste encore du travail à faire. A savoir, nous devons :

• mettre à jour notre  fichier .gitignore ,
• introduire la configuration pour GrumPHP
• introduire la configuration pour PHPMD,
• introduire la configuration de PHPCS,
• éventuellement, restructurez la structure de répertoires du passe-partout.

Tout jusqu’à l’étape finale, nous allons nous efforcer de le faire dans ce post.

Mise à jour du fichier Ignorer

Tout d’abord, nous ne voulons pas valider le répertoire du fournisseur ou le fichier de verrouillage du compositeur. Ceux-ci peuvent être générés chaque fois qu’un utilisateur télécharge le répertoire. Ils peuvent facilement se désynchroniser et ils ajoutent une taille énorme au répertoire du projet.

Pour cela, votre fichier gitignore devrait ressembler à ceci :

*.DS_Store
*.log
wp-config.php
wp-content/advanced-cache.php
wp-content/backup-db/
wp-content/backups/
wp-content/blogs.dir/
wp-content/cache/
wp-content/upgrade/
wp-content/uploads/
wp-content/mu-plugins/
wp-content/wp-cache-config.php
wp-content/plugins/hello.php

/.htaccess
/license.txt
/readme.html
/sitemap.xml
/sitemap.xml.gz

vendor/
composer.lock

Cela indique au plugin d’ignorer tout ce qui se trouve à la racine du répertoire du plugin (et certains des répertoires éventuels que nous créerons) ainsi que certains fichiers de base que nous avons l’habitude de voir dans les installations WordPress.

Certains de ce que vous voyez, tels que wp-config.php ou wp-content/backups, ne seront probablement jamais vus dans le contexte d’un plugin, mais ce sont des directives d’ignorance WordPress standard que j’aime garder à portée de main.

Vous remarquerez que j’ai également ajouté le fournisseur  et le fichier de verrouillage du compositeur au bas du fichier.

Configurer GrumPHP

GrumPHP peut faire beaucoup, et si vous avez passé du temps à parcourir le référentiel avant de lire jusqu’ici, alors vous le savez probablement ; cependant, je vais le garder aussi simple que possible, afin qu’il fournisse les instructions dont il a besoin pour les outils que nous utilisons et rien de plus.

parameters:
    git_dir: .git
    bin_dir: vendor/bin
    process_timeout: 120
    tasks:
      securitychecker:
      composer:
      jsonlint:
      xmllint:
      yamllint:
      phplint:
        exclude:
          - vendor/
      phpcs:
        metadata:
          priority: 200
      phpcsfixer2:
        allow_risky: true
        config: '.php_cs.dist'
        metadata:
          priority: 300
      phpparser:
        visitors:
          forbidden_function_calls:
            blacklist:
              - "exit"
              - "var_dump"
      phpversion:
        project: '7.1'
      phpmd:
        exclude: ['vendor']
        ruleset: ['phpmd.xml']

En bref, cela signifie exécuter une variété de vérifications pour :

• Sécurité,
• compositeur,
• JSON,
• XML,
• Yaml,
• PHP,
• PHPCS,
• Analyseur PHP,
• PHPMD,
• et plus.

Une fois que nous aurons terminé de configurer tout le reste, je ne manquerai pas de vous montrer comment tout cela s’emboîte. Mais d’abord, finissons de configurer le reste de nos utilitaires.

PHPCS

Cela utilise deux fichiers distincts – un  fichier dist et un  fichier XML – chacun ayant des objectifs différents, bien que très utiles.

Le premier fichier, php_cs.dist que vous verrez dans le référentiel à la fin de cet article, fournit un en-tête appliqué à tous les fichiers PHP de notre projet. Il applique également certaines règles différentes qui améliorent la qualité du code.

Les règles s’expliquent d’elles-mêmes et vous pouvez voir ce qu’elles appliqueront simplement en parcourant chacune des règles définies.

<?php

$header = <<<'EOF'
This file is part of the WordPress Widget Boilerplate
(c) Tom McFarlin <tom@tommcfarlin.com>

This source file is subject to the GPL license that is bundled
with this source code in the file LICENSE.
EOF;

return PhpCsFixerConfig::create()
  ->setRiskyAllowed(true)
  ->setRules([
    '@PHP56Migration' => true,
    '@Symfony' => true,
    '@Symfony:risky' => true,
    'align_multiline_comment' => true,
    'array_syntax' => ['syntax' => 'short'],
    'blank_line_before_statement' => true,
    'combine_consecutive_issets' => true,
    'combine_consecutive_unsets' => true,
    // one should use PHPUnit methods to set up expected exception instead of annotations
    'general_phpdoc_annotation_remove' => ['annotations' => ['expectedException', 'expectedExceptionMessage', 'expectedExceptionMessageRegExp']],
    'header_comment' => ['header' => $header],
    'heredoc_to_nowdoc' => true,
    'list_syntax' => ['syntax' => 'long'],
    'method_argument_space' => ['ensure_fully_multiline' => true],
    'method_chaining_indentation' => false,
    'no_extra_consecutive_blank_lines' => ['tokens' => ['break', 'continue', 'extra', 'return', 'throw', 'use', 'parenthesis_brace_block', 'square_brace_block', 'curly_brace_block']],
    'no_null_property_initialization' => true,
    'no_short_echo_tag' => true,
    'no_unneeded_curly_braces' => true,
    'no_unneeded_final_method' => true,
    'no_unreachable_default_argument_value' => true,
    'no_useless_else' => true,
    'no_useless_return' => true,
    'ordered_class_elements' => true,
    'ordered_imports' => true,
    'php_unit_construct' => true,
    'php_unit_test_class_requires_covers' => true,
    'php_unit_dedicate_assert' => true,
    'phpdoc_add_missing_param_annotation' => true,
    'phpdoc_order' => true,
    'phpdoc_types_order' => ['null_adjustment' => 'always_last'],
    'semicolon_after_instruction' => true,
    'single_line_comment_style' => true,
    'visibility_required' => ['const', 'property', 'method'],
    'yoda_style' => true,
  ])
  ->setFinder(
    PhpCsFixerFinder::create()
      ->exclude(__DIR__. '/vendor/*')
      ->in([
        __DIR__. '/src'
      ])) ;

Ensuite, vous voudrez également créer le fichier XML pour compléter le fichier ci-dessus. Vous remarquerez que dans le fichier que je vous fournis, c’est ce que j’utilise pour mon travail chez Pressware. De plus, il reconnaît également le  répertoire des tests.

À ce stade, nous n’avons pas écrit de tests unitaires, mais si vous choisissez de les introduire dans votre widget, celui-ci sera prêt à les gérer correctement.

<?xml version="1.0"?>
<ruleset name="Pressware">
    <description>Pressware, LLC Coding Standards</description>

    <!-- Scan all files in directory -->
    <file>./src</file>
    <file>./tests</file>
    <exclude-pattern>./tests/phpunit/*</exclude-pattern>
    <!-- Scan only PHP files -->
    <arg name="extensions" value="php"></arg>

    <!-- Show colors in console -->
    <arg value="-colors"></arg>

    <!-- Show sniff codes in all reports -->
    <arg value="ns"></arg>

    <!-- Use PSR-2 as a base -->
    <rule ref="PSR2"></rule>
    <rule ref="Generic.Arrays.DisallowLongArraySyntax.Found" ></rule>

    <!-- Force 2 spaces indentation -->
    <rule ref="Generic.WhiteSpace.ScopeIndent">
        <properties>
            <property name="indent" value="4"></property>
            <property name="tabIndent" value="false"></property>
        </properties>
    </rule>
</ruleset>

Il n’y a qu’un petit ensemble de configuration que je spécifie ici, mais je l’ai trouvé plus que suffisant pour mes besoins jusqu’à présent. Au fur et à mesure que j’en découvre ou que j’opte pour en utiliser davantage, je mettrai certainement à jour le contenu dans les prochains articles.

Configurer PHPMD

Et enfin, nous devons configurer le PHP Mess Detector (ou PHPMD). Heureusement, cela utilise un fichier XML qui utilisera les ensembles de règles définis dans le package installé par Composer. Tout ce que nous avons à faire est de référencer la règle dans le fichier de configuration.

Deuxièmement, nous fournirons également une petite exclusion pour un  nom ShortVariable comme vous le verrez dans l’ essentiel suivant :

<?xml version="1.0" encoding="UTF-8" ?>
<ruleset
    name="VersionEyeModule rules"
    xmlns="http://pmd.sf.net/ruleset/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://pmd.sf.net/ruleset/1.0.0 http://pmd.sf.net/ruleset_xml_schema.xsd"
    xsi:noNamespaceSchemaLocation="http://pmd.sf.net/ruleset_xml_schema.xsd"
>
    <rule ref="rulesets/cleancode.xml" ></rule>
    <rule ref="rulesets/codesize.xml" ></rule>
    <rule ref="rulesets/controversial.xml" ></rule>
    <rule ref="rulesets/design.xml" ></rule>
    <rule ref="rulesets/unusedcode.xml" ></rule>
    <rule ref="rulesets/naming.xml">
        <exclude name="ShortVariable"></exclude>
    </rule>

    <rule ref="rulesets/naming.xml/ShortVariable"
          since="0.2"
          message="Avoid variables with short names like {0}. Configured minimum length is {1}."
          class="PHPMDRuleNamingShortVariable"
          externalInfoUrl="http://phpmd.org/rules/naming.html#shortvariable">
        <priority>3</priority>
        <properties>
            <property name="minimum" description="Minimum length for a variable, property or parameter name" value="3"></property>
            <property name="exceptions" value="id,q,w,i,j,v,e,f,fp" ></property>
        </properties>
    </rule>
</ruleset>

Et une fois que tout cela est en place, nous devrions pouvoir exécuter à nouveau GrumPHP, à partir de la ligne de commande, et avoir un ensemble de résultats légèrement différent.

Exécuter à nouveau GrumPHP

Entrez ce qui suit dans votre terminal :

$ vendor/bin/grumphp run

Et vous devriez voir quelque chose comme ça :

Des résultats différents de la première fois, hein ? C’est parce que nous enfreignons certaines règles et normes qui font partie intégrante de PHP et du développement orienté objet.

Et c’est ce que nous allons nettoyer dans le prochain article.

À venir

Alors d’où vient la nature orientée objet de ceci? Jusqu’à présent, nous avons parlé d’utiliser l’API Widgets comme modèle orienté objet pour écrire du code orienté objet dans WordPress.

Une partie de ce que nous avons fait jusqu’à présent a été exactement cela (en parlant de ses principes, en voyant comment il est présenté, et plus encore).

Mais comme je l’ai mentionné au début de cet article, la mise en place d’outils de qualité de code nous fournit d’abord une base que nous pouvons utiliser lorsque nous refactorisons le passe-partout (ce que nous devons clairement faire compte tenu de la quantité de rouge affichée par GrumPHP).

Et c’est là que nous commencerons dans le prochain article de cette série.