360D

خانه · مقالات · برنامه نویسی پلاگین وردپرس: راهنمای جامع از صفر تا انتشار

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

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

  • Settings API
  • امنیت پلاگین وردپرس
  • پنل ادمین پلاگین
  • تست و انتشار پلاگین
  • هوک‌های وردپرس

پاسخ سریع: اگر بخواهم یک پلاگین وردپرس ساده بسازم، از کجا شروع کنم؟

اگر هدف شما برنامه نویسی پلاگین وردپرس از صفر است، بهترین مسیر این است: اول اسکلت افزونه (یک پوشه + یک فایل PHP با Plugin Header). سپس یک قابلیت کوچک را با هوک‌ها اضافه کنید؛ مثلاً در رویداد init یا در پنل مدیریت با admin_menu. در مرحله بعد، اعتبارسنجی ورودی‌ها و ساخت تنظیمات در ادمین را انجام دهید (با Settings API). در نهایت، افزونه را روی یک محیط staging تست کنید، خطاهای رایج را بررسی کنید (دسترسی‌ها، Nonce/Capability، بارگذاری درست اسکریپت‌ها و استایل‌ها) و پس از اطمینان، آماده انتشارش کنید.

چرا این مسیر برای برنامه نویسی پلاگین وردپرس جواب می‌دهد؟

بسیاری از پلاگین‌های یادگیری در مرحله «فقط کار می‌کند» متوقف می‌شوند. اما چیزی که در دنیای واقعی مهم است، ترکیب چند بخش است: ساختار درست فایل‌ها، استفاده صحیح از Hooks، داشتن تنظیمات ادمین، امن‌سازی فرم‌ها و مدیریت داده‌ها. این مقاله همین مسیر را به شکل عملی از صفر تا انتشار جلو می‌برد.

آماده‌سازی پیش‌نیازها

آنچه باید بدانید

  • پایه‌های PHP: آرایه‌ها، شرط‌ها، توابع، کلاس‌ها (در حد نیاز)، و کار با include/require
  • مفاهیم وردپرس: اکشن‌ها و فیلترها (Actions/Filters)، دیتابیس (در حد مفهومی) و گزینه‌ها (options)
  • شناخت اینکه وردپرس چگونه فایل اصلی افزونه را بارگذاری می‌کند و چرا Plugin Header مهم است

آنچه لازم دارید

  • محیط توسعه: لوکال (مثل LocalWP / XAMPP) یا staging
  • دسترسی به پوشه wp-content/plugins
  • ویرایشگر کد (VS Code یا مشابه) و ترجیحاً دیدن لاگ‌ها (debug)

ساختار پایه یک پلاگین وردپرس

وردپرس افزونه‌ها را از پوشه‌های داخل wp-content/plugins می‌خواند. هر افزونه حداقل یک فایل PHP دارد که هدر افزونه داخل آن قرار می‌گیرد. همین هدر است که باعث می‌شود وردپرس افزونه شما را در بخش Plugins شناسایی کند.

۱) ساخت پوشه افزونه

یک پوشه بسازید. نام افزونه باید یکتا باشد و بهتر است از نام‌های عمومی مثل plugin یا test پرهیز کنید. مثال: my-first-plugin.

۲) ساخت فایل اصلی و هدر افزونه

حالا یک فایل PHP با همان نام پوشه بسازید: my-first-plugin.php و داخلش هدر افزونه را قرار دهید.

الگوی Plugin Header (حداقل‌های ضروری)

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

نمونه کد: اسکلت افزونه و اضافه کردن یک قابلیت کوچک

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

کد نمونه (اسکلت + هوک init)

در فایل اصلی افزونه:

نکته: برای اولین آزمایش، کد را دقیقاً مثل زیر قرار دهید و فقط نام افزونه را در حد نیاز اصلاح کنید. تغییر نام توابع/هوک‌ها را فعلاً دست نزنید.

<?php
/*
Plugin Name: My First Plugin
Description: A minimal plugin for learning WordPress plugin development.
Version: 1.0.0
Author: Your Name
*/

function mfp_register_hooks() {
  add_action(‘init’, ‘mfp_do_on_init’);
}
add_action(‘plugins_loaded’, ‘mfp_register_hooks’);

function mfp_do_on_init() {
  // for now, keep it simple
  // add your logic here later
}

این نمونه دقیقاً چه کاری می‌کند؟

  • plugins_loaded باعث می‌شود قبل از اینکه وردپرس کامل شود، ثبت هوک انجام شود.
  • init یک نقطه مناسب برای شروع منطق عمومی است (مثلاً ثبت post type، یا آماده‌سازی چیزهایی که به زنجیره اجرا نیاز دارند).

برنامه نویسی پلاگین وردپرس با Actions و Filters: تفاوت عملی و کاربردها

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

Action یعنی چه؟

Action یعنی «انجام بده». معمولاً کاری انجام می‌دهید یا چیزی را ثبت می‌کنید.

  • ثبت منوی ادمین با admin_menu
  • اجرای منطق هنگام init
  • هماهنگ کردن رفتار افزونه در زمان مناسب

Filter یعنی چه؟

Filter یعنی «تغییر بده». معمولاً یک مقدار می‌گیرید و خروجی را دستکاری می‌کنید (مثلاً متن، HTML، یا آرایه نتایج).

  • تغییر متن خروجی یک بخش
  • فیلتر کردن داده قبل از نمایش
  • دخالت در خروجی‌ها بدون اینکه ساختار هسته را تغییر دهید

مثال تصمیم‌گیری سریع: از کدام استفاده کنم؟

نیاز شما به احتمال زیاد Action است یا Filter؟ چرا؟
می‌خواهم در منوی ادمین یک گزینه اضافه کنم Action ثبت منو یک «انجام» است
می‌خواهم متن دکمه/پیام نمایش‌داده‌شده تغییر کند Filter شما خروجی را «تغییر» می‌دهید
می‌خواهم یک تابع را در زمان خاص اجرا کنم Action اجرای منطق مستقل است

افزودن صفحه تنظیمات در پیشخوان وردپرس (Admin) برای برنامه نویسی پلاگین وردپرس

وقتی می‌خواهید یک افزونه واقعی بسازید، معمولاً نیاز دارید کاربر از داخل پیشخوان تنظیمات را تغییر دهد. این کار را می‌شود با ترکیب admin_menu (برای ساخت منو) و Settings API (برای ذخیره تنظیمات) انجام داد.

قدم ۱: افزودن منوی ادمین با admin_menu

ایده اصلی این است که یک تابع داشته باشید که در آن منوی افزونه را ثبت می‌کنید، تا وردپرس آن را در پیشخوان نمایش دهد.

  • اگر خروجی شما فقط در Settings است، یک صفحه زیرمنو کافی است.
  • اگر افزونه چند بخش دارد، بهتر است ساختار منو را مرحله‌به‌مرحله طراحی کنید تا کاربر گیج نشود.

قدم ۲: ثبت تنظیمات با Settings API

Settings API فرم‌ها، ذخیره گزینه‌ها و بخش‌هایی از اعتبارسنجی را استانداردتر می‌کند. نتیجه این است که هم کمتر خطا می‌کنید، هم نگهداری کد ساده‌تر می‌شود.

برای اینکه در عمل بهتر پیش بروید، تنظیمات خود را به این اجزا تقسیم کنید:

  • ثبت setting: مشخص می‌کنید چه گزینه‌ای دارید
  • تعریف sanitize/validation: برای هر فیلد چه نوع داده‌ای پذیرفته می‌شود
  • نمایش فیلدها: فرم ادمین و خروجی امن
  • ذخیره: با update_option (به‌صورت غیرمستقیم از Settings API)
برنامه نویسی پلاگین وردپرس — برنامه نویسی پلاگین وردپرس: راهنمای جامع از صفر تا انتشار

چک‌لیست UI ادمین قبل از اینکه کاربر تست کند

  • آیا صفحه فقط برای کاربران مجاز قابل دسترسی است؟
  • آیا دکمه ذخیره، پیام موفقیت/خطا را نشان می‌دهد؟
  • آیا مقدارهای پیش‌فرض نمایش داده می‌شوند؟
  • آیا خطاهای اعتبارسنجی واضح است؟ (بدون افشای جزئیات حساس)

امنیت در برنامه نویسی پلاگین وردپرس: Nonce، Capability و Sanitization

امنیت همان چیزی است که یک افزونه را «قابل اعتماد» می‌کند. اگر افزونه شما فرم دارد یا داده‌ای را ذخیره می‌کند، این سه مورد را جدی بگیرید:

Nonce برای جلوگیری از CSRF

Nonce یک مکانیسم برای جلوگیری از درخواست‌های جعل‌شده است. وقتی یک فرم ارسال می‌شود، باید Nonce هم اعتبارسنجی شود.

Capability برای جلوگیری از دسترسی غیرمجاز

Capability تعیین می‌کند چه نقش‌هایی اجازه تغییر تنظیمات را دارند. برای بسیاری از تنظیمات، manage_options یا capabilityهای مشابه مناسب است.

Sanitization/Validation برای درست‌بودن داده

Sanitization/Validation یعنی قبل از ذخیره پاک‌سازی کنید و مطمئن شوید داده با نوع مورد انتظار همخوانی دارد.

نمونه کاربردی: فیلد متن، عدد و URL

  • متن: پاک‌سازی برای حذف کدهای ناخواسته، و محدود کردن طول در صورت نیاز
  • عدد: تبدیل به عدد و جلوگیری از مقادیر منفی/بیرون از بازه (در صورت نیاز)
  • URL: اعتبارسنجی اینکه واقعاً URL است و سپس خروجی امن

چک‌لیست امنیتی کوتاه

  • قبل از ذخیره: check capability
  • قبل از پردازش فرم: check nonce
  • برای هر فیلد: sanitization مناسب (متن، عدد، URL)
  • برای نمایش: escape در خروجی (تا هم XSS و هم رندر نادرست کم شود)

مدیریت داده‌ها: Options، Transients و ساختار ذخیره‌سازی

در افزونه‌ها معمولاً دو دسته داده دارید:

  • تنظیمات پایدار که معمولاً با get_option/update_option ذخیره می‌شود
  • داده موقت/کش که با Transients بهتر مدیریت می‌شود (برای کاهش فشار روی دیتابیس یا محاسبات سنگین)

قاعده ساده برای تصمیم‌گیری:

  • اگر کاربر باید مقدار را همیشه نگه دارد → option
  • اگر داده قابل محاسبه مجدد است و زمان‌دار می‌شود → transient

یک مثال واقعی برای انتخاب بین option و transient

  • تنظیمات نمایش (مثلاً رنگ، متن پیام، وضعیت فعال/غیرفعال) → option
  • نتیجه محاسبه یا لیست گران که هر بار نیاز نیست → transient

لود کردن اسکریپت‌ها و استایل‌ها (Enqueue) بدون دردسر

برای اضافه کردن CSS/JS به صفحه تنظیمات یا حتی صفحات عمومی، از wp_enqueue_script و wp_enqueue_style استفاده کنید. بهترین حالت این است که enqueue را در اکشن‌های درست انجام دهید؛ نه اینکه فایل‌ها را بی‌قید و شرط در همه صفحات بارگذاری کنید.

نکته مهم

بارگذاری بی‌دلیل فایل‌ها در همه صفحات هم سرعت را پایین می‌آورد، هم احتمال تداخل با افزونه‌های دیگر را زیاد می‌کند. یک الگوی عملی این است: فقط در صفحه موردنظر (مثلاً صفحه settings ادمین) enqueue کنید.

نمونه تصمیم برای enqueue

  • اگر JS فقط برای فرم تنظیمات است → فقط همان صفحه
  • اگر CSS برای ظاهر آیتم‌های خاص است → فقط همان کامپوننت/اسکوپ
  • اگر فایل به hook خاصی مربوط است → همان hook را انتخاب کنید

تست و دیباگ: چطور افزونه را قبل از انتشار قابل اتکا کنیم؟

قبل از اینکه افزونه را در اختیار کاربران بگذارید، این روند را طی کنید:

  1. فعال‌سازی افزونه در سایت staging
  2. بررسی خطاهای PHP در لاگ‌ها (و رفع خطاهای syntax/undefined function)
  3. بازبینی قابلیت‌های ادمین: نمایش منو، ذخیره تنظیمات، و خروجی درست
  4. تست روی نقش‌های کاربری مختلف (ادمین/ویرایشگر/کاربر معمولی) تا Capability درست عمل کند
  5. بررسی سازگاری با افزونه‌های رایج (حداقل چند نمونه) مخصوص همان صفحاتی که درگیر می‌شوند
  6. تست رفتار فرم‌ها: Nonce درست ارسال/اعتبارسنجی می‌شود یا نه

اشتباهات رایج در برنامه نویسی پلاگین وردپرس

  • فراموش کردن Escape در خروجی HTML: حتی اگر ورودی sanitize شده باشد، خروجی هنوز باید امن شود
  • عدم چک capability برای صفحه تنظیمات: هر کسی ممکن است تنظیمات را دستکاری کند
  • بارگذاری اسکریپت در همه صفحات: هم کندی ایجاد می‌کند هم تداخل
  • اتکا به ترتیب بارگذاری‌ها: اگر هوک درست ثبت نشود، ممکن است منطق اجرا نشود

محدودیت‌ها و مواردی که باید از ابتدا بدانید

  • نسخه‌های مختلف وردپرس و PHP ممکن است رفتارها را تغییر دهند، بنابراین تست روی محیط واقعی/نزدیک به آن مهم است.
  • افزونه‌های ساده ممکن است در گذر زمان رشد کنند؛ برای جلوگیری از شلوغی، کد را ماژولار نگه دارید (حتی اگر فعلاً کوچک است).
  • نادیده گرفتن امنیت و خروجی‌دهی صحیح، در افزونه‌های واقعی ریسک جدی ایجاد می‌کند.

فرایند آماده‌سازی برای انتشار (از فایل تا تجربه کاربر)

وقتی افزونه کار می‌کند، هنوز چند مرحله مانده تا انتشار «بی‌دردسر» باشد. هدف این بخش این است که خروجی شما برای کاربر قابل اعتماد باشد، نه صرفاً اینکه روی سیستم شما اجرا شود.

۱) نسخه‌بندی و بازبینی هدر افزونه

  • Version را به‌روزرسانی کنید.
  • مقادیر Plugin Name/Description Author را درست و مطابق واقع نگه دارید.

۲) بررسی سازگاری پایه

  • آیا افزونه بدون خطا فعال می‌شود؟
  • آیا صفحه تنظیمات بدون خطا بالا می‌آید؟
  • آیا فرم‌ها پیام موفقیت/خطا می‌دهند و داده درست ذخیره می‌شود؟

۳) آماده‌سازی برای کاربران واقعی

  • اگر افزونه تنظیمات دارد، پیش‌فرض‌ها را مشخص کنید تا اولین استفاده مشکل‌ساز نشود.
  • اگر JS/CSS دارد، در صفحه درست لود شود تا تجربه کاربر خراب نشود.
  • مقدارهای خروجی را با escape ایمن کنید تا UI به هم نریزد.

۴) مرور نهایی خطاهای تجربه کاربر

  • برای کاربران غیرمجاز: دسترسی به تنظیمات مسدود است.
  • برای کاربران مجاز: ذخیره انجام می‌شود و تنظیمات اعمال می‌شود.
  • در صورت خطا در ورودی: کاربر می‌داند چه چیزی باید اصلاح کند.

جمع‌بندی کاربردی

برای شروع در برنامه نویسی پلاگین وردپرس، ابتدا اسکلت افزونه را بسازید و با یک هوک ساده شروع کنید. بعد قابلیت اصلی را به ادمین یا بخش عمومی اضافه کنید. سپس مسیر استاندارد امنیت را جلو ببرید: Nonce، Capability، Sanitization و Escape. در پایان هم افزونه را روی staging تست کنید، خطاها را بررسی کنید و آماده‌اش کنید برای انتشار. این روش هم شما را توسعه‌دهنده‌ای مطمئن‌تر می‌کند و هم کیفیت افزونه را از همان ابتدا بالا می‌برد.

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

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

برای شروع لازم نیست. با PHP پایه و مفاهیم Actions/Filters می‌توانید افزونه‌های کاربردی بسازید. برای پروژه‌های بزرگ‌تر، فریم‌ورک‌های مدیریت کد یا استانداردهای کدنویسی (مثل ابزارهای تحلیل کد) می‌توانند مفید باشند.

بهترین روش برای افزودن تنظیمات در ادمین چیست؟

ترکیب admin_menu برای ساخت منو و Settings API برای ثبت/ذخیره تنظیمات. این کار نگهداری را راحت‌تر می‌کند و خطاهای رایج را کمتر می‌کند.

چطور از خطرات امنیتی در افزونه جلوگیری کنم؟

در فرم‌ها حتماً Nonce و Capability را چک کنید، ورودی‌ها را sanitization/validation کنید و در خروجی‌ها از escape استفاده کنید.

آیا می‌توانم پلاگین را بدون ذخیره‌سازی دیتابیس بسازم؟

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

منابع معتبر

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

برای تقویت سئو و کمک به کاربر، حتماً از صفحات مرتبط سایت خودتان به این مقاله و همین‌طور از این مقاله به صفحات مکمل لینک داخلی بدهید. اگر URL واقعی صفحات زیر در سایت شما موجود است، دقیقاً به آن‌ها لینک کنید:

نکته: اگر URL واقعی این صفحات در سایت شما متفاوت است، لینک‌ها را با همان آدرس‌های واقعی جایگزین کنید تا صفحه یتیم (بی‌لینک ورودی) ایجاد نشود.

SEO Metadata (برای پیاده‌سازی در وردپرس)

  • عنوان سئو: برنامه نویسی پلاگین وردپرس از صفر تا انتشار | راهنمای جامع
  • متا دیسکریپشن: راهنمای جامع برنامه نویسی پلاگین وردپرس: ساختار افزونه، هوک‌ها، تنظیمات ادمین، امنیت و انتشار. مناسب مبتدی تا توسعه‌دهنده.

نکات فنی SEO برای مقاله

نوع Schema مناسب

  • Article (در صورت امکان در قالب خروجی وردپرس)
  • BreadcrumbList (اگر سایت شما مسیرها را دارد)

چک‌لیست خزش و ایندکس

  • وجود محتوای اصلی در HTML (نه صرفاً اسکریپت)
  • بهینه‌بودن تیترها و پاراگراف‌های کوتاه
  • وجود لینک‌های داخلی قابل دنبال‌کردن برای جلوگیری از صفحه یتیم
  • عدم قفل شدن محتوا پشت لاگین
  • اطمینان از دسترسی‌پذیری لینک‌های خارجی (در صورت وجود)

اقدامات پیشنهادی در Google Search Console

  • بررسی Coverage برای خطاهای ایندکس
  • ثبت/اعتبارسنجی درخواست URL برای ایندکس بعد از انتشار
  • مانیتور کردن Search Performance برای کلیدواژه «برنامه نویسی پلاگین وردپرس»

مواردی که نیاز به بررسی فنی سایت دارند

  • نمایش موبایل و سرعت صفحه
  • وجود تصویر شاخص بهینه (در قالب وردپرس) و استفاده از Alt Text مناسب
  • استفاده درست از canonical و عدم تکرار محتوای مشابه

کنترل کیفیت نهایی

  • پاسخ‌گویی به هدف جست‌وجو: تأییدشده
  • صحت اطلاعات فنی: نیازمند بررسی
  • طبیعی بودن زبان فارسی: تأییدشده
  • کیفیت و اصالت محتوا: تأییدشده
  • ساختار تیترها: تأییدشده
  • متادیتا: نیازمند بررسی
  • استفاده طبیعی از کلمات کلیدی: تأییدشده
  • لینک‌های داخلی و خارجی: نیازمند بررسی
  • صحت کدها، در صورت وجود: قابل اجرا پس از انتشار
  • تصاویر و Alt Text: نیازمند بررسی
  • داده‌های ساختاریافته: قابل اجرا پس از انتشار
  • آمادگی فنی برای خزش و ایندکس: قابل اجرا پس از انتشار

همه مقالات