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

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

وردپرس به بیش از ۴۰٪ وب‌سایت‌های جهان قدرت می‌دهد و بخش عمده‌ای از انعطاف‌پذیری آن مدیون توسعه افزونه وردپرس است. افزونه‌ها بسته‌های مستقل شامل کدهای PHP، جاوا اسکریپت و سایر دارایی‌ها هستند که قابلیت‌های وردپرس را گسترش می‌دهند. این افزونه‌ها همه چیز را، از ترفندهای ساده گرفته تا ویژگی‌های پیچیده تجاری، هدایت می‌کنند. اگر شما یک توسعه‌دهنده جدید هستید، یادگیری نحوه ساخت افزونه‌ها، دروازه شما به سمت سفارشی‌سازی و مقیاس‌دهی این پلتفرم برای هر نیازی است.

توسعه افزونه وردپرس مهارتی کلیدی است که به شما امکان می‌دهد عملکرد دلخواه خود را به هسته سیستم اضافه کنید، بدون اینکه تغییرات شما در به‌روزرسانی‌های آینده از بین برود. در این راهنمای جامع، شما اصول اولیه توسعه افزونه وردپرس را می‌آموزید، یک محیط محلی را با استفاده از ابزارهای مناسب تنظیم می‌کنید و یک افزونه کاربردی به عنوان مثال می‌سازید. تا پایان این مقاله، شما با کالبد یک افزونه، نحوه عملکرد هوک‌ها (Hooks) و بهترین روش‌ها برای کدنویسی امن و قابل نگهداری آشنا خواهید شد. سفر شما در توسعه افزونه وردپرس همینجا آغاز می‌شود.

تنظیم یک محیط توسعه محلی

قبل از اینکه یک خط کد بنویسید، به یک محیط وردپرس محلی نیاز دارید. محیط محلی امکان آزمایش سریع و ایمن کدها را بدون تأثیرگذاری بر وب‌سایت زنده شما فراهم می‌کند. ابزارهایی مانند WordPress Studio سریع‌ترین راه برای شروع هستند. Studio یک ابزار منبع باز است که توسط Automattic پشتیبانی می‌شود و برای تسهیل توسعه افزونه وردپرس طراحی شده است.

گام ۱: نصب ابزار توسعه (Studio)

• دانلود و نصب: ابزار Studio را برای سیستم‌عامل خود (macOS یا Windows) دانلود و نصب کنید.

• ساخت اولین سایت: Studio را اجرا کرده و روی «Add Site» کلیک کنید. یک نام برای سایت جدیدتان وارد کنید. Studio به‌صورت خودکار یک محیط کامل وردپرس را برای شما پیکربندی می‌کند. اکنون سایت جدید شما در نوار کناری Studio ظاهر می‌شود.

گام ۲: آماده‌سازی فضای کدنویسی

• دسترسی به فایل‌ها: از دکمه‌های «Open in…» در Studio استفاده کنید تا پوشه پروژه را در ویرایشگر کد مورد علاقه خود (مانند VS Code) باز کنید.

• پوشه افزونه‌ها: در ریشه پروژه خود، به مسیر wp-content/plugins/ بروید. تمام افزونه‌های وردپرس در این پوشه قرار می‌گیرند.

• برای شروع توسعه افزونه وردپرس، یک پوشه جدید با نامی مناسب (مثلاً quick-reading-time) در داخل پوشه plugins ایجاد کنید. سرور Studio به صورت لحظه‌ای تغییرات شما را در سایت محلی منعکس می‌کند.

ساختاردهی اولین افزونه شما

هر افزونه با یک پوشه و حداقل یک فایل PHP شروع می‌شود. بیایید یک افزونه مینیمال «Hello World» بسازیم تا فرآیند ساخت در توسعه افزونه وردپرس را ساده کنیم.

• در پوشه quick-reading-time/، یک فایل به نام quick-reading-time.php ایجاد کنید.

• ساختار فایل شما باید به این شکل باشد: wp-content/plugins/quick-reading-time/quick-reading-time.php

سربرگ افزونه (Plugin Header)

این سربرگ اطلاعات مورد نیاز وردپرس برای شناسایی افزونه شماست:

<?php
/*
Plugin Name: Quick Reading Time
Description: Displays an estimated reading-time badge beneath post titles.
Version:     1.0
Author:      Your Name
License:     GPL-2.0+
Text Domain: quick-reading-time
*/

این بخش در واقع یک کامنت PHP است، اما وردپرس آن را اسکن می‌کند تا افزونه شما را در بخش «افزونه‌ها -> افزونه‌های نصب‌شده» لیست کند. آن را فعال کنید. هنوز هیچ اتفاقی نمی‌افتد، اما شما اولین گام در توسعه افزونه وردپرس را برداشته‌اید.

درک هوک‌ها (Hooks): Actions و Filters

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

• Actions (عملیات): زمانی فعال می‌شوند که وردپرس عملی را انجام می‌دهد (مثلاً بارگذاری اسکریپت‌ها، ذخیره یک پست). شما با add_action() کد خود را به یک رویداد گره می‌زنید.

• Filters (فیلترها): به شما اجازه می‌دهند داده‌ها را قبل از نمایش یا ذخیره شدن، اصلاح کنید. شما با add_filter() داده‌ای را دریافت، تغییر و برمی‌گردانید.

بیایید با استفاده از فیلتر the_content، یک نشان زمان مطالعه به محتوای پست‌ها اضافه کنیم:

function qrt_add_reading_time( $content ) {
    // Check if it's a single post in the main loop
    if ( ! is_singular( 'post' ) || ! in_the_loop() || ! is_main_query() ) {
        return $content; // Return content unchanged if not on a post
    }

    // ۱. Strip HTML/shortcodes, count words
    $plain   = wp_strip_all_tags(strip_shortcodes($content));
    $words   = str_word_count( $plain );

    // ۲. Estimate: 200 words per minute (WPM)
    $wpm     = (int) get_option( 'qrt_wpm', ۲۰۰ ); // Use setting or default 200
    $minutes = max( ۱, ceil( $words / $wpm ) );

    // ۳. Build the badge
    $badge = sprintf(
        '<p class="qrt-badge" aria-label="%s"><span>%s</span></p>',
        esc_attr__( 'Estimated reading time', 'quick-reading-time' ),
        esc_html( sprintf( _n( '%s min read', '%s mins read', $minutes, 'quick-reading-time' ), $minutes ) )
    );

    return $badge . $content; // Prepend badge to content
}
add_filter( 'the_content', 'qrt_add_reading_time' );

این کد عملکرد اصلی افزونه ما را ایجاد می‌کند و از مفاهیم اصلی توسعه افزونه وردپرس برای اضافه کردن محتوای سفارشی به پست‌ها استفاده می‌کند.

بارگذاری دارایی‌ها به روش وردپرس

برای استایل دادن به نشان زمان مطالعه، باید یک شیوه نامه (Stylesheet) را به روش صحیح وردپرس در صفحه بارگذاری کنیم. در توسعه افزونه وردپرس، باید از هوک wp_enqueue_scripts استفاده کنید تا مطمئن شوید فایل شما در زمان مناسب و به درستی بارگذاری می‌شود.

function qrt_enqueue_assets() {
    wp_enqueue_style(
        'qrt-style',
        plugin_dir_url( __FILE__ ) . 'style.css',
        array(),
        '۱.۰'
    );
}
add_action( 'wp_enqueue_scripts', 'qrt_enqueue_assets' );

حالا، فایل style.css را در همان پوشه افزونه ایجاد کنید تا استایل ساده‌ای به نشانک بدهید:

.qrt-badge span {
    margin: ۰ ۰ ۱rem;
    padding: ۰.۲۵rem ۰.۵rem;
    display: inline-block;
    background: #f5f5f5;
    color: #۵۵۵;
    font-size: ۰.۸۵em;
    border-radius: ۴px;
}

نکته مهم: همیشه دارایی‌ها (CSS/JS) را فقط در مواقعی که واقعاً نیاز دارید بارگذاری کنید (مثلاً فقط در قسمت فرانت‌اند یا برای انواع پست‌های خاص) تا عملکرد وب‌سایت بهبود یابد.

بخش اختیاری: اضافه کردن صفحه تنظیمات

برای اینکه سرعت متوسط خواندن توسط کاربر قابل تنظیم باشد، یک صفحه تنظیمات به افزونه اضافه می‌کنیم. این کار با استفاده از Settings API در توسعه افزونه وردپرس انجام می‌شود.

گام ۱: ثبت تنظیمات و اعتبارسنجی

این کد یک گزینه جدید به نام qrt_wpm را در پایگاه داده ثبت می‌کند. این گزینه سرعت کلمات در دقیقه (WPM) را ذخیره می‌کند و تابع qrt_sanitize_wpm آن را اعتبارسنجی می‌کند:

// Register the setting during admin_init.
function qrt_register_settings() {
    register_setting( 'qrt_settings_group', 'qrt_wpm', array(
        'type' => 'integer',
        'sanitize_callback' => 'qrt_sanitize_wpm',
        'default' => ۲۰۰,
    ) );
}
add_action( 'admin_init', 'qrt_register_settings' );

// Sanitize the WPM value.
function qrt_sanitize_wpm( $value ) {
    $value = intval($value);
    return ( $value > ۰ ) ? $value : ۲۰۰; // Must be a positive integer
}

گام ۲: اضافه کردن صفحه تنظیمات به منوی مدیریت

با استفاده از هوک admin_menu، یک لینک به صفحه تنظیمات افزونه در زیر منوی «Settings» (تنظیمات) اضافه می‌کنیم:

function qrt_register_settings_page() {
    add_options_page(
        'Quick Reading Time', // Page Title
        'Quick Reading Time', // Menu Title
        'manage_options',     // Capability
        'qrt-settings',       // Menu Slug
        'qrt_render_settings_page' // Callback function
    );
}
add_action( 'admin_menu', 'qrt_register_settings_page' );

گام ۳: رندر کردن صفحه تنظیمات

این تابع فرم ورودی را نمایش می‌دهد و از توابع Settings API برای پردازش امن داده‌ها استفاده می‌کند:

function qrt_render_settings_page() {
    if ( ! current_user_can( 'manage_options' ) ) {
        return; // Security check
    }
    ?>
    <div class="wrap">
        <h1><?php esc_html_e( 'Quick Reading Time Settings', 'quick-reading-time' ); ?></h1>
        <form method="post" action="options.php">
            <?php
            settings_fields( 'qrt_settings_group' );
            do_settings_sections( 'qrt_settings_group' );
            $wpm = get_option( 'qrt_wpm', ۲۰۰ ); // Get saved value
            ?>
            <table class="form-table" role="presentation">
                <tr>
                    <th scope="row">
                        <label for="qrt_wpm"><?php esc_html_e( 'Words Per Minute', 'quick-reading-time' ); ?></label>
                    </th>
                    <td>
                        <input name="qrt_wpm" type="number" id="qrt_wpm" value="<?php echo esc_attr( $wpm ); ?>" class="small-text" min="۱" />
                        <p class="description"><?php esc_html_e( 'Average reading speed for your audience.', 'quick-reading-time' ); ?></p>
                    </td>
                </tr>
            </table>
            <?php submit_button(); ?>
        </form>
    </div>
    <?php
}

با این تغییرات، افزونه شما اکنون یک صفحه تنظیمات کاربرپسند در بخش تنظیمات -> Quick Reading Time فراهم می‌کند و مفهوم کامل توسعه افزونه وردپرس را به نمایش می‌گذارد.

بهترین روش‌ها در توسعه افزونه وردپرس

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

• پیشوندگذاری اجباری: برای جلوگیری از تداخل نام (Name Collision)، همیشه به توابع، کلاس‌ها و متغیرهای سراسری خود یک پیشوند منحصربه‌فرد (مانند qrt_) اضافه کنید. فضای نام وردپرس یک فضای جهانی است و این کار امنیت کد شما را تضمین می‌کند.

• پاک‌سازی و فرار: همیشه قبل از ذخیره‌سازی داده‌ها در پایگاه داده، ورودی‌ها را پاک‌سازی (Sanitize) کنید و قبل از نمایش آن‌ها در مرورگر، خروجی‌ها را فرار (Escape) کنید. از توابعی مانند esc_html()، esc_attr() و sanitize_text_field() استفاده کنید.

• بین‌المللی‌سازی (i18n): از توابع ترجمه (__ و _n) برای قابل ترجمه کردن رشته‌های متنی استفاده کنید. این کار افزونه شما را برای کاربران جهانی قابل دسترس می‌کند.

• استفاده از سیستم Enqueue: هرگز اسکریپت‌ها یا استایل‌ها را مستقیماً در HTML یا PHP بارگذاری نکنید؛ همیشه از wp_enqueue_script() و wp_enqueue_style() استفاده کنید.

• مستندسازی و استانداردها: از استاندارد‌های کدنویسی وردپرس پیروی کنید و حتماً برای توابع و فایل‌های اصلی خود مستندات (DocBlocks) بنویسید. این عمل به شما و سایر توسعه‌دهندگان کمک می‌کند تا کد را بهتر درک کنند.

نتیجه‌گیری و گام‌های بعدی

شما اکنون یک افزونه کاری دارید که سه هوک «طلایی» را نمایش می‌دهد: the_content (برای درج محتوا)، wp_enqueue_scripts (برای بارگذاری استایل‌ها) و admin_menu (برای اضافه کردن تنظیمات).

توسعه افزونه وردپرس یک سفر است. گام بعدی برای شما می‌تواند افزودن انواع پست سفارشی (init)، نقاط پایانی REST API (rest_api_init) یا بلاک‌های گوتنبرگ (register_block_type) باشد. مدل ذهنی همیشه یکسان است: هوک درست را پیدا کنید، تابع فراخوانی (callback) را بنویسید و اجازه دهید وردپرس آن را اجرا کند.

با تمرین، جهش از «ای کاش وردپرس می‌توانست…» به «وردپرس انجام می‌دهد» برای شما تبدیل به یک طبیعت ثانویه خواهد شد. به کاوش در توسعه افزونه وردپرس ادامه دهید و از ساختن قابلیت‌های جدید برای وب‌سایت‌ها لذت ببرید.