Запуск вікі спільноти для збору об'єктивних кращих практик для розробки плагінів. Це питання було натхнене коментарями @ 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дії, щоб користувач міг підключитися до дії.

Дивіться Codex: I18n для розробників WordPress

А також ця стаття: Правильно завантажуйте файли мови WP .

Оскільки WordPress 4.6+

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

Розглядаючи плагін із текстовим доменом "мій плагін", WordPress ПЕРШИЙ шукатиме файл перекладу у:
/wp-content/languages/plugins/my-plugin-en_US.mo

Якщо він не знайде його там, він шукатиме той, де плагін повідомляє його шукати (як правило, у папці "мова" плагінів, якщо слідує за кодексом):
/ wp-content / plugins / my-plugin / languages ​​/ my- plugin-en_US.mo

Нарешті, якщо не знайдено жодного мовного файлу, він перевірить розташування за замовчуванням:
/wp-content/languages/my-plugin-en_US.mo

Перша перевірка була додана в 4.6 і надає користувачам певне місце для додавання мовного файлу, так як раніше вони повинні були знати, де розробник додав мовний файл, тепер користувач просто повинен знати textdomain плагіна: / wp-content / мови / плагіни / TEXTDOMAIN-LOCAL.mo

Нижче наведено старий спосіб (Не актуально з WP 4.6+)

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

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 Core

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

Одна з переваг полягає в тому, що ви можете використовувати "застарілі повідомлення", щоб легко контролювати функції, які слід замінити. Ще однією перевагою є те, що користувачі можуть переглядати документацію щодо функцій у Codex та краще зрозуміти, що робить плагін, навіть якщо вони не є досвідченим розробником 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). Звичайно, ви можете встановити префікс усіх своїх імен функцій, щоб вони закінчилися безмежно_довгими_функціями_іменами_з_літками_короткими, але набагато простіше просто написати простий клас і зв’язати все в цьому. Крім того, помістіть свій клас у окремий файл і назви його відповідно, щоб ви могли легко розширити і підтримувати його:

// 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.)

Пов'язані

• Видалення має видалити всі дані плагіна
• Деактивація не повинна спричиняти втрату даних

Нехай змінено ім’я папки плагіна

/ плагіни / ім'я плагіна / {різні}

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

Зазвичай це обробляється шляхом визначення констант і послідовного їх використання у всьому плагіні.

Зайве говорити, що багато популярних плагінів є грішниками.

Пов'язані:

• 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 Plugin) (повне розкриття: якийсь менший код у мене там, більшість зроблено mtekk).

Пов'язані

• Видалення має видалити всі дані плагіна
• Деактивація не повинна провокувати втрату даних

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

Завжди важко читати код, який не записаний у тому порядку, який він виконується. Спочатку включайте / вимагайте, визначте, 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);

оновлення / примітка: (див. коментарі від кайзера): вищевказаний приклад має бути використаний у класі

Пропонуємо розширені форми

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

Див.: API налаштувань

Пов'язані

• Використовуйте дії та фільтри
• Повторно використовуйте існуючі функції
• Підтримка I18n

включайте функцію завжди через гачок, а не безпосередньо.

Приклад:

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

• Використовуйте завантажені додатки Hook

  // 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 на мультисайтовій установці, див. Код для довідки про дії: 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 рекомендованих плагінів для публікацій. Усі вони відображають популярні публікації, проте багато хто мають різні функції. Слід порівняти ваш плагін із подібними плагінами, прочитавши опис.

Вам слід уникати хвастощів щодо того, наскільки простий ваш плагін, якщо він дійсно не є основним. Ви повинні включити в опис корисні посилання, як-от посилання на налаштування.

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

Плагін повинен кешувати / захищати веб-сервіс та / або XMLRPC / SOAP запити через рівень кешування / постачальника даних, якщо ви використовуєте їх так, щоб не робити запитів на фронт, які чекають (повільного) відповіді веб-сервісу.

Це включає завантаження каналу RSS та інших сторінок. Створіть свої плагіни, щоб вони вимагали даних у фоновому режимі.

Один з можливих КРОКів (Візьміть допис на ping.fm як приклад): Створіть буферну таблицю, скажімо: ping_fm_buffer_post (дата, час, повідомлення, відправлений_час, статус)

1. Щоразу, коли ви бажаєте надіслати оновлення до ping.fm, додайте його до цієї таблиці.
2. Тепер нам потрібно створити плагін для обробки цих даних. Цей плагін працюватиме через crontab, щоб перевірити, чи не оновлено ще оновлення
3. Оскільки у нас є ця таблиця, ми також можемо перерахувати кожне повідомлення, подане на ping.fm, і перевірити стан кожної публікації. На випадок, якщо на стороні ping.fm є проблеми, ми можемо повторно надіслати її.

Перевірте свій плагін

Ми повинні остаточно мати деякі інструменти тестування в нашому середовищі розробки плагінів.

На підставі цієї відповіді по Етану Зейферт на тестування питання, це хороші практики , щоб слідувати:

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