Widgets de WordPress: comenzando con los estándares

El propósito de esta serie es comenzar a profundizar en el trabajo con la programación orientada a objetos en el contexto de WordPress.

Y dado que la API de widgets de WordPress es una de las API que utiliza prácticas orientadas a objetos, es un lugar lógico para comenzar. Además, nos brindará algunas técnicas fundamentales que podemos usar para aplicar en trabajos futuros a medida que veamos cómo crear más proyectos orientados a objetos en WordPress en series futuras.

Hasta ahora, hemos cubierto lo siguiente:

1. Widgets de WordPress: un enfoque orientado a objetos. La API de Widgets proporciona una sólida prueba de fuego y un ejemplo de cómo comenzar con la programación orientada a objetos en WordPress.
2. Widgets de WordPress: cómo detectar la programación orientada a objetos. El objetivo es armarlo con todo lo que necesita para detectar prácticas orientadas a objetos.

Si no estás al día, ahora es un buen momento para hacerlo. Y si es así, entonces recordará de la última publicación, terminamos con la siguiente nota:

Es decir, revisaremos el  modelo estándar de widgets de WordPress y lo refactorizaremos en su estado actual para adoptar estándares de PHP más modernos.

Para comenzar a actualizar WordPress Widget Boilerplate para seguir dichos estándares, debemos hacer algunas cosas:

1. crear una rama a partir del modelo existente,
2. instalar herramientas de calidad de código,
3. asegúrese de que nuestro IDE esté configurado correctamente,
4. y comenzar a refactorizar el código a dichos estándares.

Y eso es lo que vamos a empezar a hacer con este post.

Comenzando con los estándares

Si ha sido miembro de este sitio durante algún tiempo, entonces sabe que prefiero usar Visual Studio Code. Si no, tengo un conjunto completo de artículos dedicados a cómo lo uso (y, por lo tanto, cómo lo usaremos a lo largo de esta serie de publicaciones).

Y si está interesado en la cobertura sobre estándares de codificación, depuración, IDE, entornos de desarrollo, etc., consulte The Independent WordPress Developer.

Sin embargo, supongo que si está leyendo esto, entonces ha leído todo el material anterior o se siente cómodo leyendo todo el material anterior.

Dicho esto, comencemos.

Descargando el Repositorio

Lo primero que querrá hacer es clonar una copia del repositorio. Prefiero hacer esto a través de la línea de comandos.

Además, también creo que merece la pena hacerlo frente a la última versión de WordPress. Si no tiene una copia de la copia troncal de WordPress de Subversion, puede leer cómo configurarla aquí; sin embargo, esto es puramente opcional. Puede seguir el resto de este tutorial sin problemas con cualquier versión de WordPress que desee.

Para hacerlo,

1. Asegúrese de estar en el directorio de complementos de su instalación de WordPress
2. Y luego ingrese los siguientes comandos en una copia de su terminal

$ 

Esto creará un  directorio WordPress-Widget-Boilerplate en su  directorio de complementos. Puede navegar hasta él simplemente escribiendo:

$ cd WordPress-Widget-Boilerplate

Los resultados de la clonación del repositorio deberían verse así:

A continuación, debe asegurarse de cambiar a la  rama de desarrollo que he creado. Es muy fácil hacer esto. Pero antes de hacer eso, ¿por qué no configurar el proyecto en Visual Studio?

Configuración del código de Visual Studio

Los pasos para configurar el proyecto en Visual Studio Code son sencillos:

1. Arrastre el directorio de Boilerplate al IDE,
2. Abra el terminal integrado,
3. Intercambiar sucursales

Tal como lo hice anteriormente, proporcionaré un screencast sobre cómo hacer todo esto. Arrastrar un directorio a Visual Studio Code debería ser bastante fácil, pero intercambiar ramas en la línea de comando puede ser un poco diferente.

Primero, configurando el proyecto en Visual Studio Code:

Observe aquí que también abro el terminal integrado presionando el acceso directo CMD+P (estoy en macOS, por lo que su acceso directo puede ser diferente). Luego ingreso el comando para verificar la rama de desarrollo .

Una vez que haga esto, su repositorio local debería cambiar a la rama de desarrollo. Puede confirmar que esa es la rama en la que está trabajando escribiendo:

$ git branch

Y luego revisa el contenido de la terminal. En rigor, debe destacarse el desarrollo .

En este punto, vamos a introducir algunos archivos nuevos en el proyecto. Al final de este tutorial, puede formar un pull para obtener todo lo que voy a documentar aquí. Pero debido a que el propósito de lo que estamos haciendo es doble, es importante asegurarse de que lo estamos haciendo en la secuencia adecuada porque el primer paso es algo que uso en cada proyecto para WordPress en este momento.

Entonces, dicho esto, echemos un vistazo.

Compositor y calidad del código

Lo primero que me gusta hacer es configurar una serie de herramientas para reforzar la calidad del código. Esto se logra mediante una variedad de paquetes de Composer. Éstos incluyen:

• GrumPHP. Una herramienta de calidad de código PHP. No subestime la claridad y el grado en que este repositorio está lleno de información. Si alguna vez se queda atascado con alguna de las otras herramientas mencionadas aquí, consulte primero la documentación de este repositorio.
• Reparador PHP CS. Una herramienta para corregir automáticamente problemas de estándares de codificación de PHP.
• Pelusa paralela de PHP. Esta herramienta verifica la sintaxis de los archivos PHP más rápido que la verificación en serie con una salida más elegante.
• PHPMD. Esta utilidad toma una base de código fuente PHP dada y busca varios problemas potenciales dentro de esa fuente
• Analizador de PHP. Un analizador es útil para el análisis estático, la manipulación de código y, básicamente, cualquier otra aplicación que trate con código mediante programación.
• Administrador de proxy. Esta biblioteca tiene como objetivo proporcionar una abstracción para generar varios tipos de clases de proxy.

Quiero tener dos cosas claras:

1. Las herramientas anteriores son lo mínimo que uso, y es probable que me vea usar herramientas adicionales en el futuro,
2. las herramientas anteriores ayudarán a hacer cumplir las reglas de calidad del código antes de registrar el código en un repositorio. Está destinado a complementar la configuración en su IDE.

Para configurar y ejecutar estas herramientas dentro del proyecto, necesitaremos crear un archivo composer.json que se vea así :

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

Recuerde, puede bajar esto manualmente al final de esta publicación. Sin embargo, si desea seguir adelante, siéntase libre de hacerlo manualmente. Nunca quisiera desanimarte de eso. 🙂

Una vez que haya creado el  archivo composer.json, querrá asegurarse de ejecutar el siguiente comando desde la terminal:

$ composer install

Esto puede tomar algo de tiempo; sin embargo, una vez hecho esto, debería aparecer el siguiente mensaje:

¡Cuidado! ¡GrumPHP está olfateando tus confirmaciones!

Para darle una prueba, ingrese el siguiente comando en su terminal:

$ vendor/bin/grumphp run

Dependiendo de cómo esté trabajando con el proyecto, es posible que vea un resultado similar a este:

Pero hay más trabajo por hacer. Es decir, necesitamos:

• actualizar nuestro  archivo .gitignore ,
• introducir la configuración para GrumPHP
• introducir la configuración para PHPMD,
• introducir la configuración para PHPCS,
• eventualmente, reestructurar la estructura de directorios del repetitivo.

Todo hasta el paso final, vamos a tratar de hacerlo en esta publicación.

Actualización del archivo Ignorar

Primero, no queremos comprometer el directorio del proveedor o el archivo de bloqueo del compositor. Estos se pueden generar cada vez que un usuario descarga el directorio. Pueden desincronizarse fácilmente y agregan un tamaño enorme al directorio del proyecto.

Con ese fin, su archivo gitignore debería verse así :

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

Esto le dice al complemento que ignore cualquier cosa excepto lo que está en la raíz del directorio del complemento (y algunos de los directorios eventuales que crearemos) junto con algunos archivos básicos que estamos acostumbrados a ver en las instalaciones de WordPress.

Es probable que nunca veas algo de lo que ves, como wp-config.php o wp-content/backups, en el contexto de un complemento, pero estas son directivas estándar de WordPress para ignorar que me gusta tener a mano.

Notará que también agregué  el proveedor  y el archivo de bloqueo del compositor al final del archivo.

Configurar GrumPHP

GrumPHP puede hacer mucho, y si pasó tiempo examinando el repositorio antes de leer hasta aquí, entonces probablemente lo sepa; sin embargo, lo mantendré lo más simple posible, para que proporcione las instrucciones que necesita para las herramientas que estamos usando y nada más.

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 resumen, esto dice que ejecute una variedad de controles para:

• seguridad,
• compositor,
• JSON,
• xml,
• Yaml,
• PHP,
• PHPCS,
• analizador PHP,
• PHPMD,
• y más.

Una vez que hayamos terminado de configurar todo lo demás, me aseguraré de mostrarte cómo encaja todo esto. Pero antes, terminemos de configurar el resto de nuestras utilidades.

PHPCS

Esto utiliza dos archivos separados, un  archivo dist y un  archivo XML, cada uno de los cuales tiene propósitos diferentes, aunque muy útiles.

El primer archivo, php_cs.dist, que verá en el repositorio al final de esta publicación, proporciona un encabezado que se aplica a todos los archivos PHP de nuestro proyecto. También aplica algunas reglas diferentes que mejoran la calidad del código.

Las reglas se explican por sí mismas, y puede ver lo que se aplicará simplemente mirando cada una de las reglas definidas.

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

A continuación, también querrá crear el archivo XML para complementar el archivo anterior. Notará que en el archivo que estoy proporcionando, esto es lo que uso para mi trabajo en Pressware. Además, también reconoce el  directorio de pruebas.

En este punto, no tenemos pruebas unitarias escritas, pero si opta por introducirlas en su widget, estará listo para manejarlas correctamente.

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

Solo hay un pequeño conjunto de configuración que especifico aquí, pero hasta ahora he encontrado que es más que suficiente para mis necesidades. A medida que descubra más u opte por usar más, ciertamente actualizaré el contenido en publicaciones futuras.

Configurar PHPMD

Y finalmente, necesitamos configurar PHP Mess Detector (o PHPMD). Afortunadamente, esto usa un archivo XML que usará conjuntos de reglas como se define en el paquete instalado por Composer. Todo lo que tenemos que hacer es hacer referencia a la regla en el archivo de configuración.

En segundo lugar, también proporcionaremos una pequeña exclusión para un  nombre ShortVariable como verá en la siguiente esencia :

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

Y una vez que todo esto esté en su lugar, deberíamos poder ejecutar GrumPHP nuevamente, desde la línea de comandos, y tener un conjunto de resultados ligeramente diferente.

Ejecutando GrumPHP de nuevo

Introduce lo siguiente en tu terminal:

$ vendor/bin/grumphp run

Y deberías ver algo como esto:

Resultados diferentes a la primera vez, ¿eh? Esto se debe a que estamos violando algunas reglas y estándares que son una parte moderna de PHP y del desarrollo orientado a objetos.

Y eso es lo que vamos a aclarar en el próximo post.

Subiendo

Entonces, ¿de dónde viene la naturaleza orientada a objetos de esto? Hasta este punto, hemos estado hablando sobre el uso de la API de Widgets como un modelo orientado a objetos para escribir código orientado a objetos en WordPress.

Algo de lo que hemos hecho hasta ahora ha sido exactamente eso (hablando sobre sus principios, viendo cómo se presenta y más).

Pero como mencioné al comienzo de esta publicación, colocar herramientas de calidad de código primero nos brinda una base que podemos usar a medida que refactorizamos el modelo (lo que claramente debemos hacer dada la cantidad de rojo que muestra GrumPHP).

Y ahí es donde comenzaremos en la próxima publicación de esta serie.