آموزش ساخت افزونه وردپرس از صفر — راهنمای گام‌به‌گام

وردپرس قدرت اصلی خودش را از اکوسیستم افزونه‌هایش می‌گیرد. اگر به نیاز خاصی برخوردید که افزونه‌ای برایش وجود ندارد، یا می‌خواهید یک راه‌حل سفارشی بسازید، یادگیری ساخت افزونه یکی از بهترین سرمایه‌گذاری‌هاست. در این آموزش، اولین افزونه وردپرس‌تان را از صفر می‌سازیم.

افزونه وردپرس چیست؟

افزونه (Plugin) یک یا چند فایل PHP است که امکانات جدیدی به وردپرس اضافه می‌کند، بدون اینکه نیاز به تغییر فایل‌های هسته وردپرس باشد. افزونه‌ها از طریق سیستم هوک‌ها (Hooks) با وردپرس تعامل می‌کنند.

بیش از ۶۰ هزار افزونه رایگان در مخزن رسمی wordpress.org/plugins موجود است. یعنی تقریباً هر کاری که فکرش را بکنید، احتمالاً قبلاً کسی برایش افزونه نوشته.

پیش‌نیازهای ساخت افزونه

• آشنایی پایه با PHP (متغیر، تابع، شرط، حلقه)
• درک مفهوم WordPress Hooks (Actions و Filters)
• دسترسی به محیط توسعه محلی (Local، XAMPP، یا یک هاست تست)
• یک ویرایشگر کد مناسب مثل VS Code یا PHPStorm

گام ۱: ساخت پوشه افزونه

به مسیر /wp-content/plugins/ بروید و پوشه‌ای با نام افزونه‌تان بسازید:

/wp-content/plugins/my-first-plugin/

نام پوشه باید با حروف کوچک، بدون فاصله و ترجیحاً با خط تیره (-) باشد.

گام ۲: ساخت فایل اصلی افزونه

داخل پوشه، فایلی با همان نام پوشه و پسوند .php بسازید:

/wp-content/plugins/my-first-plugin/my-first-plugin.php

این فایل اصلی افزونه است. در ابتدای آن باید هدر استاندارد افزونه را بنویسید:

<?php
/**
 * Plugin Name: اولین افزونه من
 * Plugin URI: https://example.com/my-first-plugin
 * Description: اولین افزونه وردپرسی که ساخته‌ام
 * Version: 1.0.0
 * Author: نام شما
 * Author URI: https://example.com/
 * License: GPL-2.0+
 * Text Domain: my-first-plugin
 */

// جلوگیری از دسترسی مستقیم
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

اطلاعات این هدر در داشبورد وردپرس نمایش داده می‌شود. خط if ( ! defined( 'ABSPATH' ) ) جلوی اجرای مستقیم فایل را از طریق مرورگر می‌گیرد که یک اقدام امنیتی ضروری است.

گام ۳: فعال‌سازی افزونه

به داشبورد وردپرس بروید، منوی افزونه‌ها را باز کنید. افزونه «اولین افزونه من» را می‌بینید. روی «فعال‌سازی» کلیک کنید.

در این مرحله افزونه هیچ کاری نمی‌کند، چون هنوز کدی ننوشته‌ایم. در گام بعدی اضافه می‌کنیم.

گام ۴: درک Hooks در وردپرس

هوک‌ها دو نوع‌اند:

Actions (اقدامات)

در نقاط خاصی از اجرای وردپرس فراخوانی می‌شوند. با add_action() تابع شما در آن نقطه اجرا می‌شود.

Filters (فیلترها)

داده‌ای را ورودی می‌گیرند، اجازه تغییر می‌دهند و خروجی برمی‌گردانند. با add_filter() محتوا را قبل از نمایش تغییر می‌دهید.

گام ۵: اولین قابلیت — پیام خوش‌آمد

بیایید یک پیام خوش‌آمد بالای محتوای هر پست اضافه کنیم. کد زیر را به فایل افزونه اضافه کنید:

function mfp_add_welcome_message( $content ) {
    if ( is_single() ) {
        $welcome = '<div style="background:#f0f8ff; padding:15px; border-right:4px solid #0073aa;">
                      به وبلاگ ما خوش آمدید!
                    </div>';
        return $welcome . $content;
    }
    return $content;
}
add_filter( 'the_content', 'mfp_add_welcome_message' );

حالا به هر پست سایت خود بروید. باکس آبی رنگ پیام خوش‌آمد را بالای محتوا می‌بینید.

گام ۶: افزودن شورت‌کد

شورت‌کدها به شما اجازه می‌دهند قابلیت افزونه را هر جایی از محتوا درج کنید:

function mfp_current_year_shortcode() {
    return date('Y');
}
add_shortcode( 'current_year', 'mfp_current_year_shortcode' );

حالا در هر پست یا صفحه‌ای [current_year] بنویسید، سال جاری نمایش داده می‌شود.

گام ۷: افزودن صفحه تنظیمات

برای افزونه حرفه‌ای، معمولاً صفحه‌ای در داشبورد برای تنظیمات نیاز دارید:

function mfp_add_settings_page() {
    add_options_page(
        'تنظیمات اولین افزونه',
        'اولین افزونه',
        'manage_options',
        'my-first-plugin',
        'mfp_settings_page_html'
    );
}
add_action( 'admin_menu', 'mfp_add_settings_page' );

function mfp_settings_page_html() {
    ?>
    <div class="wrap">
        <h1>تنظیمات اولین افزونه</h1>
        <p>این صفحه تنظیمات افزونه شماست.</p>
    </div>
    <?php
}

ساختار پیشنهادی افزونه حرفه‌ای

برای افزونه‌های بزرگ‌تر، سازماندهی فایل‌ها مهم است:

my-first-plugin/
├── my-first-plugin.php (فایل اصلی)
├── uninstall.php (پاک‌سازی هنگام حذف)
├── readme.txt (برای مخزن wordpress.org)
├── includes/
│   ├── class-main.php
│   ├── class-settings.php
│   └── class-api.php
├── admin/
│   ├── class-admin.php
│   └── views/
├── public/
│   ├── class-public.php
│   └── js/
├── languages/
│   └── my-first-plugin-fa_IR.po
└── assets/
    ├── css/
    └── images/

نکات کلیدی امنیت

• همیشه از sanitize_text_field() و توابع پاک‌سازی برای ورودی‌های کاربر استفاده کنید
• با esc_html()، esc_attr() و esc_url() خروجی‌ها را امن کنید
• از nonce برای فرم‌های مدیریت استفاده کنید (wp_nonce_field())
• بررسی دسترسی کاربر با current_user_can() قبل از هر عملیات حساس
• از $wpdb->prepare() برای کوئری‌های دیتابیس استفاده کنید تا SQL Injection رخ ندهد

تست و دیباگ افزونه

در wp-config.php این خطوط را فعال کنید:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

خطاها در فایل /wp-content/debug.log ثبت می‌شوند و می‌توانید با error_log('متن') اطلاعات را برای دیباگ بنویسید.

انتشار در مخزن wordpress.org

اگر افزونه‌تان پخته و کاربردی است، می‌توانید آن را در مخزن رسمی منتشر کنید:

1. افزونه باید طبق استانداردهای کدنویسی وردپرس نوشته شود
2. فایل readme.txt با فرمت استاندارد وردپرس بنویسید
3. در wordpress.org/plugins/developers/add/ ثبت نام و درخواست کنید
4. کد شما بازبینی می‌شود (۲ تا ۱۴ روز)
5. پس از تایید، به مخزن SVN دسترسی دارید و افزونه را آپلود می‌کنید

پرسش‌های متداول

برای ساخت افزونه باید حتماً برنامه‌نویس حرفه‌ای باشم؟

خیر. با دانش پایه PHP می‌توانید افزونه‌های ساده بسازید. افزونه‌های پیچیده نیاز به تجربه بیشتر دارند اما شروع کار ساده است.

آیا افزونه تست‌نشده می‌تواند سایت را خراب کند؟

بله. همیشه افزونه خودتان را ابتدا روی سایت تست یا استیجینگ اجرا کنید، نه سایت اصلی. یک خطای PHP می‌تواند کل سایت را White Screen of Death کند.

چه فرقی بین افزونه و Must-Use Plugin وجود دارد؟

افزونه‌های Must-Use (MU) در /wp-content/mu-plugins/ قرار می‌گیرند و به‌طور خودکار فعال هستند. نمی‌توان آن‌ها را از داشبورد غیرفعال کرد. برای کدهای حیاتی یا قوانین سراسری مناسب‌اند.

چطور افزونه‌ام را چندزبانه کنم؟

از توابع __()، _e() و __() استفاده کنید، فایل .pot بسازید و با Poedit به زبان‌های مختلف ترجمه کنید.

مقالات مرتبط