18 июля, 2018
11мин. чтения
Elena B.
В этом руководстве мы подробно рассмотрим как создать плагин WordPress со своей собственной страницей администрирования. Характерная особенность любого плагина – это отделение своего кода от кода ядра WordPress. Если с плагином что-то произойдёт, остальная часть сайта будет работать.
Для выполнения шагов этого руководства вам понадобиться текстовый редактор, например, Notepad++ или среда разработки NetBeans. Также вам нужен доступ по FTP в вашей учётной записи на хостинге и работающая установка WordPress.
Узнать о том, как подключить Notepad++ к своей FTP-серверу можно прочитать в руководстве как подключиться по FTP с Notepad++(англ.). Также вы можете воспользоваться FTP программой такой как FileZilla для загрузки ваших файлов и подробнее узнать о том, как настроить клиент FileZilla в этом руководстве.
Данное плагин WordPress руководство написано для тех, кто уже имеет базовые знания в программировании на PHP. По руководству мы создадим новую функцию, вызовем существующие функции WordPress, используя их как параметры.
Также настоятельно рекомендуем сделать бекап вашего сайта(англ.) перед началом.
Плагин WordPress – это автономный код, который улучшает и расширяет функциональность WordPress. Используя любую комбинацию PHP, HTML, CSS, JavaScript/jQuery или ряда других языков программирования, плагин WordPress может добавить новые характеристики к любой части вашего сайта, включая Консоль Администрирования. Вы можете изменять поведение WordPress по умолчанию или полностью удалять ненужное поведение. Плагины позволяют легко настраивать WordPress под себя и свои потребности.
Поскольку плагин WordPress это отдельный код, он не пересекается непосредственно с какой либо частью кода ядра WordPress. Плагин может быть скопирован или установлен на любую установку WordPress. Альтернативный (и очень не рекомендуемый) путь внесения изменений в WordPress – написание новой функции в файл WordPress functions.php, который находится в каталоге /wp-includes/ или в файл functions.php, который является частью вашей темы. Это может привести к ряду возможных проблем.
WordPress и его темы регулярно обновляются. И пока вы используете дочернюю тему WordPress, очередное обновление будет перезаписывать файл functions.php, а добавленный вами новый код будет удален и придётся его добавлять снова и снова. Ещё один неудобный момент может возникнуть, если вы напишете много функций и в одной из них будет ошибка, которую вы никак не может отследить, вам может потребоваться заменить текущий файл оригинальным, однако при этом придётся пожертвовать всеми остальными функциями. Это повлечёт за собой большое количество PHP-ошибок на сайте, потому как вызовы уже удалённых функций ещё будут осуществляться из других мест.
Плагины же никогда автоматически не перезаписываются и не удаляются при обновлении WordPress. Если в коде вашего плагина WordPress есть ошибки, вы можете просто отключить его в Админ Консоли на время исправления ошибки. В случае, если в вашем плагине серьёзная ошибка, WordPress иногда может самостоятельно автоматически отключить его, чтобы сохранить функционирование всего сайта.
Плагины WordPress взаимодействуют с кодом ядра через так называемые хуки (hooks, от англ. hook – крючок). К ним, как к крючкам можно «цеплять» выполнение каких-либо интересных нам функций. В WordPress есть два вида хуков:
Посещение любой страницы WordPress-сайта – это вызов множества функций PHP (называемых событиями – actions). Функции привязываются к хукам-событиям (action hooks). Механизм хуков-событий предоставляется WordPress. Вы можете добавлять свои функции к какому-либо событию из списка событий, используя механизм хуков и они будут запускаться по запуску этого события. Вы также можете удалять уже существующие функции из любого списка хуков-событий. Хуки-события привязаны к выполнению определённого события. Например, перед закрытием тега </head> на любой странице, вызывается хук-событие wp_head() и запускается ряд функций, которые привязаны к этому хуку wp_head().
Хуки-события являются контекстными – некоторые вызываются на каждой странице сайта, другие только, когда отображается Админ Консоль и так далее. Полный список событий и контекста, в котором их можно вызывать смотрите здесь странице API плагина/Справка по Action.
Чтобы добавить функцию на любой хук-событие, ваш плагин WordPress должен вызвать функцию WordPress под названием add_action(), как минимум с двумя параметрами.
// Хук события 'init', вызывается после того, как WordPress завершает загрузку кода ядра add_action( 'init', 'add_Cookie' ); // Установка cookie с текущим временем дня function add_Cookie() { setcookie("last_visit_time", date("r"), time()+60*60*24*30, "/"); }
Этот плагин WordPress перехватывает хук-событие wp_footer(), который вызывается сразу перед закрытием тега </body> на каждой странице и добавляет новую функцию под названием mfp_Add_Text(). Так как плагин WordPress не привязывается к теме, то функционал будет работать даже при смене темы на другую. Можете сохранить себе этот пример в файл PHP, загрузить его в каталог wp-content/plugins/ и активировать в Админ Консоли, чтобы увидеть изменения.
<?php /* Plugin Name: Add Text To Footer */ // Хук события 'wp_footer', добавляем функцию 'mfp_Add_Text' к нему add_action("wp_footer", "mfp_Add_Text"); // Определяем 'mfp_Add_Text' function mfp_Add_Text() { echo "<p style='color: black; padding-left: 15%;'>После загрузки футера сайта добавляется мой текст!</p>"; } ?>
Вот результат:
Примечание: PHP загружает содержимое сразу всего скрипта перед его выполнением, это значит, что вы можете вызвать add_action() перед определением вашей функции: вызвать add_action() с вашими функциями вначале файла в том порядке, в котором они будут загружаться, потом определить ваши функции в таком же порядке ниже. Такое структурирование кода сделает файл более лёгким для чтения.
Для удаления функции, связанной с хуком-событием, нужно воспользоваться remove_action(). Пример ниже поможет понять принцип работы добавления и удаления функций в/из хука событий.
// Хук на событие 'init', который вызывается после завершения загрузки ядра WordPress и функция 'remove_My_Meta_Tags' add_action( 'init', 'remove_My_Meta_Tags' ); // Удаляем функцию 'add_My_Meta_Tags' из хука-события wp_head function remove_My_Meta_Tags() { remove_action( 'wp_head', 'add_My_Meta_Tags'); }
Запускается remove_action() как минимум в двумя параметрами.
Пример: представим, что вы хотите, чтобы текст, добавленный в футере в предыдущем примере, не выводился по понедельникам. Один из путей реализации этого, использовать функцию даты в PHP, чтобы получить текущий день недели, проходя условным оператором if…then… и проверяя соответствует ли текущий день понедельнику, затем вызвать remove_action(), если это понедельник. Вызываем функцию проверки и удаления по дню недели при помощи add_action(), прикрепляясь к событию, происходящему раньше (например, wp_head), чем то, к которому прикреплено наше основное действие выведения текста в футере (wp_footer). Если мы выберем событие происходящее позже, чем wp_footer, удаления не произойдёт, поскольку страница уже будет сгенерирована.
<?php // Хук события 'wp_footer', запуск функции 'mfp_Add_Text()' add_action("wp_footer", "mfp_Add_Text"); // Хук события 'wp_head', запуск функции 'mfp_Remove_Text()' add_action("wp_head", "mfp_Remove_Text"); // Определение функции 'mfp_Add_Text()', выводящей текст function mfp_Add_Text() { echo "<p style='color: black; padding-left: 15%;'>После загрузки футера сайта добавляется мой текст!</p>"; } // Определение функции 'mfp_Remove_Text()' удаление нашей предыдущей функции из события 'wp_footer' function mfp_Remove_Text() { if (date("l") === "Monday") { // Target the 'wp_footer' action, remove the 'mfp_Add_Text' function from it remove_action("wp_footer", "mfp_Add_Text"); } } ?>
Функции фильтры позволяют изменять возвращаемые другими функциями данные и должны быть прежде перехвачены при помощи хуков-фильтров. Хуки-фильтры несколько отличаются от хуков-событий. Однако, работают они подобно хукам-событиям — могут быть вызваны в разных точках скрипта и контекстно. Полный список хуков-фильтров и контекста вызова можно найти на WordPress Plugin API/Filter Reference page.
Чтобы добавить любую функцию к хуку-фильтру, ваш плагин должен вызвать функцию WordPress под названием add_filter(), с как минимум двумя параметрами.
// Перехват хука-фильтра 'the_content' (содержимое любого поста), запуск функции 'mfp_Fix_Text_Spacing' add_filter("the_content", "mfp_Fix_Text_Spacing"); // Автоматическое исправление двойного пробела function mfp_Fix_Text_Spacing($the_Post) { $the_New_Post = str_replace(" ", " ", $the_Post); return $the_New_Post; }
В WordPress есть функция, которая извлекает отрывок (цитату) из записи, называется она get_the_excerpt(), и также является хуком-фильтром. Функция, отображающая отрывок, вызывает get_the_excerpt(), чтоб его получить, это то место, где применяется фильтр и отрывок изменяется до отображения. Этот плагин WordPress определяет функцию фильтр, которая берёт отрывок текста как входной параметр, добавляет некоторый текст вначале него и возвращает новое значение каждый раз, когда вызывается get_the_excerpt(). Так как возвращаемое функцией get_the_excerpt() значение – это фактический фрагмент текста, он автоматически вводится как параметр функции $old_Excerpt, когда вызывается, используя add_filter(). Функция, которую вы определяете должна вернуть новое значение.
<?php /* Plugin Name: Add Excerpt */ // Перехватываем get_the_excerpt фильтр хук, запускаем функцию mfp_Add_Text_To_Excerpt add_filter("get_the_excerpt", "mfp_Add_Text_To_Excerpt"); // Берём отрывок, добавляем некоторый текст перед ним и возвращаем изменённый отрывок function mfp_Add_Text_To_Excerpt($old_Excerpt) { $new_Excerpt = "<b>Excerpt: </b>" . $old_Excerpt; return $new_Excerpt; } ?>
Для удаления фильтра нужно просто вызвать функцию remove_filter(). Например, добавим снова простое условие и будем удалять текст, если сегодня четверг.
// Хук-фильтр get_the_excerpt, запуск функции mfp_Add_Text_To_Excerpt add_filter("get_the_excerpt", "mfp_Add_Text_To_Excerpt"); // Если сегодня четверг, удалить фильтр the_excerpt() if (date("l") === "Thursday") { remove_filter("get_the_excerpt", "mfp_Add_Text_To_Excerpt"); } // Взять отрывок, добавить текст и вернуть новый отрывок function mfp_Add_Text_To_Excerpt($old_Excerpt) { $new_Excerpt = "Excerpt: " . $old_Excerpt; return $new_Excerpt; }
Теперь, когда уже есть базовое представление о хуках фильтрах и событиях, создадим простой плагин WordPress, который добавляет новую ссылку и страницу в Админ Консоль.
Первым шагом в создании плагина для WordPress является создания каталога для хранения всех файлов. Все плагины хранятся в каталоге: /wp-content/plugins/. Каталог, который вы создаёте должен иметь уникальное и понятное название, не пересекающееся с другими плагинами. Поключитесь к своему аккаунту на хостинге по FTP. Из основного каталога WordPress перейдите в wp-content потом в plugins. Внутри каталога plugins создайте новый каталог с названием my-first-plugin.
Отдельные файлы с кодом плагина лучше тематически разделять по подкаталогам внутри основного каталога плагина вместо того, чтобы хранить всё в одном каталоге, это позволит не путаться и будет хорошим смысловым разделением исходных файлов плагина. Особенно разделение файлов по смыслу будет хорошо ощутимо, когда ваш плагин будет разрастаться и становиться более сложным. Если ваш плагин использует свои стили CSS создайте каталог CSS и сохраните туда все файлы CSS. Если ваш плагин WordPress использует JavaScript создайте каталог JavaScript.
Первый файл вашего плагина – очень важный. Он содержит всю информацию, необходимую для WordPress, чтобы отобразить ваш плагин в списке текущих активных плагинов.
В вашем каталоге my-first-plugin создайте новый PHP-файл и назовите его my-first-plugin.php. Хорошей практикой является название основного файла плагина также как и каталога. Добавьте открывающий тег PHP <?php в первой строке. Вам не обязательно добавлять закрывающий тег в конце файла (чтобы понять почему, почитайте примечание на странице PHP мануала). Этот файл будет содержать прежде всего так называемые ‘header comments’ или заголовочные комментарии с информацией, которая будет прочитана и отображена WordPress. Header comments заключается в многострочный комментарий PHP, в каждой строке определяется специальная информация, начинающаяся со специальных символов, чтобы можно было определить, к чему эта строка относится. Такая структура должна присутствовать только в первом файле и её не нужно повторять в остальных.
Первой строкой в комментарии в файле my-first-plugin.php нужно добавить имя плагина. Начинайте многострочный комментарий PHP открывая его символами /* во второй строке файла, сразу после тега открытия PHP. В третьей строке напишите Plugin Name: My First Plugin. В двух следующих отдельных строках можно указать описание плагина и имя автора. Затем, со следующей строки закрываем блок комментариев символами */. Ваш файл теперь выглядит примерно так:
<?php /* Plugin Name: My First Plugin Description: Это мой первый плагин! Он создаёт отдельную админ-ссылку! Author: Имя автора */
Как только вы его загрузите обновите страницу Плагины в Админ части сайта и вы сможете увидеть в списке свой плагин, его описание и Имя автора.
Как уже было сказано выше, хорошей практикой является разделение кода плагина в соответствующие файлы и каталоги. Так как основная функция первого файла в том, чтобы содержать в себе информацию о плагине, то сам плагин WordPress разместим в других файлах и каталогах и воспользуемся функцией PHP ‘include’ для доступа к ним. Любые файлы, хранящиеся в подкаталогах вызываются прямо из нашего кода и только из нашего кода, поэтому имя подкаталога не нуждается в префиксе. Однако, весьма рекомендуем применять уникальный префикс для ваших файлов, функций и переменных, чтобы избежать конфликтов с другими плагинами. В связи в этим мы будем использовать префикс mfp, сокращение от ‘My First Plugin’.
В главном каталоге вашего плагина создайте новый подкаталог с названием includes. Любой файл, который будет подключатся по ‘include’ в другом файле будет идти в этот подкаталог. Создайте новый файл PHP в подкаталоге includes и сохраните его как mfp-functions.php. Открываем тег <?php в первой строке. В этом новом файле будут храниться функции вашего плагина.
Теперь вернитесь к my-first-plugin.php в основном каталоге плагина. Нам нужно подключить файл mfp-functions.php, для того чтобы использовать новые функции. Так как это главный файл плагина, подключение mfp-functions.php здесь сделает функции доступными в любом другом файле вашего плагина. Используйте require_once, чтобы один раз подключить файл с функциями и чтобы быть уверенным, что плагин работает только, если функции доступны. Самый простой путь подключения файлов из вашего каталога плагинов – это использование функции WordPress plugin_dir_path(__FILE__), которая выдаёт полный путь к директории, где наш плагин WordPress хранится, потом использовать . (period), чтобы дополнить именем подкаталога, который мы создали раньше (includes), затем имя созданного нами файла (mfp-functions.php).
Редактируем my-first-plugin.php как показано ниже, потом сохраняем и загружаем ещё раз, перезаписывая предыдущую версию.
<?php /* Plugin Name: My First Plugin Description: Это мой первый плагин! Он создаёт отдельную админ-ссылку! Author: Имя автора */ // Подключаем mfp-functions.php, используя require_once, чтобы остановить скрипт, если mfp-functions.php не найден require_once plugin_dir_path(__FILE__) . 'includes/mfp-functions.php';
Вернёмся к mfp-functions.php в подкаталоге includes.
Хорошая идея объединить несколько функций вместе и написать многострочный комментарий над каждой группой, описывая группу, затем короткий однострочный комментарий перед каждой из функций с её описанием. Таким образом вам не придётся читать весь код в поисках функции и распознаванию, что она делает. Назовём функцию mfp_Add_My_Admin_Link(). Она будет добавлять новую верхнюю ссылку в Админ Консоли в меню навигации.
Резюмируя, пишем новую функцию следуя этим шагам:
В mfp-functions.php, пишем следующее:
<?php /* * Добавляем новое меню в Админ Консоль */ // Добавляем новую ссылку в меню Админ Консоли function mfp_Add_My_Admin_Link() { // My code goes here }
Внутри нашей функции нам нужно использовать встроенную функцию WordPress add_menu_page() , чтобы задать имя меню, заголовок и определить, кто может её видеть. Затем мы говорим, что отображать, когда мы переходим на страницу. Вы можете также добавить к ссылке в меню иконку и установить её позицию в меню навигации админ панели – и то и другое по желанию, поэтому в нашем руководстве мы на этом не будем останавливаться. Рядом со ссылкой на вашу страницу будет отображаться иконка по умолчанию. Наша ссылка появится внизу меню навигации админ консоли. Вся эта информация вводится как параметры в add_menu_page().
Четыре необходимых параметра add_menu_page() – каждый с новой строки для лучшей наглядности:
Прежде чем мы продолжим, важно знать, что есть альтернативный путь использования этой функции. Четвертый параметр может быть просто строкой текста, которая отображается в ссылке url после ‘wp-admin/admin.php?page=’. Если вы введёте ‘my-plugin-page’, URL станет ‘wp-admin/admin.php?page=my-plugin-page’. Четвёртый параметр тогда должен быть именем функции, которая выводит что-либо. Вы можете написать функцию, которая лишь выводить ‘Welcome to page 1’, например. Значительно проще создать PHP файл, который будет содержать вашу страницу.
Редактируем mfp-functions.php, удаляем // My code goes here, заменяем его на add_menu_page() и передаём параметры, как показано ниже:
<?php /* * Добавляем новое меню в Админ Консоль */ // Добавляем новую ссылку в меню Админ Консоли function mfp_Add_My_Admin_Link() { add_menu_page( 'My First Page', // Название страниц (Title) 'My First Plugin', // Текст ссылки в меню 'manage_options', // Требование к возможности видеть ссылку 'my-first-plugin/includes/mfp-first-acp-page.php' // 'slug' - файл отобразится по нажатию на ссылку ); }
Чтобы запустить эту функцию нам нужно использовать функцию WordPress под названием add_action() с двумя параметрами, как описано в разделе ‘Добавление функций на хук-событие’ этого руководства. Вы можете перечитать этот раздел перед тем, как продолжить.
Наш окончательный файл выглядит так:
<?php /* * Добавляем новое меню в Админ Консоль */ // Хук событие 'admin_menu', запуск функции 'mfp_Add_My_Admin_Link()' add_action( 'admin_menu', 'mfp_Add_My_Admin_Link' ); // Добавляем новую ссылку в меню Админ Консоли function mfp_Add_My_Admin_Link() { add_menu_page( 'My First Page', // Название страниц (Title) 'My First Plugin', // Текст ссылки в меню 'manage_options', // Требование к возможности видеть ссылку 'my-first-plugin/includes/mfp-first-acp-page.php' // 'slug' - файл отобразится по нажатию на ссылку ); }
Загрузите файл mfp-functions.php в каталог includes и перезапишите старый.
Теперь можно создать страницу, которая будет отображаться при нажатии на ссылку в вашей админ консоли. Вернитесь в подкаталог includes и создайте новый файл PHP с названием mfp-first-acp-page.php. Открывающий тег PHP не обязателен в этом файле, поскольку мы будем использовать только HTML. Напишите HTML-код, как показано ниже и загрузите файл.
<div class="wrap"> <h1>Привет!</h1> <p>Это первая страница плагина :)</p> </div>
При создании админ страниц, WordPress рекомендует заключать свой HTML в теги div и давать ему имя класса “wrap”, как показано выше. Это гарантирует, что весь ваш контент появится в правильном месте и будет выглядеть также как и другие админ страницы. Если не придерживаться этой рекомендации, страница может выглядеть не очень привлекательно.
Вернитесь к списку плагинов WordPress в Админ Консоли и активируйте его. Как только страница загрузится, посмотрите вниз мену навигации админ панели. Здесь вы увидите новую ссылку с именем ‘My First Plugin’. Нажмите на неё и вы увидите свою родную страницу админ управления!
Поздравляем, вы только что создали свой первый плагин WordPress, добавили новую ссылку в админ меню и отобразили новую страницу в Админ Консоли! Кажется, что это не так уж и много, но это первые уверенные шаги. Теперь, опираясь на полученные знания, вы можете изменять функционал WordPress так, как вам потребуется. Больше знаний о WordPress ищите в наших других руководствах WordPress.
13 августа 2018
Спасибо большое статья очень помогла! я писал до этого плагины но без страницы админа теперь буду писать плагины с настройками
26 января 2020
Нет ли у вас инструкции, как использовать add-on из одной темы в другой? Есть тема, а в ней хорошие аддоны, но использовать хочу другую тему. Хочу перенести аддоны из одной темы в другую, но несоображу как это сделать. Надеюсь понятно описал, что хочу сделать. Может кто подскажет?
Отвечено 18 февраля 2020
Здравствуйте, Сергей! Спасибо за вопрос. К сожалению по этому вопросу у нас инструкции нет, но спасибо за идею. А пока, возможно, кто-то из наших читателей сталкивался с подобным и сможет Вам ответить.
23 февраля 2020
а как вывести сообщение из созданного плагина в какую-нибудь страницу? Например, если нажать на кнопку на админ. странице плагина, то должно появиться сообщение "Привет! Ты нажал на кнопку" Как вывести это сообщение на админ. страницу плагина или на какую-нибудь другую страницу?
Богдан
Отвечено 01 августа 2019
Чётко описанная и понятная статья, я очень благодарен всем кто принимает участие в создании ,поддержке и развитии данного проекта. От души "Спасибо вам Огромное" С уважением к 'Участвующим'