manifest / ecommerce / woocommerce-order-status-descriptions

WooCommerce Order Status Descriptions

Add configurable descriptions to WooCommerce order statuses and display the current status description on admin order edit screens.

by Amirreza Shayesteh Far · github.com/amirrezashf/woocommerce-order-status-descriptions · website

★ 0stars

Install

Download source zip No release zip yet

This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.

Install straight from GitHub with WP-CLI:

wp plugin install https://github.com/amirrezashf/woocommerce-order-status-descriptions/archive/refs/heads/main.zip

No built-in updater. New versions won't appear under Dashboard → Updates. Install new releases yourself, or let Git Updater track the repository.

Readme github.com/amirrezashf/woocommerce-order-status-descriptions ↗

Add configurable administrative descriptions to WooCommerce order statuses and display the current status description on WooCommerce order edit screens.

Description

WooCommerce Order Status Descriptions lets administrators attach an internal explanation to every built-in or custom WooCommerce order status.

The description for the order's currently saved status is displayed in the WooCommerce admin order details section. This helps support, fulfillment, finance, and operations teams understand what each status means and what should happen next.

The plugin supports both classic WooCommerce order storage and High-Performance Order Storage.

Features

Dedicated settings page under WooCommerce
Supports all built-in WooCommerce statuses
Automatically detects compatible custom order statuses
Stores one multiline description per status
Displays the current status label and description on order edit screens
Search by status label or internal key
Hides empty descriptions by default
Optional fallback notice for statuses without descriptions
Secure settings form with nonce verification
Requires manage_options to edit descriptions
Sanitizes saved content and escapes output
Supports classic order storage
Supports WooCommerce HPOS
Loads assets only on relevant admin screens
Creates no custom database tables
Stores all descriptions in one non-autoloaded option
Single-file plugin architecture
GPL-3.0

How It Works

The plugin reads statuses from:

wc_get_order_statuses()

Status keys are normalized by removing the wc- prefix.

Example:

wc-processing

is stored as:

processing

When an order edit screen loads, the plugin:

Reads the saved order status.
Normalizes its key.
Finds the saved description.
Displays the status label and description in the order details section.

Settings Page

Open:

WooCommerce → Order Status Descriptions

The page includes:

All available order statuses
Status labels
Internal status keys
Search field
Multiline description fields
Description-state indicators
Responsive layout

Only users with manage_options can save changes.

Supported Statuses

The plugin supports:

Pending payment
Processing
On hold
Completed
Cancelled
Refunded
Failed
Compatible custom statuses

Custom statuses appear automatically when they are registered through WooCommerce-compatible APIs.

Display Behavior

By default, the description box appears only when a description exists for the current status.

The box includes:

Current status label
Saved administrative description
Multiline text support
Accessible role="note"

Data Storage

Descriptions are stored in one WordPress option:

wc_osd_status_descriptions

Example:

array(
    'processing' => 'Payment has been confirmed and the order is ready for fulfillment.',
    'completed'  => 'The order has been fully delivered and requires no further action.',
);

The option is stored with autoload disabled.

The plugin does not create:

Custom database tables
User metadata
Order metadata
Transients
Scheduled tasks
Log files

Requirements

PHP 7.4+
WordPress 6.0+
WooCommerce

Installation

Download the repository as ZIP.
Open Plugins → Add New Plugin → Upload Plugin.
Upload the ZIP file.
Install and activate the plugin.
Open WooCommerce → Order Status Descriptions.
Add descriptions and save.

Manual Installation

Extract the ZIP file.
Upload the plugin directory to:

wp-content/plugins/

Activate the plugin.
Configure descriptions under WooCommerce.

Usage Examples

Processing

Payment has been confirmed. The order should now be prepared and assigned to fulfillment.

On Hold

Do not continue fulfillment until payment or customer information has been verified.

Completed

The order has been delivered or fully fulfilled. No further operational action is required.

Security

Direct-file access protection
manage_options capability check
Nonce verification
Status-key validation
Input sanitization
Output escaping
No public AJAX endpoints
No custom REST API routes
No direct SQL queries
No external requests

Performance

The plugin loads:

Settings CSS and JavaScript only on its settings page
Order description CSS only on order edit screens
No frontend assets
No external dependencies

HPOS Compatibility

The plugin declares compatibility with WooCommerce High-Performance Order Storage.

It uses WooCommerce order objects and does not access order tables directly.

Filters

`wc_osd_descriptions`

Filters all saved descriptions:

add_filter(
    'wc_osd_descriptions',
    static function ( $descriptions ) {
        return $descriptions;
    }
);

`wc_osd_current_status_description`

Filters the description displayed for the current order:

add_filter(
    'wc_osd_current_status_description',
    static function ( $description, $status_key, $order ) {
        return $description;
    },
    10,
    3
);

`wc_osd_show_empty_description_notice`

Displays a fallback message for statuses without descriptions:

add_filter(
    'wc_osd_show_empty_description_notice',
    '__return_true'
);

Actions

`wc_osd_descriptions_saved`

Runs after descriptions are saved:

add_action(
    'wc_osd_descriptions_saved',
    static function ( $descriptions ) {
        // Optional integration or audit.
    }
);

Compatibility Notes

Custom order statuses must be registered before WooCommerce returns the status list.

If a status does not appear:

Confirm it is included in wc_get_order_statuses().
Confirm it appears in WooCommerce's original order status selector.
Confirm the status key is unique.

Troubleshooting

Description does not appear

Check:

A description exists for the current status.
The order is being edited in WooCommerce admin.
The current user can manage or edit orders.
Another plugin has not removed the target order-details hook.

Custom status does not appear in settings

Confirm the custom status exists in:

wc_get_order_statuses()

Empty description box is not shown

This is expected. Empty descriptions are hidden by default.

Use wc_osd_show_empty_description_notice to show a fallback message.

Changelog

1.0.0

Initial release
Added status-description settings page
Added secure settings persistence
Added status search
Added current-order status description box
Added custom status support
Added classic order screen support
Added HPOS support
Added filters and actions

License

GPL-3.0

Author

Amirreza Shayesteh Far

Website: https://amirrezaa.ir/
GitHub: https://github.com/amirrezashf
Repository: https://github.com/amirrezashf/WooCommerce-Order-Status-Descriptions

توضیحات وضعیت سفارش ووکامرس

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

توضیحات

افزونه WooCommerce Order Status Descriptions به مدیر سایت اجازه می‌دهد برای تمام وضعیت‌های پیش‌فرض و سفارشی ووکامرس توضیح داخلی ثبت کند.

توضیح وضعیت فعلی سفارش در بخش جزئیات سفارش نمایش داده می‌شود تا تیم پشتیبانی، عملیات، انبار، مالی و مدیریت دقیقاً بداند هر وضعیت چه معنایی دارد و اقدام بعدی چیست.

افزونه با ساختار کلاسیک سفارش‌ها و HPOS سازگار است.

قابلیت‌ها

صفحه تنظیمات اختصاصی زیرمنوی ووکامرس
پشتیبانی از وضعیت‌های پیش‌فرض
شناسایی خودکار وضعیت‌های سفارشی سازگار
ذخیره یک توضیح چندخطی برای هر وضعیت
نمایش عنوان و توضیح وضعیت فعلی در سفارش
جستجو میان عنوان و کلید وضعیت‌ها
مخفی کردن توضیح خالی به‌صورت پیش‌فرض
امکان نمایش پیام جایگزین برای توضیحات خالی
ذخیره امن با nonce
الزام دسترسی manage_options
پاک‌سازی ورودی و escaping خروجی
پشتیبانی از ساختار کلاسیک
پشتیبانی از HPOS
بارگذاری محدود فایل‌ها
بدون جدول اختصاصی
ذخیره همه توضیحات در یک option
ساختار تک‌فایلی
مجوز GPL-3.0

نحوه عملکرد

وضعیت‌ها از تابع زیر خوانده می‌شوند:

wc_get_order_statuses()

پیشوند wc- از کلید وضعیت حذف می‌شود.

مثال:

wc-processing

به شکل زیر ذخیره می‌شود:

processing

هنگام باز شدن سفارش:

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

صفحه تنظیمات

مسیر تنظیمات:

ووکامرس ← توضیحات وضعیت سفارش

صفحه شامل موارد زیر است:

تمام وضعیت‌های موجود
عنوان وضعیت
کلید داخلی وضعیت
فیلد جستجو
textarea توضیح
نشانگر ثبت یا عدم ثبت توضیح
طراحی واکنش‌گرا

فقط کاربران دارای manage_options می‌توانند تنظیمات را ذخیره کنند.

وضعیت‌های پشتیبانی‌شده

در انتظار پرداخت
در حال انجام
در انتظار بررسی
تکمیل‌شده
لغوشده
مستردشده
ناموفق
وضعیت‌های سفارشی سازگار

رفتار نمایش

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

باکس شامل:

عنوان وضعیت فعلی
توضیح مدیریتی
پشتیبانی از چند خط
ویژگی دسترس‌پذیری role="note"

ذخیره‌سازی داده

توضیحات در option زیر ذخیره می‌شوند:

wc_osd_status_descriptions

نمونه:

array(
    'processing' => 'پرداخت تأیید شده و سفارش آماده ارجاع به عملیات است.',
    'completed'  => 'سفارش به‌صورت کامل تحویل یا نهایی شده است.',
);

autoload این option غیرفعال است.

افزونه موارد زیر را ایجاد نمی‌کند:

جدول دیتابیس
user meta
order meta
transient
Cron
فایل log

پیش‌نیازها

PHP 7.4+
WordPress 6.0+
WooCommerce

نصب

repository را به‌صورت ZIP دانلود کنید.
وارد افزونه‌ها ← افزودن افزونه تازه ← بارگذاری افزونه شوید.
فایل ZIP را بارگذاری کنید.
افزونه را نصب و فعال کنید.
وارد ووکامرس ← توضیحات وضعیت سفارش شوید.
توضیحات را ثبت و ذخیره کنید.

نصب دستی

فایل ZIP را استخراج کنید.
پوشه افزونه را در مسیر زیر قرار دهید:

wp-content/plugins/

افزونه را فعال کنید.
توضیحات را در زیرمنوی ووکامرس تنظیم کنید.

نمونه استفاده

در حال انجام

پرداخت تأیید شده است. سفارش باید بررسی و برای اجرای فرایند آماده‌سازی به تیم مربوطه ارجاع شود.

در انتظار بررسی

تا زمان تأیید پرداخت یا تکمیل اطلاعات مشتری، پردازش سفارش ادامه پیدا نکند.

تکمیل‌شده

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

امنیت

جلوگیری از اجرای مستقیم فایل
بررسی manage_options
nonce
اعتبارسنجی کلید وضعیت
پاک‌سازی ورودی
escaping خروجی
بدون AJAX عمومی
بدون REST API اختصاصی
بدون SQL مستقیم
بدون درخواست خارجی

عملکرد

CSS و JavaScript تنظیمات فقط در همان صفحه
CSS سفارش فقط در صفحه ویرایش سفارش
بدون فایل frontend
بدون dependency خارجی

سازگاری با HPOS

افزونه سازگاری خود را با WooCommerce High-Performance Order Storage اعلام می‌کند.

تمام عملیات از طریق object رسمی سفارش انجام می‌شود.

فیلترها

`wc_osd_descriptions`

تغییر تمام توضیحات ذخیره‌شده:

add_filter(
    'wc_osd_descriptions',
    static function ( $descriptions ) {
        return $descriptions;
    }
);

`wc_osd_current_status_description`

تغییر توضیح نمایش داده‌شده:

add_filter(
    'wc_osd_current_status_description',
    static function ( $description, $status_key, $order ) {
        return $description;
    },
    10,
    3
);

`wc_osd_show_empty_description_notice`

نمایش پیام برای وضعیت بدون توضیح:

add_filter(
    'wc_osd_show_empty_description_notice',
    '__return_true'
);

اکشن‌ها

`wc_osd_descriptions_saved`

پس از ذخیره توضیحات اجرا می‌شود:

add_action(
    'wc_osd_descriptions_saved',
    static function ( $descriptions ) {
        // اتصال یا audit اختیاری.
    }
);

عیب‌یابی

توضیح نمایش داده نمی‌شود

بررسی کنید:

برای وضعیت فعلی توضیح ثبت شده باشد.
سفارش داخل پنل مدیریت باز شده باشد.
کاربر اجازه مدیریت سفارش را داشته باشد.
Hook مربوطه توسط افزونه دیگری حذف نشده باشد.

وضعیت سفارشی در تنظیمات نیست

بررسی کنید وضعیت داخل خروجی زیر وجود داشته باشد:

wc_get_order_statuses()

توضیح خالی نمایش داده نمی‌شود

این رفتار پیش‌فرض است.

برای نمایش پیام جایگزین از wc_osd_show_empty_description_notice استفاده کنید.

تاریخچه تغییرات

1.0.0

انتشار اولیه
صفحه تنظیمات توضیحات وضعیت
ذخیره امن تنظیمات
جستجو میان وضعیت‌ها
باکس توضیح وضعیت فعلی
پشتیبانی از وضعیت سفارشی
پشتیبانی از ساختار کلاسیک
پشتیبانی از HPOS
افزودن Filter و Action

مجوز

GPL-3.0

نویسنده

Amirreza Shayesteh Far

وب‌سایت: https://amirrezaa.ir/
گیت‌هاب: https://github.com/amirrezashf
مخزن افزونه: https://github.com/amirrezashf/WooCommerce-Order-Status-Descriptions