Объективные лучшие практики разработки плагинов?

Загрузка скриптов и CSS с помощью wp_enqueue_script и wp_enqueue_style

Плагины не должны загружать или пытаться загружать дублирующиеся версии файлов JS/CSS, особенно jQuery и других JS-файлов, входящих в ядро WordPress.

Плагины всегда должны использовать wp_enqueue_script и wp_enqueue_style для подключения JS и CSS файлов, а не напрямую через теги <script>.

Связанные темы

• Использование существующих функций

Поддержка интернационализации (I18n)

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

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

См. Codex: Интернационализация для разработчиков WordPress

А также эту статью: Правильная загрузка языковых файлов в WordPress.

Начиная с WordPress 4.6+

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

Рассмотрим плагин с текстовым доменом 'my-plugin'. Теперь WordPress СНАЧАЛА будет искать файл перевода по пути:
/wp-content/languages/plugins/my-plugin-en_US.mo

Если файл не найден, WordPress проверит путь, указанный в плагине (обычно в папке 'language', если следовать рекомендациям Codex):
/wp-content/plugins/my-plugin/languages/my-plugin-en_US.mo

В крайнем случае, если языковой файл так и не найден, будет проверено стандартное расположение:
/wp-content/languages/my-plugin-en_US.mo

Первый вариант был добавлен в версии 4.6 и предоставляет пользователям определенное место для добавления языкового файла. Раньше пользователям нужно было знать, где разработчик разместил языковой файл, теперь же достаточно знать текстовый домен плагина: /wp-content/languages/plugins/ТЕКСТОВЫЙ_ДОМЕН-ЛОКАЛЬ.mo

Старый способ (Не актуально с версии WP 4.6+)

[...]
Наконец, хочу подчеркнуть, что важно загружать пользовательские языковые файлы из WP_LANG_DIR перед загрузкой языковых файлов, поставляемых с плагином. Когда для одного домена загружено несколько MO-файлов, будет использован первый найденный перевод. Таким образом, языковые файлы плагина будут служить резервным вариантом для строк, не переведенных пользователем.

public function load_plugin_textdomain()
{
    $domain = 'my-plugin';
    // Фильтр "plugin_locale" также используется в load_plugin_textdomain()
    $locale = apply_filters( 'plugin_locale', get_locale(), $domain );

    load_textdomain( 
            $domain, 
            WP_LANG_DIR . '/my-plugin/' . $domain . '-' . $locale . '.mo' 
    );
    load_plugin_textdomain( 
            $domain, 
            FALSE, 
            dirname( plugin_basename(__FILE__) ) . '/languages/' 
    );
}

Убедитесь, что плагины не вызывают ошибок при WP_DEBUG

Всегда тестируйте свои плагины с включённой опцией WP_DEBUG и, в идеале, держите её включённой на протяжении всего процесса разработки. Плагин не должен вызывать НИКАКИХ ошибок при включённом WP_DEBUG. Это включает в себя уведомления об устаревших функциях и непроверенных индексах.

Чтобы включить режим отладки, отредактируйте файл wp-config.php, установив константу WP_DEBUG в значение true. Подробнее см. в Кодексе по отладке.

Сначала используйте существующие функции в ядре WordPress

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

Одним из преимуществ является возможность использовать "уведомления об устаревании" для простого отслеживания функций, которые следует заменить. Ещё одно преимущество — пользователи могут просмотреть документацию по функциям в Codex и лучше понять, что делает плагин, даже если они не являются опытными PHP-разработчиками.

Связанные материалы

• Поддержка интернационализации (I18n)
• Загрузка скриптов/CSS с помощью wp_enqueue_script и wp_enqueue_style
• Предоставление расширяемых форм

Удаление плагина должно очищать все его данные

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

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

Связанные темы

• Деактивация не должна приводить к потере данных

Предотвращение SQL-инъекций при работе с входными данными

Плагин должен санировать все пользовательские данные, полученные напрямую или косвенно (например через $_POST или $_GET) перед использованием этих значений в запросах к базе данных MySQL.

Смотрите: Форматирование SQL-запросов.

Используйте классы и объектно-ориентированный PHP-код

Нет причин не писать чистый, объектно-ориентированный PHP-код. Поддержка PHP4 прекращена ещё в 2008 году. Конечно, вы можете добавлять префиксы ко всем именам функций и получать что-то вроде бесконечно_длинные_имена_функций_с_кучей_подчёркиваний, но гораздо проще создать простой класс и собрать всё внутри него. Также поместите ваш класс в отдельный файл и назовите его соответствующим образом, чтобы его можно было легко расширять и поддерживать:

// в functions.php
require 'inc/class-my-cool-plugin.php';
new MyCoolPlugin();

// в inc/class-my-cool-plugin.php
class MyCoolPlugin {
    function __construct() {
        // добавляем хуки фильтров, wp_enqueue_script и т.д.
        
        // Чтобы назначить метод из вашего класса для функции WP,
        // сделайте что-то подобное
        add_action('admin_menu', [$this, "admin"]);
    }
    
    public function admin() {
        // публичные методы для использования вне класса
        // Обратите внимание, что методы, используемые в других функциях WP
        // (например, add_action), должны быть public
    }
    
    private function somethingelse() {
        // методы, которые используются только внутри этого класса
    }
}

Префикс для всех элементов глобального пространства имён

Плагин должен правильно добавлять префикс ко ВСЕМ элементам глобального пространства имён (константам, функциям, классам, переменным, а также пользовательским таксономиям, типам записей, виджетам и т.д.). Например, не создавайте функцию с именем init(); вместо этого назовите её, например, jpb_init().

Обычно рекомендуется использовать трёх- или четырёхбуквенный префикс перед именами или воспользоваться возможностями пространств имён в PHP. Сравните: Однобуквенные префиксы для констант классов в PHP?

Связанные материалы

• Глобальное пространство имён — ограниченный ресурс

Деактивация не должна приводить к потере данных

Плагин не должен удалять свои данные при деактивации.

Связанные темы

• Удаление должно очищать все данные плагина

Включайте только те файлы, которые вам нужны...

Если вы работаете во фронтенде, не подключайте код, относящийся к административной части.

Предупреждение о потере данных при удалении плагина

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

Связанные темы

• Удаление должно очищать все данные плагина
• Деактивация не должна приводить к потере данных

Разрешить изменение имени папки плагина

/plugins/pluginname/{разные файлы}

Имя "pluginname", используемое для папки, всегда должно быть изменяемым.

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

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

Связанные темы:

• plugins_url() - для простого создания ссылок на ресурсы, включенные в плагин.

Минимизация имен, добавляемых в глобальное пространство имен

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

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

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

Связанные темы

• Правильное использование префиксов

Используйте встроенную в WordPress обработку ошибок

Не просто используйте return;, если какие-то пользовательские данные были неверны. Предоставьте им информацию о том, что было сделано неправильно.

function some_example_fn( $args = array() ) 
{
    // Если значение не было установлено, создаем сообщение об ошибке
    if ( ! isset( $args['some_value'] ) )
        $error = new WP_Error( 'some_value', sprintf( __( 'Вы забыли указать %1$s для вашей функции. %2$s Ошибка вызвана в %3$s на строке %4$s.', TEXTDOMAIN ), '$args[\'some_value\']', "\n", __FILE__, __LINE__ ) );

    // Завершаем выполнение и выводим сообщение об ошибке и код - только для администраторов!
    if ( isset( $error ) && is_wp_error( $error ) && current_user_can( 'manage_options' ) ) 
        wp_die( $error->get_error_code(), 'Ошибка темы: Отсутствует аргумент' );

    // Если ошибка не была вызвана, продолжаем...
}

Один объект ошибки для всех

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

function bootstrap_the_theme()
{
    global $prefix_error, $prefix_theme_name;
    // Используем название темы как ID ошибки:
    $theme_data = wp_get_theme();
    $prefix_theme_name = $theme_data->Name;
    $prefix_error = new WP_Error( $theme_data->Name );

    include // что угодно и т.д...
}
add_action( 'after_setup_theme', 'bootstrap_the_theme' );

Позже вы можете добавлять неограниченное количество ошибок по требованию:

function some_theme_fn( $args )
{
    global $prefix_error, $prefix_theme_name;
    $theme_data = wp_get_theme();
    if ( ! $args['whatever'] && current_user_can( 'manage_options' ) ) // какое-то обязательное значение не установлено
        $prefix_error->add( $prefix_theme_name, sprintf( 'Функции %1$s требуется установленный аргумент %2$s.', __FUNCTION__, '$args[\'whatever\']' ) );

    // продолжаем выполнение функции...
}

Затем вы можете собрать все ошибки в конце работы вашей темы. Таким образом, вы не прерываете отображение страницы, но все равно можете вывести все ошибки для разработки.

function dump_theme_errors()
{
    global $prefix_error, $prefix_theme_name;

    // Не администратор? ИЛИ: Нет ошибок?
    if ( ! current_user_can( 'manage_options' ) ! is_wp_error( $prefix_error ) )
        return;

    $theme_errors = $prefix_error->get_error_messages( $prefix_theme_name );
    echo '<h3>Ошибки темы</h3>';
    foreach ( $theme_errors as $error )
        echo "{$error}\n";
}
add_action( 'shutdown', 'dump_theme_errors' );

Дополнительную информацию вы можете найти в этом вопросе. Связанный тикет для исправления "совместной работы" WP_Error и wp_die() доступен по ссылке, и еще один тикет появится позже. Комментарии, критика и подобное приветствуются.

Используйте Settings API вместо add_option

Вместо добавления опций в базу данных через функцию add_option, вы должны сохранять их в виде массива, используя Settings API, который позаботится обо всём за вас.

Используйте Theme Modifications API вместо add_option

Modifications API — это довольно простой и безопасный способ, позволяющий добавлять и извлекать настройки. Всё сохраняется в базе данных как сериализованное значение. Просто, безопасно и удобно.

Комментирование с использованием PhpDoc

Лучшей практикой считается стиль, близкий к PhpDoc. Если вы не используете IDE, такую как "Eclipse", вы можете просто ознакомиться с руководством по PhpDoc.

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

Защита конфиденциальности пользователей плагинов

(Ранее: Анонимное API-взаимодействие)

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

Размещение плагинов на WordPress.org

Используйте SVN-репозиторий, предоставляемый WordPress.org, для хостинга плагинов. Это обеспечивает более удобный процесс обновления для пользователей. Если вы никогда раньше не работали с SVN, этот опыт поможет вам понять его в контексте, который оправдывает его использование.

Контроль доступа с использованием разрешений

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

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

Организуйте свой код

Всегда трудно читать код, который написан не в порядке его выполнения. Сначала подключайте файлы через include/require, определения (define), wp_enqueue_style и _script и т.д., затем функции, которые нужны плагину/теме, и в конце — код, который строит функционал (например, админ-панель, интеграции с темой и т.п.).

Попробуйте разделять такие вещи, как CSS и JS, в отдельные папки. То же самое сделайте с функциями-помощниками, например, для работы с массивами. Поддержание "главного" файла максимально чистым и читаемым поможет пользователям, разработчикам и вам самим, когда через год вам понадобится обновить код, который вы давно не видели.

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

Импорт / Экспорт настроек плагина

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

Импорт/Экспорт улучшает удобство использования плагина.

Примером плагина, который имеет такую функциональность импорта и экспорта (а также механизм отмены), является Breadcrumb NavXT (Плагин для WordPress) (полное раскрытие: небольшой вклад моего кода там присутствует, основная работа сделана mtekk).

Связанные темы

• Удаление должно очищать все данные плагина
• Деактивация не должна приводить к потере данных

Завершаем с стилем

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

Использование wp_die() также помогает обеспечить совместимость ваших плагинов/тем с тестовым набором WordPress.

• Используйте обработку ошибок в WordPress

Предоставление справочных экранов для пользователей

Лучше сказать "RTFM" (нажмите на справку) в качестве ответа, чем отвечать на один и тот же вопрос снова и снова.

/**
  * Добавление контекстной справки для этого экрана
  * 
  * @param $rtfm
  * @uses get_current_screen
  */ 
  function ContextualHelp( /*string*/ $rtfm) 
  { 
     $current_screen = get_current_screen();
     if ($current_screen->id == $this->_pageid) 
     {
        $rtfm .= '<h3>Плагин WordPress - Экран A</h3>';
        $rtfm .= '<p>Вот несколько советов: пожертвуйте мне ' .
     }
     return $rtfm; 
  }
add_action('contextual_help', array($this,'ContextualHelp'),1,1);

обновление / примечание: (см. комментарии от kaiser): приведенный выше пример предназначен для использования в классе

Предоставляйте расширяемые формы

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

См.: Settings API

Связанные темы

• Используйте Actions и Filters
• Повторное использование существующих функций
• Поддержка I18n

Всегда подключайте функции через хуки, а не напрямую.

Пример:

• Не используйте прямое подключение класса плагина через new без хука

• Используйте хук plugins_loaded

  // добавляем класс в WordPress                                   
  function my_plugin_start() {                                                               
      new my_plugin();   
  }                                                        
  add_action( 'plugins_loaded', 'my_plugin_start' );
  

Обновление: небольшой живой пример: Plugin-svn-trunk-page и псевдо-пример

// избегаем прямых вызовов этого файла, если файлы ядра WP отсутствуют
if (!function_exists ('add_action')) {
        header('Status: 403 Forbidden');
        header('HTTP/1.1 403 Forbidden');
        exit();
}

if ( !class_exists( 'plugin_class' ) ) {
    class plugin_class {

        function __construct() {
        }

    } // конец класса

    function plugin_start() {

        new plugin_class();
    }

    add_action( 'plugins_loaded', 'plugin_start' );
} // конец class_exists

Вы также можете загружать через mu_plugins_loaded на мультисайт-установках, см. справочник по действиям в codex: http://codex.wordpress.org/Plugin_API/Action_Reference Также здесь вы можете увидеть, как подключить WP с этим хуком: http://adambrown.info/p/wp_hooks/hook/plugins_loaded?version=2.1&file=wp-settings.php Я использую это очень часто, и это не так сложно и рано, лучше чем жесткий вызов new class();

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

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

Плагины, лицензированные под GPL-совместимой лицензией

Плагины и темы должны быть лицензированы под лицензией, совместимой с WordPress. Это позволяет распространять их вместе с WordPress как "программу". Рекомендуемая лицензия — GPL. Убедитесь, что все библиотеки кода, включённые в плагин, совместимы с этой же лицензией.

(Это вызывало проблемы и становилось серьёзным предметом споров как в прошлом, так и в настоящем.)

Минимизация побочных эффектов удаленных источников данных и веб-сервисов

Плагин должен кэшировать/защищать веб-сервисы и/или запросы XMLRPC/SOAP через слой кэширования/поставщика данных, если вы их используете, чтобы не заставлять фронтальные запросы ждать (медленного) ответа веб-сервиса.

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

Один из возможных ШАГОВ (на примере публикации в ping.fm): Создаем буферную таблицу, например: ping_fm_buffer_post( date, time, message, submitted_time, status )

1. Каждый раз, когда вы хотите отправить обновление в ping.fm, добавляйте его в эту таблицу.
2. Теперь нам нужно создать плагин для обработки этих данных. Этот плагин будет запускаться через crontab, чтобы проверять каждое еще не отправленное обновление
3. Поскольку у нас есть эта таблица, мы также можем вывести список всех сообщений, отправленных в ping.fm, и проверить статус каждой публикации. В случае проблем на стороне ping.fm мы можем повторно отправить сообщение.

Используйте стандарты кодинга WordPress

http://codex.wordpress.org/WordPress_Coding_Standards

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

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