راهنمای توسعه افزونه وردپرس از صفر

ساخت افزونهٔ وردپرس، برخلاف آنچه در نگاه اول به نظر می‌رسد، برای شروع ساده است — ساده‌تر از ساخت یک قالب از صفر. علتش این است که افزونه، همان‌طور که در افزونه وردپرس چیست توضیح داده‌ام، یک بستهٔ مستقل است که با هوک‌ها به هسته وصل می‌شود؛ نیازی نیست ساختار بصری و template hierarchy را یک‌جا پیاده کنید. تجربه‌ام: اولین افزونهٔ جدی هر توسعه‌دهنده، معمولاً یک شورت‌کد ساده یا یک تغییر کوچک در پیشخوان است. همین شروع کوچک، دروازهٔ ورود به دنیای حرفه‌ای افزونه‌نویسی می‌شود. این مقاله، نقشهٔ گام‌به‌گام آن مسیر است. اگر با مفاهیم پایه آشنا نیستید، توسعهٔ وردپرس چیست و ساختار هستهٔ وردپرس را ببینید.

پیش‌نیازها

پیش از کدنویسی، سه پیش‌نیاز: یک — PHP در سطح متوسط. تسلط روی کلاس، ارث‌بری، و کار با آرایه‌های چندبعدی الزامی است. منابع در آموزش PHP از صفر و شی‌گرایی در PHP. دو — درک هوک‌ها. بدون این، افزونه‌نویسی غیرممکن است. راهنمای کامل در هوک‌های وردپرس. سه — محیط توسعهٔ محلی. روش در توسعه با محیط لوکال.

حداقل فایل‌های افزونه

یک افزونهٔ وردپرس، حداقل یک فایل PHP لازم دارد. کوچک‌ترین افزونهٔ معتبر:

<?php
/*
Plugin Name: Hello WordPressKar
Description: یک افزونهٔ نمونه که یک پیام کوتاه به فوتر اضافه می‌کند.
Version: 1.0.0
Author: WordPressKar
License: GPL-2.0-or-later
Text Domain: hello-wordpresskar
*/

function wpk_footer_message() {
    echo '<p>ساخته‌شده با ❤️ در WordPressKar</p>';
}
add_action( 'wp_footer', 'wpk_footer_message' );

این کد، یک افزونهٔ کامل است. کاری که می‌کند: یک تابع تعریف می‌کند و آن را به هوک wp_footer وصل می‌کند. همین سادگی، قدرت افزونه‌نویسی در وردپرس است. تجربه‌ام: هر توسعه‌دهنده‌ای که از این مرحله شروع کرده، حداکثر در یک هفته، به افزونه‌های متوسط رسیده است. فایل را در مسیر wp-content/plugins/hello-wordpresskar/ قرار دهید و از پیشخوان فعالش کنید.

افزونه‌نویسی وردپرس، مثل لِگو بازی کردن است: قطعات کوچک را روی هم می‌گذارید تا یک ساختار پیچیده ساخته شود. هر هوک، یک قطعهٔ لِگوست.

هدر افزونه

هدر افزونه، اطلاعات شناسنامه‌ای است که وردپرس برای نمایش در پیشخوان می‌خواند. حداقلِ لازم: Plugin Name. ولی برای افزونهٔ جدی، این فیلدها را اضافه کنید: Description، Version، Author، License، Text Domain، Requires at least (نسخهٔ وردپرس)، Requires PHP (نسخهٔ PHP). الگوی دقیق و فیلدهای اختیاری در ساختار فایل‌های افزونهٔ استاندارد. تجربه‌ام: بدون این هدرها، افزونهٔ شما از نظر استاندارد رد می‌شود — حتی اگر کار کند.

هوک‌ها و نقاط اتصال

هوک‌ها، ستون فقرات هر افزونه‌اند. دو نوع اصلی: add_action برای اجرای یک کار در لحظهٔ مشخص، add_filter برای تغییر داده‌ها. هوک‌های پرکاربرد در افزونه‌نویسی: init (ثبت شورت‌کد، post type، taxonomy)، wp_enqueue_scripts (لود asset در front-end)، admin_menu (منوی پیشخوان)، the_content (فیلتر محتوا)، save_post (ذخیرهٔ نوشته). الگوهای دقیق در استفادهٔ درست از هوک‌ها، تفاوت اکشن و فیلتر، و کنترل ترتیب اجرای هوک‌ها. الگوی حرفه‌ای: تمام hookها را در یک کلاس Registry ثبت کنید، نه پراکنده در فایل‌ها.

ساختار پوشه‌ها و فایل‌ها

افزونهٔ ساده، یک فایل کافی است. افزونهٔ حرفه‌ای، ساختار دارد:

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

الگوی کامل و مسئولیت هر پوشه در ساختار فایل‌های افزونهٔ استاندارد. نکتهٔ کلیدی: جدا کردن منطق پیشخوان از front-end. این جداسازی، هم سرعت را بهبود می‌دهد (assetهای front-end در پیشخوان لود نمی‌شوند) و هم نگهداری را ساده‌تر می‌کند.

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

افزونهٔ حرفه‌ای، صفحهٔ تنظیمات دارد. الگوی استاندارد سه‌گام: یک — ثبت منو با add_menu_page یا add_options_page. دو — فرم HTML با settings_fields() و do_settings_sections(). سه — ثبت تنظیمات با register_setting() و افزودن فیلدها با add_settings_field(). راهنمای تفصیلی در ساخت صفحهٔ تنظیمات اختصاصی. تجربه‌ام: صفحهٔ تنظیمات با استفاده از Settings API، هم امن‌تر است هم ساده‌تر — جای نگرانی از nonce و validation دستی.

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

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

امنیت افزونه

هر افزونه، سطح حملهٔ تازه‌ای به سایت اضافه می‌کند. چهار قاعدهٔ امنیتی حیاتی: یک — پاک‌سازی ورودی: هر داده‌ای که از کاربر می‌آید، باید پاک‌سازی شود (sanitize_text_field، absint، esc_url_raw). دو — escape خروجی: هر داده‌ای که نمایش داده می‌شود، باید escape شود (esc_html، esc_attr، esc_url). سه — nonce: برای فرم‌ها و درخواست‌های AJAX، nonce الزامی است. چهار — check_ajax_referer: در handlerهای AJAX. راهنمای کامل در نوشتن PHP امن در وردپرس، اعتبارسنجی داده‌ها، و پاک‌سازی داده‌ها. تجربه‌ام: بیش از نیمی از افزونه‌های آسیب‌پذیر در مخزن، به‌خاطر نقض همین چهار قاعده بوده‌اند.

آماده‌سازی ترجمه

افزونهٔ جدی، قابل ترجمه است. سه قاعده: یک — تمام رشته‌های متنی با __()، _e()، esc_html__() نوشته شوند. دو — Text Domain در هدر و در تمام توابع یکسان باشد. سه — فایل .pot با ابزارهایی مثل WP-CLI ساخته و در پوشهٔ languages/ نگه داشته شود. حتی اگر امروز قصد ترجمه ندارید، این آماده‌سازی هزینهٔ کمی دارد و در آینده ارزش زیادی می‌سازد.

انتشار و فروش

دو مسیر برای افزونه: یک — مخزن رسمی وردپرس: رایگان، با بازبینی رسمی و اعتبار بالا. فرایند Submission در سایت wordpress.org. دو — فروش تجاری: از طریق سایت خودتان یا مارکت‌های معتبر. مسیر تجاری، درآمد بالا دارد ولی نیازمند بازاریابی و پشتیبانی است. مزایا و معایب در افزونهٔ رایگان یا پولی. تجربه‌ام: برای اولین افزونه، انتشار در مخزن رسمی را توصیه می‌کنم — پشتیبانی جامعهٔ وردپرس، در رشد مهارت شما معجزه می‌کند.

دید مهندسی

برای توسعه‌دهنده‌های سطح بالا، سه الگوی معماری که تفاوت بین افزونهٔ خوب و افزونهٔ حرفه‌ای را می‌سازد: یک — Autoloader. استفاده از Composer یا autoloader دستی برای لود کلاس‌ها، به‌جای requireهای دستی. مزیت: نگهداری آسان‌تر و بارگذاری بهینه. دو — Dependency Injection ساده. به‌جای استفاده از متغیرهای سراسری، وابستگی‌ها را به constructor کلاس‌ها پاس دهید. سه — Unit Testing با PHPUnit. حتی یک تست برای توابع اصلی، در بازنویسی‌های آینده نجات‌دهنده است. تجربه‌ام: افزونه‌های بدون تست، در نسخهٔ سوم یا چهارم، به بدهی فنی تبدیل می‌شوند. ابزارهای آزمون در تست و دیباگ پروژه‌های وردپرس. همچنین یک نکتهٔ معماری که در پروژه‌های بزرگ رعایت می‌کنم: جداسازی منطق کسب‌وکار (Business Logic) از لایهٔ WordPress API. این جداسازی، افزونه را قابل حمل‌تر و تست‌پذیرتر می‌کند.

جمع‌بندی

توسعهٔ افزونهٔ وردپرس، ده گام دارد: پیش‌نیازها، هدر، هوک‌ها، ساختار پوشه، صفحهٔ تنظیمات، شورت‌کد/ویجت/متاباکس، امنیت، ترجمه، و انتشار. اگر امروز فقط یک کار می‌کنید: یک افزونهٔ ساده بسازید که یک پیام به فوتر اضافه می‌کند و آن را در مخزن رسمی منتشر کنید. تجربهٔ انتشار اولین افزونه، درهای تازه‌ای به روی شما باز می‌کند. تجربه‌تان از ساخت اولین افزونه، در دیدگاه‌ها ارزشمند است. 🔌