ساخت افزونه با هوش مصنوعی

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

# افزونه‌نویسی استاندارد وردپرس (مرجع)

هدف: خروجی مثل یک افزونه‌ی **خام و استاندارد وردپرسی** باشد — تمیز، امن، توسعه‌پذیر، بدون باگ، و موازی با
WordPress Coding Standards و Plugin Handbook. کد را طوری بنویس که یک ریویوورِ ووردپرس.org بدون ایراد قبول کند.

**این اسکیل را هر وقت** کاربر افزونه وردپرس یا فایل .php مرتبط با وردپرس/ووکامرس می‌سازد، ویرایش می‌کند، اصلاحیه
می‌خواهد، یا می‌گوید «حرفه‌ای بررسی کن» فعال کن — 

قوانین بازبینی محدود به پرامپت، امنیت (nonce/capability/escape/sanitize)، الگوی ذخیره‌ی تنظیمات، تصمیم
`array_merge` در برابر migration، چرخه‌ی عمر و uninstall، انکیو دارایی‌ها، شورت‌کد/متاباکس/AJAX و سازگاری ووکامرس/HPOS.

## ۰) قوانین طلایی رفتار (همیشه رعایت کن)

- **فقط چیزی که در پرامپت خواسته شده** را تغییر بده. هیچ بخش دیگری را — حتی اگر بهترش هم می‌دانی — دست نزن. اول بصورت پیشنهاد بگو با درصد موفقیت!
- **اصلاحیه = محدود به پرامپت.** بازنویسی کلی ممنوع است مگر صریحاً خواسته شود.
- خروجی **استاندارد + توسعه‌پذیر**: نام‌گذاری یکدست با prefix یکتا، توابع/کلاس‌های قابل گسترش، بدون hard-code پراکنده،
  بدون منطق تکراری (یک گیت/هلپر مرکزی به‌جای کپی‌پیست).
- **i18n لازم نیست**: متن‌ها مستقیم فارسی نوشته شوند؛ نیازی به `__()`, `_e()`, `load_plugin_textdomain` یا textdomain نیست
- موارد فنی‌تر/جامع‌تر/کاربردی‌تر را **در صورت لزوم** اضافه کن، ولی باز هم بدون دست‌زدن به بخش‌های خارج از پرامپت.
- تا حد امکان از پیچیدگی کد ها و محاسبات ریاضی غیرضروری کدها دوری کن.

## ۱) اسکلت و ساختار فایل

افزونه باید اول فایل زیپ . درونش تک فولدر اصلی . نهایتا همه فایل های دیگر باشند

my-plugin/
├── my-plugin.php          ← فایل اصلی: هدر + define ها + require ها + هوک‌های چرخه‌ی عمر
├── uninstall.php          ← پاک‌سازی دیتابیس هنگام حذف
├── assets/                  ← فایل های  css - js - font 
├── includes/              ← منطق: کلاس‌ها و توابع php
```

قواعد ثابت:
- **هر فایل PHP** با گارد شروع شود:
  ```php
  if ( ! defined( 'ABSPATH' ) ) { exit; }
  ```
- ثابت‌های پایه در فایل اصلی: `MYPLG_VERSION`, `MYPLG_DIR` (`plugin_dir_path`), `MYPLG_URL` (`plugin_dir_url`),
  `MYPLG_BASENAME` (`plugin_basename`).
- **یک prefix یکتا** برای همه‌ی توابع/هوک‌ها/آپشن‌ها/متاکی‌ها انتخاب کن تا با افزونه‌های دیگر collision نکند.
- فقط یک‌بار `require_once` در فایل اصلی؛ منطق در `includes/` بماند.

## ۲) امنیت (غیرقابل‌مذاکره)

| ورودی/خروجی | کار درست |
|---|---|
| خروجی HTML | `esc_html()` / `esc_attr()` / `esc_url()` / `wp_kses_post()` |
| ذخیره‌ی ورودی | `sanitize_text_field()` / `sanitize_key()` / `absint()` / `sanitize_hex_color()` و سانیتایزر اختصاصی |
| فرم تنظیمات | Settings API + `sanitize_callback` |
| AJAX / اکشن فرم | `check_ajax_referer()` یا `wp_verify_nonce()` + `current_user_can()` |
| کوئری مستقیم DB | `$wpdb->prepare()` |

قواعد:
- **هیچ‌وقت** ورودی کاربر را escape‌نشده echo نکن. سانیتایز موقع ذخیره، escape موقع نمایش (هر دو، نه یکی).
- هر تغییر state (ذخیره/حذف/آپدیت) باید **nonce + capability check** داشته باشد.
- خروجی‌ای که از قبل escape شده را با `// phpcs:ignore` کامنت کن تا نیت روشن بماند.
- بدون درخواست خارجی غیرضروری؛ فونت/آیکون/تصویر را محلی نگه‌دار.
- فقط یک خط کامنت خلاصه کافیه نه بیشتر

## ۳) الگوی ذخیره‌ی تنظیمات (یک آپشن آرایه‌ای واحد)

به‌جای ده‌ها `get_option` جدا، **یک آپشن آرایه‌ای** نگه‌دار. این هم تمیزتر است هم کم‌کوئری‌تر.

```php
// دیفالت‌ها در یک جا
function myplg_get_defaults() {
    return array(
        'key_a' => '#ffffff',
        'key_b' => 1,
    );
}

// خواندن کل تنظیمات با کش استاتیک (یک کوئری در هر ریکوئست)
function myplg_get_all_settings( $force = false ) {
    static $cache = null;
    if ( $force || null === $cache ) {
        $saved = get_option( 'myplg_settings', array() );
        if ( ! is_array( $saved ) ) { $saved = array(); }
        $cache = array_merge( myplg_get_defaults(), $saved );
    }
    return $cache;
}

// گتر مرکزی یک کلید
function myplg_get_option( $key, $default = null ) {
    $all = myplg_get_all_settings();
    return array_key_exists( $key, $all ) ? $all[ $key ] : $default;
}
```

ثبت با Settings API (یک گروه، یک سانیتایزر مرکزی که فقط کلیدهای ارسالی را با اسکیمای سانیتایز ادغام می‌کند):
```php
register_setting( 'myplg_group', 'myplg_settings', array( 'sanitize_callback' => 'myplg_sanitize_settings' ) );
```
سانیتایزر باید مقادیر فعلی را بخواند و فقط کلیدهای موجود در `$input` را روی آن‌ها بنویسد (تا چک‌باکس‌های تیک‌نخورده
و فیلدهای تب‌های دیگر پاک نشوند). برای چک‌باکس، یک `<input type=hidden value=0>` همنام قبل از چک‌باکس بگذار.

## ۴) array_merge در برابر Migration (مهم‌ترین قانون نسخه‌بندی 1.0.0 به بعد)

**جدول تصمیم:**

| تغییر بین نسخه‌ها | روش درست |
|---|---|
| کلید جدید + دیفالت ساده | `array_merge` کافی است |
| تغییر **نام** کلید | Migration اجباری |
| **ادغام** دو کلید در یکی | Migration اجباری |
| **حذف** کلید | Migration اجباری |
| تغییر **نوع داده** (مثلاً عدد → آرایه) | Migration اجباری |
| فقط مقدار **دیفالت** عوض شد و می‌خواهی کاربران قدیمی هم ببینند | Migration |

**خلاصه‌ی یک‌خطی:** کلید *تغییر نام داد / حذف شد / ادغام شد / نوعش عوض شد* → migration. فقط *کلید جدید اضافه شد* → array_merge.

نکته: تصمیم صحیح نهایی باتویه!

## ۵) چرخه‌ی عمر: activation / deactivation / uninstall


## ۶) انکیو دارایی‌ها (هدفمند و نسخه‌دار)

- فرانت فقط وقتی لازم است لود شود (مثلاً وجود شورت‌کد در محتوا یا گزینه‌ی «لود اجباری»)، نه روی همه‌ی صفحات.
- ادمین فقط روی صفحه‌ی تنظیمات خودِ افزونه (`$hook` را چک کن).
- همیشه `MYPLG_VERSION` را به‌عنوان نسخه پاس بده تا کش مرورگر با هر آپدیت بشکند.
- داده‌ی PHP→JS با `wp_localize_script` یا `wp_add_inline_script`.
- CSS داینامیک (رنگ/سایز از تنظیمات) با `wp_add_inline_style` تزریق شود، نه استایل اینلاین پراکنده در HTML.

## ۷) APIهای پرکاربرد

- **شورت‌کد:** همیشه `return` کن (نه `echo`)؛ یک **گیت مخفی‌سازی مرکزی** بساز که همه‌ی شورت‌کدها اول آن را صدا بزنند
  (متاباکس per-post، قواعد سراسری، شرایط ووکامرس). اولویت‌ها را شفاف نگه‌دار؛ سراسری‌ترین گیت بالای تابع.
- **متاباکس:** ذخیره با `save_post` + nonce + `current_user_can` + چک `DOING_AUTOSAVE`.
- **AJAX:** `wp_ajax_{action}` (+ `nopriv` در صورت نیاز) با nonce و وایت‌لیست کلیدها؛ خروجی با `wp_send_json_success/error`.
- **منو:** `add_options_page` / `add_menu_page` با `manage_options` (یا قابلیت مناسب).

## ۸) سازگاری ووکامرس / HPOS (در صورت وجود)

- سازگاری HPOS را اعلام کن:

- قبل از استفاده، وجود `wc_get_product` / کلاس‌ها را چک کن تا بدون ووکامرس fatal ندهد.
- محصول متغیر: کمترین قیمت واریشن‌ها را در نظر بگیر؛ حالت‌های ناموجود/بدون‌قیمت/رایگان را جدا کن.


## نکته‌ی نهایی برای Claude

اگر بین «درست‌تر از نظر استاندارد» و «فقط همان چیزی که کاربر خواست» تعارض بود، **خواسته‌ی کاربر و scope پرامپت برنده است**؛
بهبود استاندارد را فقط پیشنهاد بده. صراحت در گزارش: بگو دقیقاً چه چیزهایی عوض شد، با چه اطمینانی، و چه چیزی تأییدنشده ماند.
ابهامی بود بپرس! 
بخاطر قطعی نت - افزونه به 2 قسمت تقسیم بکن و برای مرحله بعدی از من بپرس که ادامه بدم؟ - بعد تایید من: ادامه بده و در نهایت یکبار فایل اصلاحی دانلودی کامل بده
بهینه سازی کویریها را با ریسک پایین تغییر کد انجام بده که به مشکل نخوره