Как се прави custom WordPress plugin: архитектура, сигурност и реални практики от production среда

Кратък отговор (featured snippet):
Custom WordPress plugin се създава чрез изграждане на самостоятелна PHP структура в /wp-content/plugins/, с ясно дефиниран plugin header, hooks (actions и filters), правилно enqueue-ване на ресурси и спазване на WordPress coding standards. Ключови са сигурността (nonces, sanitization), производителността и избягването на конфликт с темата или други плъгини.

---

WordPress позволява почти всичко. Въпросът е къде да имплементирате логиката си – в темата или в плъгин.

Когато функционалността не е свързана с визуалния слой, правилният подход е custom plugin. Това е архитектурно решение, което гарантира мащабируемост, лесна поддръжка и независимост от темата.

В тази статия ще разгледаме:

• Кога има смисъл да се пише custom plugin
• Как изглежда правилната структура
• Как да използвате hooks, shortcodes и REST API
• Как да избегнете най-честите грешки
• Реален production казус

---

Кога ви трябва custom WordPress plugin (а не код в темата)

Типични случаи:

• Интеграция с външен API (ERP, CRM, платежни системи)
• Custom Post Types и специфична бизнес логика
• Административни панели и настройки
• Background процеси (cron jobs)
• REST endpoints
• Разширяване на WooCommerce

Златното правило:
Ако функционалността трябва да остане активна дори при смяна на темата — тя принадлежи в plugin.

---

Минимална структура на custom WP plugin

Всеки WordPress plugin започва с директория в:

/wp-content/plugins/my-custom-plugin/

И основен PHP файл, например:

my-custom-plugin.php

Примерен plugin header:

<?php
/**
 * Plugin Name: Balev Custom Tools
 * Description: Custom business logic for project X.
 * Version: 1.0.0
 * Author: Balev Dev
 */

Това е задължително. WordPress разчита на този header за регистрация.

---

Архитектура: как да не пишете procedural spaghetti

В production среда не се пише всичко в един файл.

Добра практика:

my-custom-plugin/
│
├── my-custom-plugin.php
├── includes/
│   ├── class-loader.php
│   ├── class-admin.php
│   ├── class-public.php
│
├── assets/
│   ├── css/
│   ├── js/

Използвайте класове и autoload логика.

Минимален loader пример:

require_once plugin_dir_path(__FILE__) . 'includes/class-admin.php';
require_once plugin_dir_path(__FILE__) . 'includes/class-public.php';

---

Hooks: гръбнакът на WordPress

WordPress работи чрез actions и filters.

Action пример:

add_action('init', 'register_custom_post_type');

Filter пример:

add_filter('the_content', 'modify_content');

Разликата:

• Action изпълнява код
• Filter модифицира стойност и я връща

Ако не разбирате hooks добре, не трябва да пишете custom plugin.

---

Регистрация на Custom Post Type в plugin

function register_projects_cpt() {
    register_post_type('project', [
        'label' => 'Projects',
        'public' => true,
        'supports' => ['title', 'editor', 'thumbnail'],
        'show_in_rest' => true
    ]);
}

add_action('init', 'register_projects_cpt');

Важно:
show_in_rest => true позволява Gutenberg и REST API съвместимост.

---

Добавяне на admin настройки

Правилният начин:

add_action('admin_menu', function() {
    add_options_page(
        'Plugin Settings',
        'Plugin Settings',
        'manage_options',
        'plugin-settings',
        'plugin_settings_page'
    );
});

Винаги валидирайте входните данни.

---

Сигурност: къде повечето разработчици грешат

Никога не:

• Използвайте $_POST директно
• Изкарвайте данни без escaping
• Записвайте опции без sanitization

Пример:

$value = sanitize_text_field($_POST['custom_field']);
update_option('custom_option', $value);

Nonce защита:

wp_nonce_field('save_data_action', 'save_data_nonce');

И проверка:

if (!wp_verify_nonce($_POST['save_data_nonce'], 'save_data_action')) {
    return;
}

---

Зареждане на CSS и JS правилно (enqueue)

Грешно:

echo '<script src="script.js"></script>';

Правилно:

add_action('wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'custom-script',
        plugin_dir_url(__FILE__) . 'assets/js/script.js',
        ['jquery'],
        '1.0.0',
        true
    );
});

Това предотвратява конфликти и дублиране.

---

Plugin vs Theme Code

Критерий	Plugin	Theme
Смяна на темата	Запазва функционалността	Губи се
Бизнес логика	Да	Не е препоръчително
Визуални промени	Не	Да
REST API разширения	Да	Не
Cron задачи	Да	Не

Обобщение:
Всичко, което е част от бизнес процеса, трябва да бъде в plugin.

---

Реален казус: ERP интеграция за eCommerce

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

• Автоматична синхронизация на наличности
• Синхронизация на поръчки
• Логиране на грешки
• Retry механизъм

Решението:

• Custom plugin
• WP Cron за периодични заявки
• REST endpoint за inbound заявки
• Custom admin страница за логове

Резултат:

• 0 зависимост от темата
• Без конфликт с WooCommerce
• Лесен debugging
• Миграция към нова тема без промяна в интеграцията

---

Често допускани грешки

1. Писане на бизнес логика в functions.php
2. Липса на namespace
3. Липса на versioning
4. Липса на error logging
5. Прекалено много глобални функции
6. Игнориране на WordPress Coding Standards
7. Неправилна REST authentication логика

---

Разширени възможности

Custom plugin може да включва:

• REST API endpoints
• Custom Gutenberg blocks
• CLI команди (WP-CLI)
• Background processing
• Queue система
• WooCommerce hooks
• Multisite съвместимост
• WPML интеграция

При по-сложни проекти се използва dependency injection и OOP архитектура.

---

Q&A: Какво най-често питат разработчиците

Трябва ли ми OOP за custom plugin?

Не е задължително, но при средни и големи проекти е препоръчително.

Мога ли да използвам Composer?

Да, особено при външни библиотеки. Нужно е правилно autoload конфигуриране.

Plugin или must-use plugin?

MU-plugin е подходящ при критична логика, която не трябва да се деактивира.

Как се update-ва custom plugin?

Чрез versioning и manual deployment или private repository система.

Безопасно ли е да се работи директно в production?

Не. Използвайте staging среда.

---

Индустриални наблюдения

В 70% от проектите, които изискват рефакторинг, проблемът идва от:

• Логика в темата
• Липса на архитектура
• Неправилно използване на hooks
• Липса на logging

Custom plugin не е просто файл с код.
Това е архитектурно решение.

---

Финално експертно обобщение

Custom WordPress plugin е правилният начин да изградите устойчива, независима и мащабируема функционалност. Архитектурата трябва да бъде ясна, сигурността – приоритет, а кодът – организиран и стандартизиран. При сериозни проекти плъгинът се превръща в отделен софтуерен слой, който може да се развива независимо от темата.

Custom WordPress plugin позволява отделяне на бизнес логиката от визуалния слой. Той се създава чрез структурирана PHP директория с дефиниран header и използване на hooks. Ключови са сигурността, правилното enqueue-ване и валидирането на входни данни. При по-сложни проекти се използва OOP архитектура и REST API разширения. Това гарантира мащабируемост, по-лесна поддръжка и независимост от темата.