devLap

فهرست هوک های افزونه ووکامرس وردپرس با توضیحات 2026

php dev.to

راهنمای جامع هوک‌های ووکامرس (Actions & Filters)

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

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

هوک چیست و چه انواعی دارد؟

  • Action Hook (اکشن): در یک نقطهٔ خاص اجرا می‌شود و یک عمل را انجام می‌دهد (مثلاً چاپ یک متن). هیچ مقداری بازگردانده نمی‌شود.
  • Filter Hook (فیلتر): یک مقدار را دریافت می‌کند، آن را تغییر می‌دهد و بازمی‌گرداند (مثلاً تغییر متن یک دکمه یا فیلدهای فرم).

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

📌 نحوهٔ استفاده از هوک‌ها 

// اتصال یک تابع به Action
add_action( 'woocommerce_before_add_to_cart_button', 'my_custom_action' );
function my_custom_action() {
    echo '<p>✓ ارسال رایگان برای این محصول</p>';
}

// اتصال یک تابع به Filter
add_filter( 'woocommerce_product_single_add_to_cart_text', 'my_custom_button_text' );
function my_custom_button_text( $text ) {
    return 'خرید فوری';
}
Enter fullscreen mode Exit fullscreen mode

کدها را در فایل functions.php قالب فرزند (Child Theme) یا یک افزونهٔ اختصاصی قرار دهید.

🛍️ ۱. هوک‌های صفحهٔ فروشگاه و آرشیو محصولات

این هوک‌ها در صفحات فروشگاه، دسته‌بندی‌ها، برچسب‌ها و نتایج جستجو اجرا می‌شوند.

Action Hooks (اکشن‌ها)

هوک (Hook) توضیح فارسی
woocommerce_before_main_content قبل از محتوای اصلی تمام صفحات ووکامرس (باز کردن wrapper اصلی).
woocommerce_after_main_content بعد از محتوای اصلی (بستن wrapper).
woocommerce_archive_description نمایش توضیحات دسته یا فروشگاه.
woocommerce_before_shop_loop قبل از شروع لیست محصولات (جایگاه بنر، ابزار مرتب‌سازی).
woocommerce_before_shop_loop_item در ابتدای هر کارت محصول در حلقه (باز شدن تگ <li>).
woocommerce_before_shop_loop_item_title قبل از عنوان محصول در کارت (جایگاه تصویر).
woocommerce_shop_loop_item_title محل رندر شدن عنوان محصول.
woocommerce_after_shop_loop_item_title بعد از عنوان محصول (جایگاه قیمت و امتیاز).
woocommerce_after_shop_loop_item انتهای کارت محصول (دکمهٔ افزودن به سبد، بستن تگ <li>).
woocommerce_after_shop_loop بعد از اتمام لیست محصولات (صفحه‌بندی).
woocommerce_no_products_found هنگامی که هیچ محصولی یافت نشود.
woocommerce_before_subcategory قبل از نمایش هر زیردسته.
woocommerce_before_subcategory_title قبل از عنوان زیردسته.
woocommerce_shop_loop_subcategory_title محل عنوان زیردسته.
woocommerce_after_subcategory_title بعد از عنوان زیردسته.
woocommerce_after_subcategory بعد از نمایش زیردسته.
woocommerce_product_loop_start قبل از شروع حلقهٔ محصولات (باز کردن تگ <ul>).
woocommerce_product_loop_end بعد از پایان حلقه (بستن تگ <ul>).

Filter Hooks (فیلترها)

هوک توضیح فارسی
loop_shop_per_page تغییر تعداد محصولات در هر صفحه از آرشیو.
loop_shop_columns تغییر تعداد ستون‌های نمایش محصولات.
woocommerce_product_loop_title تغییر عنوان محصول در حلقه.
woocommerce_loop_add_to_cart_link تغییر HTML دکمهٔ "افزودن به سبد خرید" در حلقه.
woocommerce_loop_add_to_cart_args فیلتر آرگومان‌های دکمهٔ افزودن به سبد در حلقه.
woocommerce_product_add_to_cart_text تغییر متن دکمهٔ خرید در صفحات آرشیو.

📄 ۲. هوک‌های صفحهٔ تک محصول

این هوک‌ها ساختار و محتوای صفحهٔ محصول (Single Product) را کنترل می‌کنند.

Action Hooks

هوک توضیح فارسی
woocommerce_before_single_product قبل از بارگذاری کامل صفحهٔ محصول.
woocommerce_before_single_product_summary قبل از بخش خلاصهٔ محصول (معمولاً جای گالری تصاویر).
woocommerce_single_product_summary بخش اصلی خلاصهٔ محصول (عنوان، قیمت، توضیح، دکمه خرید).
woocommerce_before_add_to_cart_form قبل از فرم افزودن به سبد خرید.
woocommerce_before_add_to_cart_button قبل از دکمهٔ افزودن به سبد.
woocommerce_before_add_to_cart_quantity قبل از فیلد تعداد.
woocommerce_after_add_to_cart_quantity بعد از فیلد تعداد.
woocommerce_after_add_to_cart_button بعد از دکمهٔ افزودن به سبد.
woocommerce_after_add_to_cart_form بعد از کل فرم افزودن به سبد.
woocommerce_product_thumbnails محل نمایش تصاویر بندانگشتی گالری.
woocommerce_before_variations_form قبل از فرم انتخاب متغیرها (محصول متغیر).
woocommerce_after_variations_form بعد از فرم متغیرها.
woocommerce_product_meta_start ابتدای بخش متای محصول (دسته‌ها، برچسب‌ها).
woocommerce_product_meta_end انتهای متا.
woocommerce_after_single_product_summary بعد از خلاصهٔ اصلی (جایگاه تب‌ها و محصولات مرتبط).
woocommerce_after_single_product انتهای کامل صفحه.

اولویت‌بندی المان‌های داخل woocommerce_single_product_summary

اولویت محتوای پیش‌فرض
5 عنوان محصول
10 امتیازدهی و قیمت
20 توضیح کوتاه
30 دکمهٔ افزودن به سبد خرید
40 متادیتا (شناسه، دسته‌ها)
50 دکمه‌های اشتراک‌گذاری

با استفاده از پارامتر اولویت می‌توانید محتوای دلخواه را دقیقاً بین این بخش‌ها قرار دهید:

add_action( 'woocommerce_single_product_summary', 'my_custom_info', 25 );
function my_custom_info() {
    echo '<p style="color:red;">فقط ۲ عدد در انبار باقی مانده</p>';
}
Enter fullscreen mode Exit fullscreen mode

Filter Hooks

هوک توضیح فارسی
woocommerce_product_tabs فیلتر آرایهٔ تب‌های محصول (افزودن، حذف، تغییر ترتیب تب‌ها).
woocommerce_product_single_add_to_cart_text تغییر متن دکمهٔ خرید در صفحه محصول.
woocommerce_product_description_heading تغییر عنوان تب "توضیحات".
woocommerce_product_description_tab_title عنوان تب توضیحات.
woocommerce_product_reviews_tab_title عنوان تب نظرات.
woocommerce_product_additional_information_heading عنوان بخش "اطلاعات بیشتر".
woocommerce_product_additional_information_tab_title عنوان تب اطلاعات بیشتر.
woocommerce_output_related_products_args تغییر آرگومان‌های محصولات مرتبط (تعداد، ستون‌ها).
woocommerce_related_products_columns تعداد ستون‌های محصولات مرتبط.
woocommerce_upsell_display نمایش محصولات پیشنهادی (upsells).
woocommerce_get_price_html تغییر HTML نمایش قیمت (در تمام بخش‌ها).

🛒 ۳. هوک‌های سبد خرید

Action Hooks

هوک توضیح فارسی
woocommerce_before_cart قبل از کل صفحهٔ سبد خرید.
woocommerce_before_cart_table قبل از جدول سبد خرید.
woocommerce_before_cart_contents قبل از محتوای ردیف‌های محصولات.
woocommerce_cart_contents داخل ردیف‌های سبد خرید (مناسب برای افزودن ستون جدید).
woocommerce_after_cart_contents بعد از ردیف‌ها.
woocommerce_after_cart_table بعد از جدول سبد خرید.
woocommerce_cart_collaterals بخش جانبی (جمع‌بندی سبد، کد تخفیف).
woocommerce_before_cart_collaterals قبل از بخش جانبی.
woocommerce_before_cart_totals قبل از جدول جمع کل.
woocommerce_cart_totals داخل جدول جمع کل.
woocommerce_after_cart_totals بعد از جدول جمع کل.
woocommerce_after_cart_collaterals بعد از بخش جانبی.
woocommerce_after_cart انتهای صفحه.
woocommerce_cross_sell_display نمایش محصولات cross-sell (پیشنهادهای متقابل).
woocommerce_cart_is_empty وقتی سبد خرید خالی باشد.

Filter Hooks

هوک توضیح فارسی
woocommerce_cart_item_thumbnail تغییر تصویر بندانگشتی آیتم در سبد.
woocommerce_cart_item_name تغییر نام محصول در ردیف سبد.
woocommerce_cart_item_price تغییر قیمت واحد هر آیتم.
woocommerce_cart_item_quantity تغییر فیلد تعداد محصول.
woocommerce_cart_item_subtotal تغییر جمع جزء هر آیتم.
woocommerce_cross_sells_columns تعداد ستون‌های محصولات cross-sell.
woocommerce_add_to_cart_redirect تغییر مسیر پس از افزودن به سبد.
woocommerce_add_cart_item_data افزودن دادهٔ دلخواه به آیتم سبد (قبل از اضافه شدن).
woocommerce_return_to_shop_redirect تغییر لینک دکمهٔ "بازگشت به فروشگاه" در سبد خالی.
woocommerce_cart_shipping_method_full_label تغییر متن و نحوهٔ نمایش روش‌های حمل و نقل به همراه قیمت.

🧾 ۴. هوک‌های تسویه حساب

Action Hooks

هوک توضیح فارسی
woocommerce_before_checkout_form قبل از فرم تسویه حساب.
woocommerce_checkout_before_customer_details قبل از بخش اطلاعات مشتری (صورتحساب/حمل).
woocommerce_checkout_billing بخش فیلدهای صورتحساب.
woocommerce_checkout_shipping بخش فیلدهای حمل و نقل.
woocommerce_checkout_after_customer_details بعد از اطلاعات مشتری.
woocommerce_checkout_before_order_review قبل از بخش مرور سفارش.
woocommerce_checkout_order_review خود بخش مرور سفارش (محصولات، جمع کل، درگاه‌ها).
woocommerce_checkout_after_order_review بعد از مرور سفارش.
woocommerce_review_order_before_payment قبل از گیت‌وی‌های پرداخت.
woocommerce_review_order_after_payment بعد از گیت‌وی‌ها.
woocommerce_review_order_before_submit قبل از دکمهٔ ثبت سفارش.
woocommerce_review_order_after_submit بعد از دکمهٔ ثبت سفارش.
woocommerce_after_checkout_form انتهای فرم.
woocommerce_checkout_process هنگام اعتبارسنجی و ثبت سفارش (مناسب برای بررسی فیلدهای سفارشی).
woocommerce_checkout_update_order_review هنگام به‌روزرسانی بخش مرور سفارش (Ajax).
woocommerce_before_checkout_coupon_form قبل از فرم کوپن در تسویه حساب.
woocommerce_applied_coupon پس از اعمال موفق کوپن.
woocommerce_removed_coupon پس از حذف کوپن.

Filter Hooks

هوک توضیح فارسی
woocommerce_checkout_fields قدرتمندترین فیلتر برای تغییر تمام فیلدهای فرم (حذف، جابجایی، اجباری/اختیاری).
woocommerce_billing_fields فیلتر فقط فیلدهای صورتحساب.
woocommerce_shipping_fields فیلتر فقط فیلدهای حمل و نقل.
woocommerce_default_address_fields فیلدهای پیش‌فرض آدرس (مشترک بین بیلینگ و شیپینگ).
woocommerce_checkout_get_value تغییر مقدار پیش‌فرض یک فیلد.
woocommerce_order_button_text تغییر متن دکمهٔ "ثبت سفارش".
woocommerce_available_payment_gateways فیلتر لیست درگاه‌های پرداخت در دسترس.
woocommerce_cod_process_payment_order_status تغییر وضعیت سفارش برای روش پرداخت در محل.

مثال: غیرضروری کردن فیلد تلفن در تسویه حساب 

add_filter( 'woocommerce_checkout_fields', 'custom_override_checkout_fields' );
function custom_override_checkout_fields( $fields ) {
    $fields['billing']['billing_phone']['required'] = false;
    return $fields;
}
Enter fullscreen mode Exit fullscreen mode

📦 ۵. هوک‌های سفارش‌ها و صفحه تشکر

Action Hooks

هوک توضیح فارسی
woocommerce_new_order به‌محض ایجاد سفارش جدید (قبل از ذخیره‌سازی کامل).
woocommerce_checkout_order_processed بلافاصله پس از پردازش موفق سفارش و ایجاد آبجکت سفارش.
woocommerce_thankyou صفحهٔ تشکر پس از خرید (موفق یا ناموفق). پارامتر $order_id را دریافت می‌کند.
woocommerce_thankyou_{payment_method} صفحه تشکر مخصوص یک روش پرداخت (مثلاً woocommerce_thankyou_cod).
woocommerce_before_thankyou قبل از محتوای صفحه تشکر.
woocommerce_view_order هنگام نمایش یک سفارش در حساب کاربری.
woocommerce_order_details_before_order_table قبل از جدول جزئیات سفارش.
woocommerce_order_details_after_order_table بعد از جدول جزئیات.
woocommerce_order_details_before_customer_details قبل از اطلاعات مشتری در جزئیات سفارش.
woocommerce_order_details_after_customer_details بعد از اطلاعات مشتری.
woocommerce_order_status_changed وقتی وضعیت سفارش تغییر کند. پارامترها: $order_id, وضعیت قبلی, وضعیت جدید.
woocommerce_order_status_{status} زمانی که سفارش به وضعیت خاصی برسد (مثلاً woocommerce_order_status_completed).
woocommerce_payment_complete بعد از تکمیل موفق پرداخت.
woocommerce_before_order_object_save قبل از ذخیرهٔ آبجکت سفارش.
woocommerce_after_order_object_save بعد از ذخیرهٔ آبجکت سفارش.

Filter Hooks

هوک توضیح فارسی
woocommerce_order_number تغییر شماره سفارش نمایش داده شده.
woocommerce_get_order_item_totals تغییر ردیف‌های جمع‌بندی سفارش (قیمت کل، حمل و نقل…).
woocommerce_my_account_my_orders_actions تغییر دکمه‌های قابل انجام برای سفارشات در حساب کاربری.

👤 ۶. هوک‌های حساب کاربری و ورود/ثبت‌نام

Action Hooks

هوک توضیح فارسی
woocommerce_account_navigation منوی ناوبری حساب کاربری.
woocommerce_before_account_navigation قبل از منوی حساب.
woocommerce_after_account_navigation بعد از منوی حساب.
woocommerce_account_dashboard داشبورد حساب کاربری.
woocommerce_before_account_orders قبل از جدول سفارشات.
woocommerce_after_account_orders بعد از جدول سفارشات.
woocommerce_before_account_downloads قبل از بخش دانلودها.
woocommerce_before_edit_account_form قبل از فرم ویرایش حساب.
woocommerce_account_content محتوای اصلی صفحات حساب کاربری.
woocommerce_login_form_start ابتدای فرم ورود.
woocommerce_login_form_end انتهای فرم ورود.
woocommerce_register_form_start ابتدای فرم ثبت‌نام.
woocommerce_register_form_end انتهای فرم ثبت‌نام.
woocommerce_created_customer پس از ایجاد کاربر جدید.

Filter Hooks

هوک توضیح فارسی
woocommerce_account_menu_items تغییر آیتم‌های منوی حساب کاربری (نام، ترتیب، لینک).
woocommerce_my_account_my_orders_columns ستون‌های جدول سفارش‌های من.
woocommerce_login_redirect تغییر مسیر پس از ورود موفق.

📧 ۷. هوک‌های ایمیل‌ها

Action Hooks

هوک توضیح فارسی
woocommerce_email_header هدر ایمیل‌های ووکامرس.
woocommerce_email_footer فوتر ایمیل‌ها.
woocommerce_email_before_order_table قبل از جدول محصولات در ایمیل.
woocommerce_email_after_order_table بعد از جدول محصولات.
woocommerce_email_order_details بخش جزئیات سفارش.
woocommerce_email_customer_details بخش اطلاعات مشتری.
woocommerce_email_order_meta محل نمایش متاهای سفارش.
woocommerce_email_sent پس از ارسال موفق ایمیل.

Filter Hooks

هوک توضیح فارسی
woocommerce_email_subject_{class} تغییر موضوع ایمیل (مثلاً woocommerce_email_subject_new_order).
woocommerce_email_heading_{class} تغییر عنوان ایمیل.
woocommerce_email_styles فیلتر استایل‌های درون‌خطی (inline) ایمیل.
woocommerce_email_footer_text تغییر متن فوتر ایمیل.

🏗️ ۸. هوک‌های محصولات، قیمت‌ها و تخفیف‌ها

Action Hooks

هوک توضیح فارسی
woocommerce_product_options_general_product_data در صفحهٔ ویرایش محصول، بخش "داده‌های عمومی" (برای افزودن فیلدهای سفارشی).
woocommerce_process_product_meta هنگام ذخیرهٔ متاباکس‌های محصول.

Filter Hooks

هوک توضیح فارسی
woocommerce_get_price_html تغییر HTML نمایش قیمت (قبلاً هم ذکر شد).
woocommerce_product_get_price قیمت محصول.
woocommerce_product_get_regular_price قیمت اصلی.
woocommerce_product_get_sale_price قیمت حراج.
woocommerce_get_price_excluding_tax قیمت بدون مالیات.
woocommerce_get_price_including_tax قیمت با مالیات.
woocommerce_currency_symbol تغییر نماد ارز (مثلاً "تومان").
woocommerce_format_sale_price فرمت نمایش قیمت حراج.
woocommerce_product_is_in_stock وضعیت موجودی (true/false).
woocommerce_product_get_stock_quantity تعداد موجودی.
woocommerce_product_get_stock_status وضعیت موجودی (instock/outofstock).
woocommerce_get_availability متن و کلاس موجودی.

⚙️ ۹. هوک‌های متفرقه و پیشرفته

هوک نوع توضیح فارسی
woocommerce_init Action پس از بارگذاری هستهٔ ووکامرس (مناسب برای کلاس‌های شخص ثالث).
woocommerce_loaded Action پس از آماده‌سازی کامل ووکامرس.
woocommerce_product_query Action تغییر کوئری اصلی حلقهٔ محصولات (برای فیلتر/مرتب‌سازی سفارشی).
woocommerce_shortcode_before_product_loop Action قبل از حلقهٔ محصولات در شورت‌کدها.
woocommerce_shortcode_after_product_loop Action بعد از حلقه.
woocommerce_pagination Action صفحه‌بندی سفارشی.
woocommerce_before_template_part Action قبل از بارگذاری هر قالب جزئی (template part). پارامترها: نام قالب، مسیر.
woocommerce_after_template_part Action بعد از قالب جزئی.
woocommerce_get_image_size_{size} Filter تغییر اندازهٔ تصاویر (مثلاً woocommerce_get_image_size_thumbnail).
woocommerce_placeholder_img_src Filter تغییر تصویر جایگزین (placeholder).
wc_product_attributes Filter فیلتر لیست صفات محصول.
woocommerce_add_error Filter فیلتر اعلان‌های خطا (قرمز).
woocommerce_add_notice Filter فیلتر اعلان‌های موفقیت/اطلاع (سبز/آبی).
woocommerce_breadcrumb_defaults Filter تغییر آرگومان‌های breadcrumbs (جداکننده، متن خانه).
woocommerce_cart_calculate_fees Action افزودن هزینه‌های اضافی به سبد خرید.
woocommerce_ajax_added_to_cart Action پس از افزودن به سبد از طریق Ajax.
woocommerce_cart_updated Action پس از به‌روزرسانی سبد خرید.
woocommerce_before_shipping_calculator Action قبل از ماشین حساب حمل و نقل در سبد.
woocommerce_after_shipping_calculator Action بعد از ماشین حساب.
woocommerce_before_get_current_promotions Action قبل از دریافت تبلیغات فعال.
woocommerce_after_get_current_promotions Action بعد از دریافت تبلیغات.
woocommerce_rest_insert_product Action هنگام ایجاد/به‌روزرسانی محصول از طریق REST API.
woocommerce_rest_insert_order Action سفارش از طریق REST API.
woocommerce_rest_insert_customer Action مشتری از طریق REST API.

https://www.intellsoft.ir/

Source: dev.to

arrow_back Back to Tutorials