Инструменты для написания лучшего кода WordPress: Composer

Хотя я думаю, что название этой серии и статьи для каждой из них достаточно ясны, есть и другие вещи, которые я стремлюсь сделать с этой серией, в отличие от других серий, которые я написал до этого момента.

В частности, две вещи, которые я пытаюсь сделать, это два:

1. каждая статья должна быть относительно краткой (по сравнению с предыдущими статьями);
2. сосредоточьтесь на чем-то одном и дайте краткое описание.

Поскольку это контент для участников, я не возражаю против того, чтобы он был немного длиннее, чем обычно, но я также не хочу, чтобы он был настолько длинным, чтобы за ним было трудно следить. Я бы предпочел, чтобы это было короткое чтение с чем-то практическим, что вы можете реализовать после прочтения каждого поста.

И одна из вещей, которая очень помогает в написании лучшего кода WordPress, — это Composer.

Лучший код WordPress с Composer

Если вы читали этот блог какое-то время, то знаете, что я фанат Composer (однако я далеко не единственный человек, работающий с WordPress).

И хотя я написал об этом кое-какой материал, я не написал ничего с конкретной целью, чтобы вы начали работать с ним к концу прочтения одной короткой статьи.

К этому моменту нам придется пойти на некоторые компромиссы: а именно, я предоставлю пример файла конфигурации вместе со способом организации каталога вашего плагина. Затем, в следующем посте, я объясню некоторые возможности Composer.

Что такое Композитор?

Во-первых, важно понять, что такое Composer. И легко прочитать определение, как указано на сайте, не так ли? Это менеджер зависимостей для PHP.

Но во-первых, что такое зависимость?

Однако у некоторых это вызывает ряд вопросов:

• Что такое зависимость?
• Зачем мне ими управлять?

И если вы копнете немного глубже, вы можете обнаружить, что это менеджер пакетов, и это просто вызывает те же вопросы, за исключением того, что вы просто заменяете «зависимость» на «пакет», и вы возвращаетесь к тому, с чего начали.

Поэтому я сделаю все, что в моих силах, чтобы сделать это как можно более ясным:

Зависимость или пакет, часть программного обеспечения, которое использует ваш код. Это может быть что-то, от чего зависит функциональность во время выполнения, например , способ выполнения HTTP-запросов, или это может быть библиотека для преобразования массивов в XML.

Composer упрощает включение этих конкретных пакетов в вашу библиотеку, позволяя вам:

• скачать и включить пакет в свой плагин,
• автоматически загружать ваш плагин во время выполнения,
• упростите для вашего плагина создание экземпляра или вызов плагина по мере необходимости.

Это означает, что нам не нужно засорять каталоги нашей кодовой базы большим количеством файлов, добавляемых вручную, и это означает, что мы не используем include или require повсюду.

У них будет свое место, о чем я расскажу в следующем посте, но их не нужно будет устанавливать автоматически. Вместо этого Composer будет управлять ими. Следовательно, менеджер зависимостей является частью его цели.

Теперь, когда вы его установили, у вас есть некоторый контекст.

Использование композитора

Написание этого конкретного раздела несколько сложно, потому что у всех нас разные потребности, верно? Но, по крайней мере, мы все можем воспользоваться автозагрузчиком.

Это то, что мы все можем использовать.

Итак, вот что я сделаю:

1. Я настрою базовый каталог плагинов,
2. Создайте необходимые файлы для запуска плагина,
3. Настройте простой файл Composer,
4. Выполнить это

А потом я покажу вам результаты. Мы можем получить доступ к сторонним библиотекам или другим функциям в будущем посте (или, на самом деле, в будущих сериях).

Но, по крайней мере, это покажет вам, как использовать Composer для определения автозагрузчика, чтобы вы могли сосредоточиться на написании кода, а не на размышлениях о том, включены ли классы.

Каталог плагинов

Обычно я структурирую свои плагины следующим образом:

• есть загрузочный файл, читаемый WordPress,
• есть  каталог src, в котором хранятся все каталоги и файлы PHP,
• существует  каталог ресурсов верхнего уровня, в котором хранятся изображения, файлы JavaScript и файлы Sass,
• и есть  папка поставщика, созданная Composer для размещения зависимостей и автозагрузчика.

Иногда могут быть какие-то другие странные папки, такие как папка inc или lib, но на данном этапе в той работе, которую я делаю, это очень необычно. И из-за этого я не буду беспокоиться об этом для этого поста.

Вместо этого мой каталог выглядит примерно так.

Каталог поставщика отсутствует, потому что я еще не создал файл Composer, который используется для выполнения. Но мы увидим это до конца поста.

Примеры файлов

Давайте настроим образец файла в плагине. И когда я говорю образец, я также имею в виду простоту.

Этот файл будет иметь единственную цель: вывести сообщение на панель инструментов при входе в WordPress.

Помните, однако, что цель этого не в том, чтобы показать, как написать плагин с хорошей архитектурой. Вместо этого он показывает, как сгенерировать автозагрузчик, чтобы файлы плагина генерировались автоматически.

Таким образом, начальная загрузка плагина выглядит так :

<?php
/**
 * The plugin bootstrap file
 *
 * This file is read by WordPress to generate the plugin information in the plugin
 * admin area. This file also includes all of the dependencies used by the plugin,
 * registers the activation and deactivation functions, and defines a function
 * that starts the plugin.
 *
 * @since             0.1.0
 * @package           SamplePlugin
 *
 * @wordpress-plugin
 * Plugin Name:       Sample Plugin
 * Description:       A sample plugin used for a blog post.
 * Version:           0.1.0
 * Author:            Tom McFarlin
 * Author URI:        https://tommcfarlin.com
 * License:           GPL-3.0+
 * License URI:       http://www.gnu.org/licenses/gpl-3.0.txt
 */

namespace SamplePlugin;

use SamplePluginMessenger;

// This file called directly.
defined('WPINC') || die;

// Include the autoloader.
require_once __DIR__. '/vendor/autoload.php';

// Start the machine.
(new Messenger())->start();

И файл, непосредственно отвечающий за отображение сообщения, выглядит так :

<?php

namespace SamplePlugin;

class Messenger
{
    /**
     * Subscribers the `adminNotices` function to the admin_notices hook in WordPress.
     */
    public function start()
    {
        add_action('admin_notices', [$this, 'adminNotices']);
    }

    /**
     * Displays the contents of the `message.html` file into the adminitrative notices
     * area on the dashboard whenever the plugin is active.
     */
    public function adminNotices()
    {
        if ('dashboard' !== get_current_screen()->id) {
            return;
        }

        include_once dirname(__FILE__). '/Admin/Views/message.html';
    }
}

И если вам интересно узнать о файле HTML, он тоже прост :

<div class="notice notice-success is-dismissible">
    <p>This is a message from the <strong>Sample Plugin</strong></p>
</div>

Я говорил тебе, что это просто.

Файл конфигурации Composer

Этот конкретный файл может быть как простым, так и сложным по мере необходимости. Для этого поста мы придерживаемся простоты. Цель этого поста — просто дать ему имя, описание, лицензию, авторов, а затем настроить автозагрузчик.

Взгляните сюда, а затем я объясню, что вы видите чуть ниже:

{
    "name": "tommcfarlin/sample-plugin",
    "description": "A sample plugin used for a blog post.",
    "type": "wordpress-plugin",
    "license": "GPL-3.0-or-later",
    "authors": [
      {
        "name": "Tom McFarlin",
        "email": "tom@tommcfarlin.com",
        "homepage": "https://tommcfarlin.com"
      }
    ],
      "autoload": {
        "psr-4": {
          "SamplePlugin": "src/"
        }
      }
  }

Во-первых, имя, описание, тип и лицензия должны быть достаточно простыми для понимания. Область автора также прямолинейна.

Автозагрузка — это область, о которой мы сейчас беспокоимся. Это должно быть довольно ясно.

Короче говоря, у нас есть директива для PSR4, о  которой вы можете прочитать подробнее, а также о том, где находится пространство имен. Итак, в приведенном выше примере все в пространстве имен SamplePlugin находится в src. 

Это то, что сообщает автозагрузчику, где искать определенные файлы. И в нашем случае он просто будет искать класс Messenger .

Бегущий композитор

Теперь, когда мы рассмотрели самые основы файла конфигурации Composer, пришло время его запустить. Напомним, что каталог вашего плагина должен выглядеть примерно так:

В терминале введите следующую команду :

И вы должны увидеть что-то вроде этого:

Предполагая, что все прошло хорошо, вы сможете войти в WordPress и активировать плагин.

Видеть все это вместе

После активации плагина вы можете перейти к панели управления вашего сайта. Там вы должны увидеть удаляемое уведомление, которое выглядит точно так же, как мы видели в начале поста:

Если вы зашли так далеко, то вам пора! В противном случае дважды проверьте свой синтаксис, чтобы убедиться, что все в порядке. Если что-то не так, скорее всего, вы не смогли бы зайти так далеко, и если у вас установлены базовые константы отладки, вы, вероятно, увидите, где существует проблема.

Это не все

В Composer есть гораздо больше, и я настоятельно рекомендую прочитать документацию по нему. Кое-что из этого я расскажу при рассмотрении инструментов, которые я планирую рассмотреть позже в этой серии, но сейчас я рекомендую ознакомиться с некоторыми соглашениями.

Ой! И я не рекомендую проверять каталог поставщика в вашем репозитории. Позже это может превратиться в огромный каталог и подорвать всю цель Composer.

В следующем посте расскажу почему. Некоторые люди делают это, и это нормально, и я делал это раньше, но важно быть благоразумным в том, когда вы делаете.

Ошибаетесь в том, что не делаете этого. И я объясню почему в следующем посте.