WordPress-widgets: Börjar med standarder

Syftet med den här serien är att börja göra en djupare dykning i arbetet med objektorienterad programmering i WordPress-sammanhang.

Och eftersom WordPress Widgets API är en av API:erna som använder objektorienterade metoder, är det ett logiskt ställe att börja. Vidare kommer det att ge oss några grundläggande tekniker som vi kan använda för att tillämpa på framtida arbete när vi ser hur man bygger mer objektorienterade projekt på WordPress i framtida serier.

Hittills har vi täckt följande:

1. WordPress-widgets: ett objektorienterat tillvägagångssätt. Widgets API ger ett gediget lackmustest och exempel på hur man kommer igång med objektorienterad programmering i WordPress.
2. WordPress-widgets: Hur man upptäcker objektorienterad programmering. Målet är att beväpna dig med allt du behöver för att upptäcka objektorienterade metoder.

Om du inte är ikapp är det nu ett bra tillfälle att göra det. Och om du har, kommer du att minnas från det förra inlägget, vi avslutade med följande anteckning:

Det vill säga, vi kommer att återbesöka WordPress Widget Boilerplate och jag kommer att omstrukturera den i dess nuvarande tillstånd för att anta mer moderna PHP-standarder.

För att börja uppdatera WordPress Widget Boilerplate för att följa nämnda standarder måste vi göra några saker:

1. skapa en gren från den befintliga pannplattan,
2. installera verktyg för kodkvalitet,
3. se till att vår IDE är korrekt inställd,
4. och börja omfaktorisera koden till nämnda standarder.

Och det är vad vi ska börja göra med det här inlägget.

Börjar med standarder

Om du har varit medlem på den här webbplatsen ett tag, då vet du att jag föredrar att använda Visual Studio Code. Om inte, har jag en hel uppsättning artiklar som ägnas åt hur jag använder det (och därmed hur vi kommer att använda det i den här serien av inlägg).

Och om du är intresserad av täckning angående kodningsstandarder, felsökning, IDE, utvecklingsmiljöer och så vidare, kolla in The Independent WordPress Developer.

Jag antar dock att om du läser detta så har du läst igenom materialet ovan eller så är du bekväm med att gå igenom allt material ovan.

Med det sagt, låt oss börja.

Laddar ned arkivet

Det första du kommer att vilja göra är att klona en kopia av förvaret. Jag föredrar att göra detta via kommandoraden.

Dessutom tycker jag också att det är värt att göra det mot den senaste versionen av WordPress. Om du inte har en kopia av Subversions trunkkopia av WordPress kan du läsa hur du ställer in det här; detta är dock helt valfritt. Du kan följa med resten av denna handledning alldeles utmärkt med vilken version av WordPress du vill.

Att göra så,

1. Se till att du är i plugins- katalogen för din WordPress-installation
2. Och skriv sedan in följande kommandon i en kopia av din terminal

$ 

Detta kommer att skapa en WordPress-Widget-Boilerplate- katalog i din plugin – katalog. Du kan navigera till det genom att enkelt skriva:

$ cd WordPress-Widget-Boilerplate

Resultaten av att klona förvaret bör se ut ungefär så här:

Därefter måste du se till att du byter till utvecklingsgrenen som jag har skapat. Det är verkligen lätt att göra det här. Men innan vi gör det, varför inte sätta upp projektet i Visual Studio?

Konfigurera Visual Studio Code

Stegen för att ställa in projektet i Visual Studio Code är enkla:

1. Dra katalogen för Boilerplate till IDE,
2. Öppna den integrerade terminalen,
3. Byt grenar

Precis som jag har gjort ovan kommer jag att ge en screencast om hur man gör allt detta. Att dra en katalog till Visual Studio Code borde vara lätt nog, men att byta grenar på kommandoraden kan vara lite annorlunda.

Ställ först in projektet i Visual Studio Code:

Lägg märke till att jag också öppnar den integrerade terminalen genom att trycka på CMD+P-genvägen (jag använder macOS så din genväg kan vara annorlunda). Sedan skriver jag in kommandot för att kolla in utveckla grenen.

När du har gjort detta bör ditt lokala arkiv byta över till utvecklingsgrenen. Du kan bekräfta att det är grenen som du arbetar med genom att skriva:

$ git branch

Och granska sedan innehållet i terminalen. Strängt taget bör utveckla lyftas fram.

Vid det här laget kommer vi att introducera några nya filer i projektet. I slutet av den här handledningen kan du skapa en dragning för att få allt som jag ska dokumentera här. Men eftersom syftet med det vi gör är dubbelt så är det viktigt att se till att vi gör detta i rätt ordning eftersom det första steget är något som jag använder i varje enskilt projekt för WordPress vid det här laget.

Så med det sagt, låt ta en titt.

Kompositör och kodkvalitet

Det första jag gillar att göra är att ställa in en serie verktyg för att framtvinga kodkvalitet. Detta uppnås med en mängd olika Composer-paket. Dessa inkluderar:

• GrumPHP. Ett verktyg för PHP-kodkvalitet. Underskatta inte förtydligandet och i vilken grad detta förråd är fullt av information. Om du någonsin fastnar med något av de andra verktygen som nämns här, titta igenom dokumentationen i det här arkivet först.
• PHP CS Fixer. Ett verktyg för att automatiskt fixa problem med PHP-kodningsstandarder.
• PHP Parallell Lint. Det här verktyget kontrollerar syntaxen för PHP-filer snabbare än seriell kontroll med en snyggare utdata.
• PHPMD. Det här verktyget tar en given PHP-källkodsbas och letar efter flera potentiella problem inom den källan
• PHP Parser. En parser är användbar för statisk analys, manipulation av kod och i princip alla andra applikationer som hanterar kod programmatiskt.
• Proxy Manager. Detta bibliotek syftar till att tillhandahålla en abstraktion för att generera olika typer av proxyklasser.

Jag vill vara tydlig med två saker:

1. Ovanstående verktyg är det absoluta minimum som jag använder, och du kommer sannolikt att se mig använda ytterligare verktyg i framtiden,
2. verktygen ovan hjälper till att upprätthålla regler för kodkvalitet innan du checkar in kod i ett arkiv. Det är tänkt att komplettera uppställningen i din IDE.

För att få dessa verktyg konfigurerade och körda inom projektet måste vi skapa en composer.json -fil som ser ut så här :

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

Kom ihåg att du kan dra ner detta manuellt i slutet av det här inlägget. Om du däremot vill följa med kan du göra detta manuellt. Jag skulle aldrig vilja avskräcka dig från det. 🙂

När du har skapat  filen composer.json vill du se till att du kör följande kommando från terminalen:

$ composer install

Detta kan ta lite tid; men när det är gjort bör du få följande meddelande:

Se upp! GrumPHP sniffar dina åtaganden!

För att ge det en torrkörning, skriv in följande kommando i din terminal:

$ vendor/bin/grumphp run

Beroende på hur du arbetar med projektet kan du se utdata som ser ut ungefär så här:

Men det finns mer att göra. Vi behöver nämligen:

• uppdatera vår .gitignore -fil,
• introducera konfiguration för GrumPHP
• introducera konfiguration för PHPMD,
• introducera konfiguration för PHPCS,
• så småningom, strukturera om boilerplates katalogstruktur.

Allt fram till det sista steget kommer vi att sikta på att göra i det här inlägget.

Uppdaterar Ignorera-filen

För det första vill vi inte commitera leverantörskatalogen eller kompositörens låsfil. Dessa kan genereras när en användare laddar ner katalogen. De kan lätt falla ur synk och de lägger till enorm storlek till projektets katalog.

För det ändamålet bör din gitignore -fil se ut så här :

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

Detta säger åt plugin-programmet att ignorera allt utom det som finns i roten av plugin-katalogen (och några av de eventuella katalogerna vi kommer att skapa) tillsammans med några grundläggande filer som vi är vana vid att se i WordPress-installationer.

En del av det du ser, som wp-config.php eller wp-content/backups, kommer du aldrig att se i samband med ett plugin, men det här är standarddirektiv för WordPress som jag vill ha till hands.

Du kommer att märka att jag också har lagt till leverantörs-  och kompositörlåsfilen längst ned i filen.

Konfigurera GrumPHP

GrumPHP kan göra mycket, och om du ägnade tid åt att granska förvaret innan du läste så här långt, så vet du förmodligen det; Jag kommer dock att hålla den så smal som möjligt, så den ger instruktionerna den behöver för de verktyg vi använder och inget mer.

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

Kort sagt, detta säger att köra en mängd olika kontroller för:

• säkerhet,
• kompositör,
• JSON,
• XML,
• Yaml,
• PHP,
• PHPCS,
• PHP Parser,
• PHPMD,
• och mer.

När vi har slutfört konfigureringen av allt annat kommer jag att se till att visa dig hur allt detta hänger ihop. Men först, låt oss slutföra konfigureringen av resten av våra verktyg.

PHPCS

Detta använder två separata filer – en dist -fil och en XML -fil – som var och en har olika, men mycket användbara syften.

Den första filen, php_cs.dist som du kommer att se i förvaret i slutet av detta inlägg, tillhandahåller en rubrik som tillämpas på alla PHP-filer i vårt projekt. Det upprätthåller också några olika regler som förbättrar kodens kvalitet.

Reglerna är självförklarande och du kan se vad de kommer att tillämpa genom att bara titta igenom var och en av reglerna som definieras.

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

Därefter vill du också skapa XML-filen för att komplettera filen ovan. Du kommer att notera att i filen jag tillhandahåller är detta vad jag använder för mitt arbete på Pressware. Dessutom bekräftar den också testkatalogen.

För närvarande har vi inga enhetstester skrivna, men skulle du välja att introducera dem i din widget kommer detta att vara redo att hantera dem på rätt sätt.

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

Det finns bara en liten uppsättning konfigurationer som jag anger här, men jag har tyckt att den är mer än tillräcklig för mina behov hittills. När jag upptäcker mer eller väljer att använda mer, kommer jag definitivt att uppdatera innehållet i framtida inlägg.

Konfigurera PHPMD

Och slutligen måste vi konfigurera PHP Mess Detector (eller PHPMD). Lyckligtvis använder detta en XML-fil som kommer att använda regeluppsättningar som definieras i paketet installerat av Composer. Allt vi behöver göra är att referera till regeln i konfigurationsfilen.

För det andra kommer vi också att tillhandahålla en liten uteslutning för ett ShortVariable- namn som du ser i följande sammanfattning :

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

Och när alla dessa är på plats borde vi kunna köra GrumPHP igen, från kommandoraden, och ha en något annorlunda uppsättning resultat.

Kör GrumPHP igen

Ange följande i din terminal:

$ vendor/bin/grumphp run

Och du borde se något sånt här:

Annat resultat än första gången, va? Detta beror på att vi bryter mot vissa regler och standarder som är en modern del av PHP och objektorienterad utveckling.

Och det är vad vi ska städa upp i nästa inlägg.

Kommer upp

Så var kommer den objektorienterade naturen av detta ifrån? Fram till denna punkt har vi pratat om att använda Widgets API som en objektorienterad modell för att skriva objektorienterad kod i WordPress.

En del av det vi har gjort hittills har varit exakt det (genom att prata igenom dess principer, se hur det är upplagt och mer).

Men som jag nämnde i början av det här inlägget, ger läggande av kodkvalitetsverktyg oss först en grund som vi kan använda när vi refaktorerar boilerplate (vilket vi helt klart måste göra med tanke på mängden rött som visas av GrumPHP).

Och det är där vi börjar i nästa inlägg i den här serien.