Widget WordPress: a partire dagli standard

Lo scopo di questa serie è iniziare a fare un tuffo più profondo nel lavorare con la programmazione orientata agli oggetti nel contesto di WordPress.

E poiché l’API dei widget di WordPress è una delle API che utilizza pratiche orientate agli oggetti, è un punto di partenza logico. Inoltre, ci fornirà alcune tecniche di base che possiamo utilizzare per applicare al lavoro futuro mentre vediamo come costruire più progetti orientati agli oggetti su WordPress nelle serie future.

Finora, abbiamo trattato quanto segue:

1. Widget WordPress: un approccio orientato agli oggetti. L’API Widgets fornisce una solida cartina di tornasole ed un esempio di come iniziare con la programmazione orientata agli oggetti in WordPress.
2. Widget WordPress: come rilevare la programmazione orientata agli oggetti. L’obiettivo è fornirti tutto ciò di cui hai bisogno per rilevare le pratiche orientate agli oggetti.

Se non sei preso, ora è un ottimo momento per farlo. E se l’hai fatto, ricorderai dall’ultimo post, abbiamo concluso con la seguente nota:

Cioè, rivisiteremo il WordPress Widget Boilerplate e lo refactoring nel suo stato attuale per adottare standard PHP più moderni.

Per iniziare ad aggiornare il WordPress Widget Boilerplate per seguire detti standard, dobbiamo fare alcune cose:

1. creare un ramo dal boilerplate esistente,
2. installare strumenti di qualità del codice,
3. assicurati che il nostro IDE sia impostato correttamente,
4. e iniziare il refactoring del codice in base a detti standard.

Ed è quello che inizieremo a fare con questo post.

A cominciare dagli standard

Se sei un membro di questo sito da tempo, allora sai che preferisco usare Visual Studio Code. In caso contrario, ho un’intera serie di articoli dedicati a come lo uso (e quindi a come lo utilizzeremo in questa serie di post).

E se sei interessato alla copertura relativa a standard di codifica, debugging, IDE, ambienti di sviluppo e così via, dai un’occhiata a The Independent WordPress Developer.

Tuttavia, presumo che se stai leggendo questo, allora hai letto il materiale sopra o ti senti a tuo agio nell’esaminare tutto il materiale sopra.

Detto questo, iniziamo.

Download del repository

La prima cosa che vorrai fare è clonare una copia del repository. Preferisco farlo tramite la riga di comando.

Inoltre, penso che valga la pena farlo anche contro l’ultima versione di WordPress. Se non hai una copia della copia trunk di Subversion di WordPress, puoi leggere come configurarla qui; tuttavia, questo è puramente facoltativo. Puoi seguire il resto di questo tutorial perfettamente con qualsiasi versione di WordPress che desideri.

Fare così,

1. Assicurati di essere nella directory dei plugin della tua installazione di WordPress
2. E quindi inserisci i seguenti comandi in una copia del tuo terminale

$ 

Questo creerà una  directory WordPress-Widget-Boilerplate nella directory  dei plugin. Puoi accedervi digitando semplicemente:

$ cd WordPress-Widget-Boilerplate

I risultati della clonazione del repository dovrebbero assomigliare a questo:

Successivamente, devi assicurarti di passare al  ramo di sviluppo che ho creato. È davvero facile farlo. Ma prima di farlo, perché non impostare il progetto in Visual Studio?

Configurazione del codice di Visual Studio

I passaggi per impostare il progetto in Visual Studio Code sono semplici:

1. Trascina la directory per il Boilerplate nell’IDE,
2. Aprire il terminale integrato,
3. Scambia rami

Proprio come ho fatto sopra, fornirò uno screencast su come fare tutto questo. Il trascinamento di una directory in Visual Studio Code dovrebbe essere abbastanza semplice, ma lo scambio di rami sulla riga di comando può essere leggermente diverso.

Innanzitutto, configurando il progetto in Visual Studio Code:

Nota qui che apro anche il terminale integrato premendo il collegamento CMD + P (sono su macOS, quindi il collegamento potrebbe essere diverso). Quindi inserisco il comando per controllare il ramo di sviluppo .

Dopo averlo fatto, il tuo repository locale dovrebbe passare al ramo di sviluppo. Puoi confermare che è la filiale di cui stai lavorando digitando:

$ git branch

E poi rivedere il contenuto del terminale. A rigor di termini, lo sviluppo dovrebbe essere evidenziato.

A questo punto introdurremo alcuni nuovi file nel progetto. Alla fine di questo tutorial, puoi formare un pull per ottenere tutto ciò che sto per documentare qui. Ma poiché lo scopo di ciò che stiamo facendo è duplice, è importante assicurarsi di farlo nella sequenza corretta perché il primo passaggio è qualcosa che uso in ogni singolo progetto per WordPress a questo punto.

Quindi, detto questo, diamo un’occhiata.

Compositore e qualità del codice

La prima cosa che mi piace fare è impostare una serie di strumenti per rafforzare la qualità del codice. Ciò è possibile grazie a una varietà di pacchetti Composer. Questi includono:

• GrumPHP. Uno strumento di qualità del codice PHP. Non sottovalutare il chiarimento e il grado in cui questo repository è pieno di informazioni. Se rimani bloccato con uno qualsiasi degli altri strumenti qui menzionati, consulta prima la documentazione in questo repository.
• Riparatore PHP CS. Uno strumento per risolvere automaticamente i problemi relativi agli standard di codifica PHP.
• PHP Parallel Lint. Questo strumento controlla la sintassi dei file PHP più velocemente del controllo seriale con un output più elaborato.
• PHPMD. Questa utility prende una data base di codice sorgente PHP e cerca diversi potenziali problemi all’interno di quella sorgente
• Analizzatore PHP. Un parser è utile per l’analisi statica, la manipolazione del codice e, sostanzialmente, qualsiasi altra applicazione che si occupa di codice a livello di codice.
• Gestore proxy. Questa libreria mira a fornire un’astrazione per la generazione di vari tipi di classi proxy.

Voglio essere chiaro su due cose:

1. Gli strumenti di cui sopra sono il minimo indispensabile che utilizzo e probabilmente mi vedrai utilizzare strumenti aggiuntivi in ​​futuro,
2. gli strumenti di cui sopra aiuteranno a far rispettare le regole di qualità del codice prima di archiviare il codice in un repository. Ha lo scopo di completare l’impostazione nel tuo IDE.

Per configurare e far funzionare questi strumenti all’interno del progetto, dovremo creare un  file composer.json che assomigli a questo :

{
    "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"
  }

Ricorda, puoi tirarlo giù manualmente alla fine di questo post. Se, tuttavia, desideri continuare, sentiti libero di farlo manualmente. Non vorrei mai scoraggiarti da questo. 🙂

Dopo aver creato il  file composer.json, assicurati di eseguire il seguente comando dal terminale:

$ composer install

Questo potrebbe richiedere del tempo; tuttavia, una volta terminato, dovresti essere presentato con il seguente messaggio:

Attento! GrumPHP sta annusando i tuoi impegni!

Per provarlo, inserisci il seguente comando nel tuo terminale:

$ vendor/bin/grumphp run

A seconda di come stai lavorando con il progetto, potresti vedere un output simile a questo:

Ma c’è più lavoro da fare. Vale a dire, dobbiamo:

• aggiorna il nostro  file .gitignore ,
• introdurre la configurazione per GrumPHP
• introdurre la configurazione per PHPMD,
• introdurre la configurazione per PHPCS,
• eventualmente, ristrutturare la struttura della directory di boilerplate.

Tutto fino al passaggio finale, mireremo a fare in questo post.

Aggiornamento del file Ignora

Innanzitutto, non vogliamo eseguire il commit della directory del fornitore o del file di blocco del compositore. Questi possono essere generati ogni volta che un utente scarica la directory. Possono facilmente perdere la sincronizzazione e aggiungere enormi dimensioni alla directory del progetto.

A tal fine, il tuo file gitignore dovrebbe assomigliare a questo :

*.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

Questo dice al plugin di ignorare qualsiasi cosa tranne ciò che è nella radice della directory del plugin (e alcune delle eventuali directory che creeremo) insieme ad alcuni file di base che siamo abituati a vedere nelle installazioni di WordPress.

Alcuni di ciò che vedi, come wp-config.php o wp-content/backups che probabilmente non vedrai mai nel contesto di un plugin, ma queste sono direttive standard di WordPress ignore che mi piace tenere a portata di mano.

Noterai che ho anche aggiunto  il fornitore  e il file di blocco del compositore nella parte inferiore del file.

Configura GrumPHP

GrumPHP può fare molto e se hai passato del tempo a esaminare il repository prima di leggere fino a qui, probabilmente lo saprai; tuttavia, lo manterrò il più snello possibile, quindi fornisce le istruzioni necessarie per gli strumenti che stiamo utilizzando e nient’altro.

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']

In breve, questo dice di eseguire una serie di controlli per:

• sicurezza,
• compositore,
• JSON,
• XML,
• Yaml,
• PHP,
• PHPCS,
• Analizzatore PHP,
• PHPMD,
• e altro ancora.

Una volta completata la configurazione di tutto il resto, sarò sicuro di mostrarti come tutto questo si adatta insieme. Ma prima, finiamo di configurare il resto delle nostre utilità.

PHPCS

Questo utilizza due file separati, un  file dist e un  file XML, ognuno dei quali ha scopi diversi, anche se molto utili.

Il primo file, php_cs.dist che vedrai nel repository alla fine di questo post, fornisce un’intestazione che viene applicata a tutti i file PHP nel nostro progetto. Inoltre, applica alcune regole diverse che migliorano la qualità del codice.

Le regole sono autoesplicative e puoi vedere cosa applicherà semplicemente esaminando ciascuna delle regole definite.

<?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'
      ])) ;

Successivamente, vorrai anche creare il file XML per completare il file sopra. Noterai che nel file che sto fornendo, questo è ciò che uso per il mio lavoro in Pressware. Inoltre, riconosce anche la  directory dei test.

A questo punto, non abbiamo alcun test unitario scritto, ma se scegli di introdurli nel tuo widget, questo sarà pronto per gestirli correttamente.

<?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>

C’è solo un piccolo set di configurazione che specifico qui, ma finora l’ho trovato più che sufficiente per le mie esigenze. Man mano che scopro di più o scelgo di usarne di più, aggiornerò sicuramente il contenuto nei post futuri.

Configura PHPMD

Infine, dobbiamo configurare PHP Mess Detector (o PHPMD). Fortunatamente, questo utilizza un file XML che utilizzerà i set di regole come definito nel pacchetto installato da Composer. Tutto quello che dobbiamo fare è fare riferimento alla regola nel file di configurazione.

In secondo luogo, forniremo anche una piccola esclusione per un  nome ShortVariable come vedrai nel seguente succo :

<?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>

E una volta che tutti questi sono a posto, dovremmo essere in grado di eseguire di nuovo GrumPHP, dalla riga di comando, e avere una serie di risultati leggermente diversa.

Esecuzione di GrumPHP di nuovo

Inserisci quanto segue nel tuo terminale:

$ vendor/bin/grumphp run

E dovresti vedere qualcosa del genere:

Risultati diversi rispetto alla prima volta, eh? Questo perché stiamo violando alcune regole e standard che sono una parte moderna di PHP e dello sviluppo orientato agli oggetti.

Ed è quello che andremo a ripulire nel prossimo post.

In arrivo

Quindi da dove viene la natura orientata agli oggetti di questo? Fino a questo punto, abbiamo parlato dell’utilizzo dell’API Widgets come modello orientato agli oggetti per la scrittura di codice orientato agli oggetti in WordPress.

Parte di ciò che abbiamo fatto finora è stato esattamente questo (parlando dei suoi principi, vedendo come è strutturato e altro).

Ma come ho detto all’inizio di questo post, la creazione di strumenti per la qualità del codice ci fornisce innanzitutto una base che possiamo utilizzare durante il refactoring del boilerplate (cosa che dobbiamo chiaramente fare data la quantità di rosso mostrata da GrumPHP).

Ed è qui che inizieremo nel prossimo post di questa serie.