کدنویسی اختصاصی افزونهٔ وردپرس، مرز بین «کاربر وردپرس» و «توسعه‌دهندهٔ وردپرس» است. تجربه‌ام: زمانی که یک توسعه‌دهنده اولین افزونهٔ جدی خودش را می‌نویسد، دیدگاهش نسبت به وردپرس کامل عوض می‌شود — از «مجموعه‌ای از تنظیمات» به «یک پلتفرم قابل برنامه‌ریزی». این مقاله، چارچوب کدنویسی اختصاصی افزونه را از پایه باز می‌کند: از تعریف نیاز تا ساختار، امنیت، تست، و انتشار. تمرکزش نه بر تئوری، بر الگوهایی است که در پروژه‌های واقعی استفاده می‌کنم. اگر با مفاهیم پایه آشنا نیستید، افزونهٔ وردپرس چیست، توسعهٔ افزونه از صفر، و شروع اصولی کدنویسی را پیش از ادامه ببینید.

قبل از کد: پنج سؤال تصمیم

پیش از شروع، پنج سؤال را پاسخ دهید: یک — آیا افزونهٔ آماده‌ای برای این نیاز وجود دارد؟ اول جستجو کنید. دو — آیا این قابلیت، عمومی است یا اختصاصی؟ اگر عمومی است، افزونهٔ آماده بهتر از اختصاصی. سه — آیا این قابلیت منطقی است یا ظاهری؟ اگر ظاهری است، چایلد تم کافی است. چهار — آیا این افزونه باید قابل انتشار باشد؟ اگر بله، ساختار و مستندسازی حرفه‌ای‌تر لازم است. پنج — چه کسی این افزونه را نگهداری می‌کند؟ خودتان، تیم، یا مشتری — پاسخ، سطح مستندسازی را تعیین می‌کند. تجربه‌ام: پاسخ به این پنج سؤال، در ۸۰٪ موارد، تصمیم «افزونهٔ اختصاصی بنویسیم یا نه» را روشن می‌کند. اگر پاسخ‌ها به «افزونهٔ آماده» می‌رسد، از نوشتن افزونهٔ اختصاصی پرهیز کنید. الگوی تفکیک در افزودن قابلیت به وردپرس و راهنمای انتخاب افزونه.

افزونهٔ اختصاصی، دارایی است؛ افزونهٔ اختصاصیِ بی‌دلیل، بدهی است. تفاوت این دو، در پاسخ به پنج سؤال بالا مشخص می‌شود.

چه زمانی افزونهٔ اختصاصی بنویسیم؟

پنج سناریوی واضح: یک — نیاز اختصاصی کسب‌وکار. مثال: محاسبه‌گر قیمت خاص، اتصال به CRM داخلی. دو — یکپارچگی با سیستم درون‌سازمانی. مثال: پل بین سایت و ERP شرکت. سه — قابلیت منطقی که نباید به قالب وابسته باشد. مثال: سیستم امتیازدهی کاربران. چهار — عملکرد بهینه. مثال: جایگزینی یک افزونهٔ سنگین بازار با نسخهٔ سبک اختصاصی. پنج — انتشار تجاری. مثال: ساخت افزونه برای فروش. الگوی گام‌به‌گام در مراحل ساخت افزونهٔ اختصاصی و توسعهٔ افزونه از صفر. تجربه‌ام: در پروژه‌ای که سه افزونهٔ بازار روی هم انباشته بود، بازنویسی به یک افزونهٔ اختصاصی سبک، بار سایت را ۳۰٪ کاهش داد.

ساختار استاندارد افزونهٔ اختصاصی

ساختار پیشنهادی:

my-plugin/
├── my-plugin.php           # فایل اصلی با هدر
├── uninstall.php           # پاک‌سازی هنگام حذف
├── readme.txt
├── includes/
│   ├── class-loader.php
│   ├── class-activator.php
│   ├── class-deactivator.php
│   ├── class-my-plugin.php
│   └── functions.php
├── admin/
│   ├── class-admin.php
│   ├── css/
│   ├── js/
│   └── views/
│       └── settings-page.php
├── public/
│   ├── class-public.php
│   ├── css/
│   └── js/
└── languages/
    └── my-plugin.pot

جداسازی admin از public، یکی از مهم‌ترین الگوهاست: در پیشخوان، CSS و JS فرانت‌اند لود نمی‌شود و برعکس. راهنمای کامل در ساختار فایل‌های افزونهٔ استاندارد. فایل اصلی، فقط bootstrap است — نه پر از کد:

<?php
/**
 * Plugin Name: My Plugin
 * Version: 1.0.0
 * Requires PHP: 7.4
 * Text Domain: my-plugin
 */

if ( ! defined( 'ABSPATH' ) ) exit;

require_once __DIR__ . '/includes/class-my-plugin.php';
My_Plugin::instance();

نکته: ABSPATH، جلوگیری از دسترسی مستقیم به فایل PHP. تجربه‌ام: نبود این خط، در پرونده‌های امنیتی متعدد دیده‌ام. الگوی کامل در PHP امن در وردپرس.

هوک‌ها و Registry Pattern

هوک‌ها، ستون فقرات افزونه‌اند. الگوی حرفه‌ای: همهٔ هوک‌ها را در یک نقطه ثبت کنید:

class My_Plugin_Loader {
    protected $actions = array();
    protected $filters = array();

    public function add_action( $hook, $component, $callback, $priority = 10, $args = 1 ) {
        $this->actions[] = compact( 'hook', 'component', 'callback', 'priority', 'args' );
    }

    public function add_filter( $hook, $component, $callback, $priority = 10, $args = 1 ) {
        $this->filters[] = compact( 'hook', 'component', 'callback', 'priority', 'args' );
    }

    public function run() {
        foreach ( $this->filters as $f ) {
            add_filter( $f['hook'], array( $f['component'], $f['callback'] ), $f['priority'], $f['args'] );
        }
        foreach ( $this->actions as $a ) {
            add_action( $a['hook'], array( $a['component'], $a['callback'] ), $a['priority'], $a['args'] );
        }
    }
}

مزیت: تمام نقاط اتصال در یک نگاه، امکان تست و بازبینی. تجربه‌ام: در پروژه‌ای با ۶۰ هوک پراکنده، انتقال به این الگو، زمان دیباگ را نصف کرد. راهنمای هوک‌ها در هوک‌های وردپرس، تفاوت اکشن و فیلتر، و کنترل ترتیب اجرا.

صفحهٔ تنظیمات و پیشخوان

افزونهٔ جدی، صفحهٔ تنظیمات دارد. استفاده از Settings API، استاندارد رسمی:

function my_plugin_register_settings() {
    register_setting( 'my_plugin_group', 'my_plugin_options', array(
        'type' => 'array',
        'sanitize_callback' => 'my_plugin_sanitize',
    ) );
    add_settings_section( 'general', 'تنظیمات عمومی', null, 'my-plugin' );
    add_settings_field( 'api_key', 'کلید API', 'my_plugin_field_api_key', 'my-plugin', 'general' );
}
add_action( 'admin_init', 'my_plugin_register_settings' );

راهنمای کامل در ساخت صفحهٔ تنظیمات اختصاصی و ساخت منوی مدیریتی. مزیت Settings API: nonce، sanitize، و ذخیرهٔ منظم در wp_options خودکار انجام می‌شود.

شورت‌کد، ویجت، متاباکس

سه راه افزودن قابلیت به محتوا: یک — شورت‌کد: کد کوتاه در محتوا. الگو در ساخت شورت‌کد. دو — ویجت: بلوک قابل تنظیم در sidebar. الگو در ساخت ویجت اختصاصی. سه — متاباکس: فیلد اضافی در صفحهٔ ویرایش. الگو در کار با متاباکس‌ها. توصیه: انتخاب بین این سه، به UX بستگی دارد، نه به راحتی کدنویسی. مثال شورت‌کد:

function my_plugin_shortcode( $atts ) {
    $atts = shortcode_atts( array(
        'title' => '',
        'count' => 5,
    ), $atts, 'my_list' );

    $output = '<div class="my-list">';
    $output .= '<h3>' . esc_html( $atts['title'] ) . '</h3>';
    $output .= '</div>';
    return $output;
}
add_shortcode( 'my_list', 'my_plugin_shortcode' );

نکته: همیشه shortcode_atts برای مقادیر پیش‌فرض و esc_html برای خروجی. الگوهای امنیتی در پاک‌سازی داده‌ها.

REST API و endpoint اختصاصی

افزونهٔ مدرن، endpoint سفارشی دارد. الگو:

add_action( 'rest_api_init', function() {
    register_rest_route( 'my-plugin/v1', '/items', array(
        'methods' => 'GET',
        'callback' => 'my_plugin_get_items',
        'permission_callback' => function() {
            return current_user_can( 'read' );
        },
    ) );
} );

راهنمای کامل در ساخت API اختصاصی و REST API وردپرس. نکتهٔ حیاتی: permission_callback هرگز خالی نباشد. الگوی امنیتی در PHP امن در وردپرس.

امنیت در افزونهٔ اختصاصی

پنج قاعدهٔ الزامی: یک — ABSPATH در ابتدای هر فایل PHP. دو — پاک‌سازی ورودی. sanitize_text_field، absint، esc_url_raw. سه — escape خروجی. esc_html، esc_attr، esc_url. چهار — nonce و check_user_can در هر فرم و AJAX. پنج — آماده‌سازی کوئری. $wpdb->prepare. راهنمای کامل در PHP امن در وردپرس، پاک‌سازی داده‌ها، اعتبارسنجی داده‌ها، و نانس وردپرس. تجربه‌ام: رعایت همین پنج قاعده، ۹۰٪ آسیب‌پذیری‌های افزونه را حذف می‌کند. اصول کلی امنیت پروژه در امنیت پروژهٔ وردپرس.

تست افزونه

سه سطح تست: یک — Unit Test با PHPUnit. برای توابع منطقی. دو — Integration Test با WP_UnitTestCase. برای تعامل با هستهٔ وردپرس. سه — E2E با Playwright. برای جریان‌های کاربری. الگوی کامل در تست و دیباگ پروژه‌های وردپرس. نمونهٔ Unit Test:

class My_Plugin_Test extends WP_UnitTestCase {
    public function test_shortcode_output() {
        $output = do_shortcode( '[my_list title="Test"]' );
        $this->assertStringContainsString( 'Test', $output );
    }
}

نکته: تست افزونه، از روز اول شروع شود. تجربه‌ام: در افزونه‌ای که از ابتدا تست داشت، در پنج آپدیت بزرگ، حتی یک باگ در Production نداشتیم. CI/CD در CI/CD در وردپرس.

انتشار و به‌روزرسانی

سه مسیر انتشار: یک — مخزن رسمی وردپرس. رایگان، با بازبینی تیم امنیتی. مناسب افزونه‌های عمومی. دو — سایت خودتان. با لایسنس و سیستم به‌روزرسانی. مناسب افزونه‌های تجاری. سه — خصوصی، فقط برای مشتری. بدون انتشار عمومی. برای به‌روزرسانی، سه ابزار: یک — GitHub + Plugin Update Checker. دو — سرور لایسنس اختصاصی. سه — مخزن رسمی. راهنمای بکاپ پیش از هر انتشار در افزونه‌های بکاپ. مزایا و معایب رایگان/پولی در افزونهٔ رایگان یا پولی.

دید مهندسی: معماری افزونهٔ حرفه‌ای

برای توسعه‌دهنده‌های سطح بالا، سه الگوی پیشرفته در افزونه‌نویسی: یک — Dependency Injection ساده. به‌جای دسترسی مستقیم به سرویس‌ها، آن‌ها را به constructor پاس دهید. این کار، تست را ساده‌تر و وابستگی‌ها را شفاف‌تر می‌کند. دو — Service Container. در افزونه‌های بزرگ، یک Container سبک که تمام سرویس‌ها را نگه می‌دارد، جایگزین متغیرهای سراسری می‌شود. سه — Event Dispatcher. در کنار هوک‌های وردپرس، یک dispatcher داخلی برای رویدادهای اختصاصی افزونه، امکان جداسازی ماژول‌ها را می‌دهد. تجربه‌ام: در پروژه‌ای با پنج ماژول داخلی، انتقال از procedural به این الگو، زمان اضافه‌کردن هر ماژول جدید را از دو هفته به دو روز کاهش داد. الگوهای استاندارد کد در استانداردهای کدنویسی و پیاده‌سازی استانداردها آمده است. یک نکتهٔ معماری در مورد افزونه‌های بزرگ: منطق کسب‌وکار را از لایهٔ WordPress API جدا کنید. این جداسازی، افزونه را قابل حمل‌تر و تست‌پذیرتر می‌کند. اگر روزی وردپرس را ترک کردید، منطق شما با کمترین تغییر به پلتفرم دیگر منتقل می‌شود. این اصل، در پروژه‌های سازمانی که به پایداری بلندمدت اهمیت می‌دهند، استاندارد است.

اشتباهات رایج

جمع‌بندی

کدنویسی اختصاصی افزونهٔ وردپرس، ده گام دارد: تعریف نیاز، ساختار استاندارد، هوک‌ها و Registry، صفحهٔ تنظیمات، شورت‌کد/ویجت/متاباکس، REST API، امنیت، تست، و انتشار. قاعدهٔ طلایی: پیش از نوشتن افزونهٔ اختصاصی، پنج سؤال تصمیم را پاسخ دهید. اگر امروز فقط یک کار می‌کنید: یک افزونهٔ سادهٔ «hello world» بسازید که یک پیام به فوتر اضافه کند و آن را در GitHub بگذارید. تجربهٔ خودتان از نوشتن اولین افزونه، در دیدگاه‌ها ارزشمند است. 🔌