Как составить плагин

В основе любого плагина лежит PHP код, логика его работы и правильное использование API WordPress. Задачей любого плагина должно быть создание нового функционала с минимально возможной нагрузкой, совместимость с ядром WordPress и грамотная работа кода в условиях постоянно-обновляющейся системы.

Создание плагина

Чтобы создать плагин WordPress нужно:

1. Создать папку плагина. В ней будут лежать файлы нашего плагина. Создается она в папке всех плагинов WordPress. Например, создаем папку /wp-content/plugins/my-plugin-name.

2. Создать главный файл плагина. Рекомендуется чтобы название этого файла совпадало с названием папки плагина. Например, my-plugin-name.php → /wp-content/plugins/my-plugin-name/my-plugin-name.php.

3. Создать описание плагина – заголовки плагина. Они нужны чтобы wordpress распознал плагин как плагин, иначе он просто не будет работать. В самое начало главного файла плагина, нужно добавить php комментарий, где указать имя плагина:

   <?php
   
   /*
    * Plugin Name: Мой первый плагин
    */

Готово! Теперь наш плагин можно увидеть в разделе Плагины в админ-панели.

Дополнительные данные в заголовке

Чтобы плагин начал работать достаточно указать только Plugin Name (название плагина). Но можно также указать другие параметры плагина – это улучшит отображение плагина в консоли WordPress.

Build In Post

<?php

/**
 * Plugin Name: Название плагина
 * Description: Описание плагина желательно не очень длинное (140 символов)
 * Plugin URI:  Ссылка на страницу плагина
 * Author URI:  Ссылка на автора
 * Author:      Имя автора
 * Version:     Версия плагина, например 1.0
 *
 * Text Domain: ID перевода, указывается в load_plugin_textdomain()
 * Domain Path: Путь до файла перевода.
 * Requires at least: 2.5
 * Requires PHP: 5.4
 *
 * License:     GPL2
 * License URI: https://www.gnu.org/licenses/gpl-2.0.html
 *
 * Network:     Укажите "true" для возможности активировать плагин для сети Multisite.
 * Update URI: https://example.com/link_to_update
 */

// код плагина

Plugin Name:(обязательный)

Название плагина, которое отображается в списке плагинов в админке.

Description:

Краткое описание плагина, которое отображается в разделе Плагины в в админке. Рекомендуется не превышать 140 символов.

Version:

Номер текущей версии плагина, например, 1.0 или 1.0.3.

При установке версии имейте ввиду, что WP для сравнения версий использует функцию version_compare(). Поэтому при изменении версии убедитесь что новая версия будет выше. Например, 1.02 больше чем 1.1

Plugin URI:

Домашняя страница плагина, которая может быть на WordPress.org или на вашем собственном сайте.

Author:

Имя автора плагина. В списке может быть более одного автора.

Author URI:

Сайт автора или профиль на другом веб-сайте, например, WordPress.org.

Requires at least:

Самая низкая версия WordPress, на которой будет работать плагин. Например: 2.5.

Requires PHP:

Минимальная требуемая версия PHP. Например: 5.4.

License:

Короткое имя лицензии плагина, например GPL2. Более подробную информацию о лицензировании можно найти на WordPress.org.

License URI:

Ссылка на лицензию, например, https://www.gnu.org/licenses/gpl-2.0.html .

Text Domain:

Идентификатор перевода (домен локализации) используется в функциях локализации и в названии файла перевод mo. Подобрее смотрите цитату здесь.

Domain Path:

Нужен если файл перевода находится не в той же папке, в которой находится текущий файл. Например, .mo файл находится в папке /myplugin/languages, а файл плагина в /myplugin/myplugin.php, тогда тут указываем /languages.

Network:

Укажите “true” чтобы плагин обязательно активировался по всей сети сайтов в MU сборке WordPress. Это сделает невозможным активировать плагин для одного сайта, если активирована мультисеть.

Update URI:

URL для обновления сайта. Используется в функции wp_update_plugins(). Из домена будет создан хук update_plugins_(hostname).

Шаблон для создания плагина WordPress

Чтобы не создавать файлы и структуру с нуля, можно использовать шаблон для создания плагина:

• WordPress Plugin Boilerplate – генератор шаблона, где указывается название плагина, которое будет использовано в названиях папок, классов и функций – WordPress Plugin Boilerplate Generator.

Шаблон представляет собой стандартную и организованную объектно-ориентированную основу.

Шаблон придерживаются стандартов PHP кода для WordPress.

Используя такой подход, можно быть уверенным в более четкой и понятной структуре плагина. Так можно сгенерировать основу и затем просто удалить все ненужные файлы, оставив структуру папок – структура важна!

Хуки в плагине

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

Существует два типа хуков в WordPress:

• События (actions) — позволяют добавлять или изменять функционал WordPress.
• Фильтры (filters) — позволяют изменять данные.

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

Непосредственно к плагинам относятся три функции:

• register_activation_hook() – регистрирует функцию, которая будет срабатывать во время активации плагина.
  Используется для добавления настроек плагина и т.п.

• register_deactivation_hook() – регистрирует функцию, которая должна запускаться после деактивации плагина.
  Используется для удаления временных данных плагина.

• register_uninstall_hook() – регистрирует функцию, которая вызывается при удалении плагина.
  Используется при удалении плагин для удаления всех данных плагина: в настройках, в файлах, в базе данных и т.д.

Можно создавать свои собственные хуки в исходном коде плагина с помощью do_action() или apply_filters(). Они позволят пользователям вашего плагина расширить его возможности, точно также как WordPress позволяет вам расширять свои возможности.

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

PHP Функции и WordPress API

WordPress предоставляет ряд API. API могут значительно упростить написание кода. Т.е. не нужно изобретать колесо, когда оно уже есть.

Некоторые API WordPress:

• API настроек – упрощает создание и управление опциями плагина, которые сохраняются в базу данных.

• plugin_dir_url() — Получает URL папки (директории, каталога), где находится указанный файл плагина (со слэшем на конце).
• register_activation_hook() — Регистрирует функцию, которая будет срабатывать во время активации плагина.
• register_deactivation_hook() — Регистрирует функцию, которая будет запускаться после деактивации плагина.
• register_uninstall_hook() — Регистрирует функцию, которая вызывается при удалении плагина, чтобы почистить все следы прибывания плагина в системе.

• HTTP API – упрощает создание HTTP запросов в PHP. Отличная замена велосипедов на cURL.

Как WordPress загружает плагины

При активации плагина WordPress, записывает путь на его главный файл в опцию active_plugins. Далее при загрузке любой страницы (админки и фронта) WordPress просто подключает все файлы из опции active_plugins (пути на них там хранятся в виде массива). Смотрите как это выглядит:

$active_plugins = get_option( 'active_plugins' );

/* Получим в $active_plugins
Array
(
	[0] => hello-dolly/hello-dolly.php
	[1] => backupwordpress/backupwordpress.php
	[2] => democracy-poll/democracy.php
	[3] => disable-emojis/disable-emojis.php
)
*/

Из всего этого следует: просто своим присутствием плагины не влияют на скорость работы сайта (за исключением подключения файла плагина, а это супер быстрая операция). Неактивные плагины не влияют вообще никак. Подробнее читайте здесь.

Репозиторий плагинов WordPress

Плагин может быть личный (создается только для одного сайта), а может быть публичный (выкладывается в репозиторий плагинов WordPress).

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

Если планируете отправлять плагин на WordPress.org, нужно следовать требованиям к заголовку плагина WordPress.

Лицензия сообщает пользователям, как они могут использовать код плагина в своих целях. Для поддержания совместимости с ядром WordPress рекомендуется выбрать лицензию, работающую с GNU General Public License (GPLv2+).

Время на прочтение
12 мин

Количество просмотров 6.3K

Перед началом…

Всем привет! Это серия постов будет иметь много различных тем, но и я так-же не забыл о написании ядра на Rust, скоро будут продолжения).

Немного понятий

Я думаю, что стоит начать с некоторой основной информацией по созданию плагинов, а именно:

1. Все плагины основываются на Bukkit – API для плагинов, которая может немного отличаться в зависимости от версий.

2. Плагины пишутся в основном на Java или иногда на Kotlin.

3. Некоторая информация плагина исключительно для ядра храниться в plugin.yml, где можно найти версию плагина, главный класс плагина и многое другое.

4. В стандартных случаях плагинам хватает обычного, но существуют моменты, где могут понадобится NMS – net.minecraft.server или же API к самому Minecraft.

5. Плагины без труда могут использовать API других плагинов, если имеется такая возможность, например PlaceholderAPI и Vault.

6. Почти всегда, когда ядро обращается к плагину – выполняется в синхронном потоке сервера.

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

Подготавливаем наш тестовый сервер

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

Для начала нам стоит выбрать основную версию и ядро, я выбрал 1.16.5 версию так-как сейчас она как основа для версий выше.

Из статистики выше видно, что большинство серверов на 1.16.5 и выше, а ядро Paper и следовательно как изначально планировалось было выбрано ядро Paper. Скачать его версии 1.16.5 можно по этой ссылке.

Скачанный файл по ссылке выше я помещаю в отдельную директорию рядом со своим Start.sh файлом:

Содержимое Start.sh

java -Xms512M -Xmx1G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 -XX:InitiatingHeapOccupancyPercent=15 -Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true -jar paper-1.16.5-794.jar nogui

После первого запуска будет скачан кеш и создан eula.txt( в котором надо будет установить true вместо false ):

После изменения eula.txt будет такой вывод с полным запуском:

settings:
  allow-end: false
  warn-on-overload: true
  permissions-file: permissions.yml
  update-folder: update
  plugin-profiling: false
  connection-throttle: 0
  query-plugins: false
  deprecated-verbose: default
  shutdown-message: Server closed
  minimum-api: none
spawn-limits:
  monsters: 10
  animals: 10
  water-animals: 5
  water-ambient: 10
  ambient: 5
chunk-gc:
  period-in-ticks: 900
ticks-per:
  animal-spawns: 1
  monster-spawns: 1
  water-spawns: 1
  water-ambient-spawns: 1
  ambient-spawns: 1
  autosave: 12000
aliases: now-in-commands.yml

enable-jmx-monitoring=false
rcon.port=25575
level-seed=
gamemode=survival
enable-command-block=false
enable-query=false
generator-settings=
level-name=world
motd=Test Server
query.port=25565
pvp=true
generate-structures=false
difficulty=easy
network-compression-threshold=256
max-tick-time=60000
max-players=20
use-native-transport=true
online-mode=false
enable-status=true
allow-flight=false
broadcast-rcon-to-ops=true
view-distance=6
max-build-height=256
server-ip=
allow-nether=false
server-port=25565
enable-rcon=false
sync-chunk-writes=true
op-permission-level=4
prevent-proxy-connections=false
resource-pack=
entity-broadcast-range-percentage=100
rcon.password=
player-idle-timeout=0
debug=false
force-gamemode=false
rate-limit=0
hardcore=false
white-list=false
broadcast-console-to-ops=true
spawn-npcs=true
spawn-animals=true
snooper-enabled=true
function-permission-level=2
level-type=flat
text-filtering-config=
spawn-monsters=true
enforce-whitelist=false
resource-pack-sha1=
spawn-protection=16
max-world-size=500

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

• PlaceholderAPI – API для плейсхолдеров.

• PlugManX – форк оригинального PlugMan для работы с плагинами(перезагрузка, загрузка, выгрузка и тд).

• Auto Reload – автоматическая перезагрузка плагинов в случае изменений.

После загрузки можно перезагрузить частично сервер используя reload confirm. И потом плагины загрузятся и некоторые создадут конфигурации.

Изменённые конфигурации

ignored-plugins: [PlugManX]
notify-on-broken-command-removal: true
auto-load:
  enabled: true
  check-every-seconds: 2
auto-unload:
  enabled: true
  check-every-seconds: 2
auto-reload:
  enabled: false
  check-every-seconds: 2

# PlaceholderAPI
# Version: 2.11.1
# Created by: extended_clip
# Contributors: https://github.com/PlaceholderAPI/PlaceholderAPI/graphs/contributors
# Issues: https://github.com/PlaceholderAPI/PlaceholderAPI/issues
# Expansions: https://api.extendedclip.com/all/
# Wiki: https://github.com/PlaceholderAPI/PlaceholderAPI/wiki
# Discord: https://helpch.at/discord
# No placeholders are provided with this plugin by default.
# Download placeholders: /papi ecloud
check_updates: true
cloud_enabled: true
cloud_sorting: "name"
cloud_allow_unverified_expansions: true
boolean:
  'true': 'yes'
  'false': 'no'
date_format: MM/dd/yy HH:mm:ss
debug: true

enabled: false
serverUuid: 00000-00000
logFailedRequests: false

После сделанных изменений надо снова перезагрузить сервер, а после полной перезагрузки мы можем спокойно зайти на наш тестовый сервер с любого клиента, который поддерживает версию 1.16.5, так-же стоит выдать себе все права используя op <ваш ник>.

Подготовка нашего плагина

Так-как плагин будет написан на стандартном Java, то нам надо подумать о сборщике нашего плагина, есть несколько вариантов: IDE компилятор, Maven и Gradle. Давайте посмотрим основные плюсы и минусы, которые я выделил как основные:

• Компилятор IDE(IDEA, Eclipse и др)
  Плюсы:
  1) Все зависимости и компиляция настроены прямо в настройках редактора.
  2) Может быть быстрым но зависит от настроек компиляции.
  Минусы:
  1) Для редактирования может потребоваться конкретный редактор или его поддержка в другом редакторе.
  2) Часто ограничен возможностями самого редактора.
  3) Компиляция часто может идти тяжелее нежели на Maven или Gradle.

• Maven
  Плюсы:
  1) Возможно настроить и форматирование файлов, все зависимости и репозитори, а так-же плагины компиляции.
  2) Не зависит от конкретного редактора.
  3) Быстро компилирует, но хуже Gradle.
  Минусы:
  1) Для компиляции каждый раз запускается новый процесс, который каждый раз заново читает и собирает информацию.

• Gradle
  Плюсы:
  1) Есть настройки форматирования файлов, зависимостей, репозиторий и различных дополнений(например Lombok).
  2) Запускает компиляцию в фоновом процессе, который считывает конфиги и другое после изменений или при другой нужде.
  3) Не зависит от редактора как и Maven.
  4) Можно писать конфигурацию компиляции на языке Groovy или Kotlin DSL
  5) Запуск компиляции проходит с помощью запуска фонового процесса(если не запущен) или обращение к нему.
  Минусы:
  1) Фоновый процесс постоянно требует некоторое количество ОЗУ.

Вы конечно можете сами выбрать сборщик под себя, но я выбрал Gradle и из-за чего дальше будет информация связанная с ним. Так-же выбрал редактор Intellij IDEA от JetBrains так-как он очень замечательно работает с Java.

Первым делом нужно инициализировать Gradle проект:

После создания проекта я в первую очередь удалил папку test и изменил build.gradle под проект:

Содержимое build.grade

plugins {
    id 'java'
}

group 'xyz.distemi'
version '1.0-SNAPSHOT'

repositories {
    mavenCentral()
    maven {
        name = "PaperMC"
        url = "https://repo.papermc.io/repository/maven-public/"
    }
    maven {
        name = "PlaceholderAPI"
        url = 'https://repo.extendedclip.com/content/repositories/placeholderapi/'
    }
}

dependencies {
    compileOnly 'com.destroystokyo.paper:paper-api:1.16.5-R0.1-SNAPSHOT' // PaperMC
    compileOnly 'me.clip:placeholderapi:2.11.1' // API плагина PlaceholderAPI 
    compileOnly 'org.projectlombok:lombok:1.18.24' // Lombok API
    annotationProcessor 'org.projectlombok:lombok:1.18.24' // Lombok процессор
}

Теперь нам надо сделать главный класс плагина, который у меня будет xyz.distemi.litesmt.LiteSMT:

Базовый код главного класса плагина LiteSMT

package xyz.distemi.litesmt; // Объявляем наш пакет

// Импортируем Getter из ломбок, абстрактный класс JavaPlugin и
// интерфейс логгера.
import lombok.Getter; 
import org.bukkit.plugin.java.JavaPlugin;

import java.util.logging.Logger;

public class LiteSMT extends JavaPlugin {
  	// Создаём две статичные переменные:
    @Getter
    private static LiteSMT instance; // Класс плагина.
    @Getter
    private static Logger jlogger; // Логгер.
    @Override
    public void onEnable() {
				// Устанавливаем наши статичные переменные:
        instance = this; 
        jlogger = super.getLogger();
      	// Выводим в консоль сообщение Hello from LiteSMT
      	// от имени плагина.
      	jlogger.info("Hello from LiteSMT!");
    }
}

Чтож, главный класс у нас имеется, но для работы плагина этого недостаточно!
Серверу нужно знать какой же класс главный и другую информацию, для этого нам нужно создать файл plugin.yml, но уже не в качестве кода, а файл-ресурса, в Gradle такие файлы можно создать в директории проекта src/main/resources/, где файлы внутри не могут быть скомпилированы, а копируются в наш jar “сырыми”, но есть например возможность некоторого форматирования, однако пока думаю можно будет обойтись и без него.

Создание plugin.yml

name: LiteSMT
main: xyz.distemi.litesmt.LiteSMT
version: 1.0
author: Distemi
prefix: LSMT
depend:
  - PlaceholderAPI

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

task copyToDevEnv_1_16_5() {
    doLast {
        copy {
            from "build/libs/LiteSMT-1.0-SNAPSHOT.jar"
            into "../test-server1.16.5/plugins/"
        }
    }
}

build.finalizedBy copyToDevEnv_1_16_5

Тут мы объявляем задачу, которая копирует готовый jar плагина в папку указанную из into, а build.finalizedBy означает, что задачу build мы всегда заканчиваем с copyToDevEnv_1_16_5. Давайте теперь мы впишем ./gradlew build –offline -x test, где мы запускаем компиляцию без доступа к интернету(–offline) и исключаем задачу(-x) тестов(test). Теперь смотрим в нашу папку с плагинами и видим:

Ура! Наш плагин успешно собрался и сам был помещён в директорию с плагинами. Теперь пробуем запустить наш сервер и видим…

Да! Плагин наш был успешно запущен и при запуске вывел в консоль наше сообщение, однако для проверки автоматической перезагрузки плагина в случае изменений я могу чуть изменить сообщение в коде и заново собрать плагин прошлой командой в консоль/терминал и увидеть уже в консоли сервера:

Всё-таки я добавил “Changed from me!” в строку вывода и после сборки плагин AutoReload сам увидел изменение и перезагрузил плагин, ну не удобство ли, когда надо бывает частенько и главный класс изменить?)

Так-же как вы могли бы заметить, то наш префикс из plugin.yml тоже показывает результат так-как без того атрибута у нас выводился бы LiteSMT.

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

Обработка событий в плагине или как можно приукрасить чат.

Сейчас мы будем работать лишь с тремя из большого количества событий, а именно вход игрока, выход и написание сообщений в чат. Наверное многим не нравиться стандартный формат чата из и игры из-за чего скачивают и устанавливают плагины по типу Chatty и другого, но сейчас мы сделаем некую свою мини альтернативу, правда не всё, но хоть что-то)

Для событий в плагинах используют отдельные классы, которые просто помимо своего существования должны наследовать один из интерфейсов от Bukkit и быть зарегистрированы в событиях Bukkit-а.

Для событий чата будет у меня отдельный пакет в моём jar, а именно xyz.distemi.litesmt.listeners.chat, который в IDEA создаётся в два клика:

В нашем новом пакете создадим класс с именем MainChatListener, который по началу имеет только публикацию класса и пакет. И после его имени мы должны прописать implements Listener, однако как я говорил раньше, то нужно и импортировать классы, чтобы сборщик мог знать какой класс нам нужен и JVM тоже, поэтому IDEA предлагает выбрать Listener из нескольких пакетов, но нам нужен именно с org.bukkit.event и следом появиться импорт org.bukkit.event.Listener. Теперь данный класс для ядра считается неким слушателем событий, однако он не зарегистрирован и пусть, а это значит, что от него нету толка, для этого в главном классе, в onEnable мы прописываем:

Bukkit.getPluginManager().registerEvents(new MainChatListener(), this);

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

– Тогда получается возможно регистрировать слушатели и из других плагинов?
– Верно! Однако не стоит так делать.

Если мы и попробуем сейчас собрать плагин и протестировать его, то у нас не будет никаких отличий так-как слушатель хоть и существует, но он пустой. Давайте попробуем создать в нём функцию для форматирования сообщений из чата, а именно установка своего формата сообщений:

import io.papermc.paper.event.player.AsyncChatEvent;
import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.TextColor;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class MainChatListener implements Listener {
    @EventHandler
    public void onChat(AsyncChatEvent event) {
        event.renderer((source, sourceDisplayName, message, viewer) -> 
                Component.text()
                  .append(sourceDisplayName.color(TextColor.fromHexString("#a8a432")))
                  .append(Component.text(" : "))
                  .append(message)
                  .build());
    }
}

Объяснение кода

Теперь если мы попробуем набрать в консоль любое сообщение, то увидим:

Далее я бы убрал сообщение выхода с сервера таким кодом:

@EventHandler
public void onQuit(PlayerQuitEvent event) {
	event.quitMessage(null);
}

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

Можно и приукрасить сообщение о входе:

@EventHandler
public void onJoin(PlayerJoinEvent event) {
	event.joinMessage(Component.text()
		.append(Component.text("["))
    .append(Component.text("+", TextColor.fromHexString("#28ff03")))
    .append(Component.text("] "))
    .append(event.getPlayer().displayName())
    .build());
}

И после сборки этого кода, то при заходе будет данное сообщение:

Итог

Вот и была сделана небольшая основа для плагина, которая дальше будет дополняться всё большим функционалом в следующих частях!

Готовый сходный код доступен по этой ссылке.

От автора: для получения максимального результата от урока по разработке плагина для WordPress вы должны понимать базовые понятия, такие как экшены, фильтры, шорткоды, виджеты и объектно-ориентированный дизайн.

Реальный пример – Список филиалов компании

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

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

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

Настройка

Давайте все настроим, перейдите в папку плагина и создайте следующие папки/файловую структуру

Самый верхний файл wp_simple_location_plugin.php будет главным. Тут мы будем загружать наши стили из папки CSS, а также дополнительные PHP файлы из папки inc.

Основной класс местоположения

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

Непрямой доступ

Рекомендуется закрывать прямой доступ к PHP файлам с помощью проверки на существование константы ABSPATH (если не существует, скрипт прекращает работу). Поместите код ниже прямо после открывающего PHP тега:

Объявление плагина

Чтобы плагин работал, его сначала необходимо объявить. Объявление выглядит, как набор комментариев для WordPress, в которых содержится информация о плагине. В плагин необходимо добавить код ниже, иначе он просто не появится в менеджере плагинов в WP.

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

Класс wp_simple_location Class

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

Подключаем файлы шорткодов и виджета

Так как мы будем использовать и виджет и шорткод, то было решено разбить функционал на два отдельных файла.
Скопируйте код ниже в самый конец класса wp_simple_location:

Код выше подключает наши файлы. О них мы поговорим чуть позже.

Свойства класса

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

Функция _construct

Функция _construct – важная часть плагина. Это мастер-функция, с помощью которой можно обрабатывать и запускать другие функции.

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

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

Функции register_activation_hook и register_deactivation_hook используются для встраивания в другие функции при активации и отключении плагина. Мы будем использовать эти функции для проверки правильности добавленного типа контента (наши места) и обработки ссылок (мы будем использовать человекопонятные ссылки).

Настройка рабочих часов для определенного филиала

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

Рабочие дни хранятся на стороне back-end’а в свойстве $wp_location_trading_hour_days. Для настройки рабочих дней и часов необходимо вызвать функцию set_location_trading_hour_days.

После заполнения значений массива необходимо вызвать фильтр wp_location_trading_hours_days. Т.е. тема или другой плагин смогут переписать рабочие дни магазина (они могут фильтровать массив и добавить поле каникул «holidays», чтобы потом задать для этого периода свое рабочее время).

Настройка рабочих часов заданного филиала

Тут мы создадим наш пользовательский тип местоположений, который будем использовать в плагине. Необходимо указать лейблы и аргументы типа контента и передать наши аргументы в функцию register_post_type. На странице кодекса объясняются все варианты пользовательского типа контента. Для нашего типа нам понадобятся заголовок, редактор и встроенное изображение.

После добавления этого кода в меню должна появиться новая строка.

Добавляем мета бокс к новому типу местоположений

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

Третье значение add_meta_box – функция, которая будет показывать наш бокс. Тут мы вызываем функцию location_meta_box_display, ее мы создадим следующей.

Функция location_meta_box_display

Эта функция будет вызываться из мета бокса и будет показывать дополнительные поля, которые администратор сможет использовать для записи информации о месте.

Что делает функция:

Мета бокс должен показаться на странице места. Выглядеть это будет примерно так:

Регистрация типа контента и обработка правил перезаписи во время активации

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

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

Также мы изменим правила перезаписи, чтобы можно было использовать человекопонятные ссылки (у нас будут ссылки типа example.com/location/mylocation вместо example.com/?p=144)

Сброс правил перезаписи при отключении плагина

Функция plugin_deactivate срабатывает при отключении плагина. Так как мы удаляем плагин, а в плагине использовался пользовательский тип контента, то для верности необходимо сбросить правила перезаписи.

Показываем мета данные для конкретного места

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

Функция prepend_location_meta_to_content цепляется к фильтру the_content, т.е. мы можем добавить свои данные перед главным контентом страниц.

Что делает функция:

Выводим список мест

Необходимо создать функцию для создания HTML кода списка мест. Функция get_locations_output используется как виджетом, так и шорткодом для создания разметки. Так как функция многозадачная, в ней есть несколько важных действий. Разберем все по порядку.

Сохранение дополнительных мета данных

При сохранении нового места необходимо запускать функцию, которая будет собирать и обновлять наши дополнительные мета поля (почта, телефон, адрес и т.д). Для этого мы создадим функцию save_location.

Что мы делаем:

Загружаем админ и публичные скрипты и стили

Нам необходимо загрузить дополнительные CSS файлы как для front-end, так и для back-end стороны нашего сайта. Для этого мы создадим две функции, которые будут загружать любые скрипты или файлы стилей.

Внутри CSS файлов будут стили полей мета бокса в панели администратора, а также немного стилей front-end’а. Плагин замечательно работает без CSS стилей. Если вам эта часть не интересна, ее можно пропустить. (Если вы пропускаете эту часть, не забудьте удалить вызов экшенов в конструкторе)

Шорткод

Теперь можно перейти к классу шорткода, который будет работать в паре с нашим основным классом. Шорткоды предоставляют администратору простой интерфейс отображения различных мест. Шорткоды будут настраиваемые, администратор сможет задавать конкретный филиал (место) по ID или же показывать все филиалы сразу. Шорткод на странице будет выглядеть примерно следующим образом:

Работать мы будем в файле wp_location_shortcode.php.

Запрет на прямой доступ

Как в случае с основным файлом PHP, тут мы тоже хотим закрыть прямой доступ. Скопируйте код ниже в верхушку файла:

Класс wp_location_shortcode

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

Функция __construct

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

Функция register_location_shortcodes

С помощью этой функции мы будем добавлять шорткод. Мы вызываем функцию add_shortcode для добавления нового шорткода wp_locations. Для вывода шорткода будем использовать функцию location_shortcode_output.

Вывод шорткода

Функция вывода вызывается из функции add_shortcode и нужна для формирования кода для вывода шорткода на экран.

Что делает функция:

Создаем объект wp_location_shortcode

В самом конце класса необходимо создать объект wp_location_shortcode. Таким образом будет активирован весь функционал класса.

Виджет

Закончим статью классом, работающим с виджетом. Мы добавим виджет, потому что почти все темы сейчас поддерживают виджеты. Виджеты дают администраторам простой и быстрый способ демонстрации чего-либо (в нашем случае это филиалы компании). Откроем файл wp_location_widget.php и начнем.

Запрет прямого доступа

И опять мы запрещаем прямой доступ к PHP файлу с помощью следующей строки:

Класс wp_location_widget

Создадим базовую структуру класса wp_location_widget. Класс похож на предыдущие; но в этот раз мы расширим уже существующий класс WP_widget.

Функция __construct

В функции _construct мы определим наши базовые стили виджета. А сделаем мы это, перегрузив родительский конструктор и передав в него наши значения. Нам необходимо задать ID, название и описание виджета. Также мы прицепим нашу функцию register_wp_location_widgets к хуку widgets_init, чтобы зарегистрировать наш виджет.

Создаем интерфейс виджета в панели администратора

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

Функция form() унаследована от родительского класса WP_widget, она будет автоматически вызываться, когда мы будем заходить на экран виджета в панели администратора.

Что тут происходит:

Обновление виджета и сохранение вариантов

Для сохранения значений формы необходимо вызывать функцию обновления виджета. Функция update() унаследована от класса WP_widget. Нам осталось только указать, как сохранять значения.

У нас есть две переменные $new_instance и $old_instance. В $new_instance хранятся текущие значения формы, а в $old_instance хранятся старые значения. Нам необходимо создать новый массив для хранения извлеченных значений для последующего их возврата.

Отображение виджета на стороне front-end’а

Функция widget() унаследована из класса WP_widget, с ее помощью виджет показывается на стороне front-end’а. Для формирования кода на вывод используется функция отображения из класса wp_simple_locations.

Что мы тут делаем:

Регистрация виджета

Функция ниже нужна для регистрации виджета в WordPress. Необходимо вызвать функцию register_widget() и передать в нее название класса в качестве значения.

Надеюсь, вам понравился реальный пример разработки плагина для WordPress с нуля. Следите за моими статьями.

Автор: Simon Codrington

Источник: //www.sitepoint.com/

Редакция: Команда webformyself.