Создание сообщества вики для сбора объективных лучших практик по разработке плагинов. Этот вопрос был вдохновлен комментариями @ EAMann к wp-хакерам .

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

ОБНОВЛЕНИЕ: После просмотра первых нескольких ответов становится ясно, что нам нужно иметь только одну идею / предложение / наилучшую практику для каждого ответа, и люди должны просмотреть список, чтобы убедиться в отсутствии дубликатов перед публикацией.

Используйте действия и фильтры

Если вы думаете, что люди хотели бы добавить или изменить некоторые данные: предоставьте apply_filters () перед возвратом .

PS Одна вещь, которую я нахожу немного разочаровывающей, это то, что ваши вопросы адресованы процентным соотношением плагинов, которые предназначены только для конечных пользователей, то есть не имеют собственных хуков. Представляете, если WordPress были разработаны как большинство плагинов? Это было бы негибким и очень нишевым решением.

Может быть, все было бы иначе, если бы у WordPress была возможность автоматически устанавливать плагины, от которых зависели другие плагины? Поскольку мне обычно приходится писать много функций, которые мне нужны, с нуля, потому что клиенты хотят, чтобы вещи были определенным образом, а доступные плагины, в то время как 90% там, не позволяют мне гибко обновлять оставшиеся 10%.

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

Давайте возьмем пример из другого вопроса :

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

Связанный

• Предлагаем расширяемые формы

Загрузить сценарии / CSS с помощью wp_enqueue_scriptиwp_enqueue_style

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

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

Связанный

• Повторно использовать существующие функции

Поддержка I18n

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

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

См. Кодекс: I18n для разработчиков WordPress.

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

Начиная с WordPress 4.6+

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

Учитывая плагин с текстовым доменом «my-plugin», WordPress теперь ПЕРВЫЙ будет искать файл перевода в:
/wp-content/languages/plugins/my-plugin-en_US.mo

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

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

Первая проверка была добавлена ​​в 4.6 и дает пользователям определенное место для добавления языкового файла, так как раньше им нужно было знать, куда разработчик добавил языковой файл, теперь пользователю просто нужно знать текстовый домен плагина: / wp-content / языки / плагины / TEXTDOMAIN-LOCAL.mo

Ниже приведен старый способ (не относится к WP 4.6+)

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

public function load_plugin_textdomain()
{
    $domain = 'my-plugin';
    // The "plugin_locale" filter is also used in 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 отсутствует соответствующая функция.

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

Связанный

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

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

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

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

Связанный

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

Предотвращение внедрения SQL с входными данными

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

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

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

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

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

Связанный

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

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

Нет причин не писать чистый объектно-ориентированный код PHP5. Поддержка PHP4 будет прекращена после следующего выпуска (WP 3.1). Конечно, вы можете добавить к именам всех ваших функций префикс endlessly_long_function_names_with_lots_of_underscores, но гораздо проще просто написать простой класс и связать все в нем. Кроме того, поместите ваш класс в отдельный файл и назовите его соответствующим образом, чтобы вы могли легко расширять и поддерживать его:

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

// in inc/class-my-cool-plugin.php
class MyCoolPlugin {
    function __construct() {
        // add filter hooks, wp_enqueue_script, etc.

        // To assign a method from your class to a WP 
        // function do something like this
        add_action('admin_menu', array($this, "admin"));
    }

    public function admin() {
        // public methods, for use outside of the class
        // Note that methods used in other WP functions 
        // (such as add_action) should be public
    }

    private function somethingelse() {
        // methods you only use inside this class
    }
}

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

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

Связанный

• Деинсталляция должна удалить все данные плагина

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

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

Объявляем о потере данных при удалении плагина

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

Связанный

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

Пусть имя папки плагина будет изменено

/ плагинов / pluginname / {} различные

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

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

Излишне говорить, что многие популярные плагины являются грешниками.

Связанный:

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

Использовать WordPress (встроенный) Обработка ошибок

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

function some_example_fn( $args = array() ) 
{
    // If value was not set, build an error message
    if ( ! isset( $args['some_value'] ) )
        $error = new WP_Error( 'some_value', sprintf( __( 'You have forgotten to specify the %1$s for your function. %2$s Error triggered inside %3$s on line %4$s.', TEXTDOMAIN ), '$args[\'some_value\']', "\n", __FILE__, __LINE__ ) );

    // die & print error message & code - for admins only!
    if ( isset( $error ) && is_wp_error( $error ) && current_user_can( 'manage_options' ) ) 
        wp_die( $error->get_error_code(), 'Theme Error: Missing Argument' );

    // Elseif no error was triggered continue...
}

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

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

function bootstrap_the_theme()
{
    global $prefix_error, $prefix_theme_name;
    // Take the theme name as error ID:
    $theme_data = wp_get_theme();
    $prefix_theme_name = $theme_data->Name;
    $prefix_error = new WP_Error( $theme_data->Name );

    include // whatever, etc...
}
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' ) ) // some required value not set
        $prefix_error->add( $prefix_theme_name, sprintf( 'The function %1$s needs the argument %2$s set.', __FUNCTION__, '$args[\'whatever\']' ) );

    // continue function...
}

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

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

    // Not an admin? OR: No error(s)?
    if ( ! current_user_can( 'manage_options' ) ! is_wp_error( $prefix_error ) )
        return;

    $theme_errors = $prefix_error->get_error_messages( $prefix_theme_name );
    echo '<h3>Theme Errors</h3>';
    foreach ( $theme_errors as $error )
        echo "{$error}\n";
}
add_action( 'shutdown', 'dump_theme_errors' );

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

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

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

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

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

Связанный

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

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

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

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

Используйте API настроек перед add_option

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

Используйте API Модификации Темы перед add_option

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

Защита пользователей плагинов

(Ранее: анонимный API-интерфейс)

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

Размещать плагины на WordPress.org

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

Обеспечить контроль доступа с помощью разрешений

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

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

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

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

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

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

Связанный

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

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

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

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

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

Умри со стилем

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

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

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

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

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

/**
  * Add contextual help for this screen
  * 
  * @param $rtfm
  * @uses get_current_screen
  */ 
  function ContextualHelp( /*string*/ $rtfm) 
  { 
     $current_screen = get_current_screen();
     if ($current_screen->id == $this->_pageid) 
     {
        $rtfm .= '<h3>The WordPress Plugin - Screen A</h3>';
        $rtfm .= '<p>Here are some tips: donate to me ' .
     }
     return $rtfm; 
  }
add_action('contextual_help', array($this,'ContextualHelp'),1,1);

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

Предлагаем расширяемые формы

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

Смотрите: Настройки API

Связанный

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

включать функцию всегда через Hook, а не напрямую.

Пример:

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

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

  // add the class to WP                                   
  function my_plugin_start() {                                                               
      new my_plugin();   
  }                                                        
  add_action( 'plugins_loaded', 'my_plugin_start' );

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

//avoid direct calls to this file where wp core files not present
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() {
        }

    } // end class

    function plugin_start() {

        new plugin_class();
    }

    add_action( 'plugins_loaded', 'plugin_start' );
} // end class_exists

Вы также можете загрузить с помощью mu_plugins_loaded на multisite-install, см. Справочник кодекса действий: 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 Я использую это очень часто, и это не так сложно и рано, лучше, чем жесткий новый класс ();

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

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

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

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

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

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

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

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

Один из возможных ШАГОВ (Возьмите в качестве примера публикацию на ping.fm): создайте буферную таблицу, скажем: ping_fm_buffer_post (дата, время, сообщение, submit_time, status)

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

Проверьте свой плагин

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

На основании этого ответа по Этану Зейферт на тестирование вопрос, это хорошие практики , чтобы следовать:

• Ваше модульное тестирование должно проверять наименьшее количество поведения, которое может выполнить класс.
• Когда вы дойдете до уровня функционального тестирования, вы сможете протестировать свой код с зависимостями Wordpress.
• В зависимости от того, что делает ваш плагин - рассмотрите возможность использования тестов на основе Selenium, которые проверяют наличие данных в DOM с помощью идентификаторов