آموزش تابع wp_insert_comment() در وردپرس و کاربرد آن

تابع wp_insert_comment() یک تابع سطح پایین (low-level) در هستهٔ وردپرس است که برای درج برنامه‌نویسی یک نظر (comment) در جدول نظرات پایگاه‌داده استفاده می‌شود. این تابع به شما امکان می‌دهد که دیدگاه‌ها را از سمت سرور، اسکریپت‌ها، افزونه‌ها یا APIها بدون استفاده از فرم‌های استاندارد وردپرس اضافه کنید. در این مقاله رفتار، پارامترها، نکات امنیتی و مثال‌های عملی را بررسی می‌کنیم.

موقعیت استفاده — کی باید از wp_insert_comment() استفاده کنید؟

• درج خودکار نظرات از منابع خارجی (مثلاً واردسازی نظرات از سرویس دیگر).
• ایجاد کامنت از سرویس‌های batched یا cron job.
• افزونه‌هایی که به‌طور برنامه‌ای نظر می‌سازند و سپس متای اختصاصی یا پردازش‌های خاص انجام می‌دهند.

پارامترهای اصلی تابع

ورودی تابع یک آرایهٔ انجمنی از کلیدها است. جدول زیر مهم‌ترین کلیدها و مقادیر قابل انتظار را نشان می‌دهد:

مقدار بازگشتی و خطاها

تابع معمولاً یک عدد (شناسهٔ جدید نظر) بازمی‌گرداند. اگر پارامتر دوم $wp_error را true قرار دهید، در صورت خطا یک شیء WP_Error بازگردانده می‌شود که بهتر می‌توان خطاها را مدیریت کرد.

نمونهٔ پایه‌ای: درج یک نظر ساده

 $commentdata = array(
  'comment_post_ID' => 123,
  'comment_author' => 'Ali',
  'comment_author_email' => 'ali@example.com',
  'comment_author_url' => 'https://example.com',
  'comment_content' => 'این یک نظر تستی است.',
  'comment_type' => '',
  'user_id' => 0,
  'comment_approved' => 1,
);
$comment_id = wp_insert_comment( $commentdata );

توضیح: این قطعه کد یک آرایهٔ دادهٔ نظر می‌سازد و آن را به wp_insert_comment می‌دهد. در صورت موفقیت $comment_id شامل آی‌دی عددی جدید خواهد بود. در حالت واقعی باید مقادیر ورودی را قبل از ارسال پاک‌سازی کنید (sanitize).

مثال پیشرفته: پاک‌سازی، بررسی خطا و ارسال اعلان

 $commentdata = array(
  'comment_post_ID' => intval( $_POST['post_id'] ),
  'comment_author' => sanitize_text_field( $_POST['author'] ),
  'comment_author_email' => sanitize_email( $_POST['email'] ),
  'comment_author_url' => esc_url_raw( $_POST['url'] ),
  'comment_content' => wp_strip_all_tags( $_POST['comment'] ),
  'user_id' => get_current_user_id(),
  'comment_approved' => 0, // منتظر تایید
);

$comment_id = wp_insert_comment( $commentdata, true );

if ( is_wp_error( $comment_id ) ) {
    // ثبت خطا و بازگشت پیام مناسب
    error_log( 'Comment insert error: ' . $comment_id->get_error_message() );
} else {
    // اضافه کردن متا اختصاصی
    add_comment_meta( $comment_id, 'source', 'api' );
    // اطلاع‌رسانی به نویسندهٔ پست یا مدیر
    wp_notify_postauthor( $comment_id );
}

توضیح: در این مثال ورودی‌ها با توابع وردپرس پاک‌سازی شده و از حالت $wp_error = true استفاده شده تا در صورت بروز خطا یک WP_Error دریافت شود. بعد از درج، متای دلخواه اضافه و اعلان به نویسنده فرستاده می‌شود.

نکات امنیتی و بهترین‌عمل‌ها

• همیشه داده‌های ورودی را با sanitize_text_field، sanitize_email، esc_url_raw یا wp_strip_all_tags پاک‌سازی کنید.
• از nonce یا بررسی capability برای درخواست‌های AJAX/REST استفاده کنید تا ارسال‌های غیرمجاز مسدود شوند.
• اگر نظر از طرف کاربر واردشده است، مقدار user_id را مقداردهی کنید تا سیستم هویت را بشناسد.
• برای جلوگیری از اسپم، از توابعی مانند akismet_add_comment یا بررسی نرخ ارسال استفاده کنید.
• برای ارسال اعلان‌ها به مدیر یا نویسنده از wp_notify_postauthor و wp_notify_moderator استفاده کنید (wp_insert_comment به‌تنهایی اعلان‌ها را ارسال نمی‌کند).

تفاوت wp_insert_comment() با توابع سطح بالاتر

توابعی مانند wp_new_comment() پردازش‌های بیشتری انجام می‌دهند: اعتبارسنجی، فیلترها، ایجاد کوکی برای نویسنده و ارسال اعلان‌ها. اگر نیاز دارید تمام جریان معمولی ارسال نظر اجرا شود، بهتر است از wp_new_comment استفاده کنید. اما اگر می‌خواهید کنترل کامل روی داده و پردازش‌ها داشته باشید، wp_insert_comment مناسب‌تر است.

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

 // افزودن متا
add_comment_meta( $comment_id, 'rating', 5 );

// بروزرسانی متن نظر
wp_update_comment( array(
  'comment_ID'      => $comment_id,
  'comment_content' => 'متن نظر به‌روز شد.'
) );

توضیح: بعد از درج نظر می‌توانید متاها را با add_comment_meta ذخیره کنید و برای تغییر محتوای نظر از wp_update_comment استفاده کنید. همیشه آرایهٔ ورودی wp_update_comment شامل comment_ID باشد.

موارد عملکردی و بهینه‌سازی

• اگر در حجم بالا نظر درج می‌کنید، از batch processing و transactionهای دیتابیس (در سطح افزونه) استفاده کنید تا فشار کمتر شود.
• از hookهایی که بر عملکرد تاثیر می‌گذارند مانند comment_post، transition_comment_status و comment_post_redirect با احتیاط استفاده کنید تا در درج انبوه باعث کندی نشوند.

جمع‌بندی

تابع wp_insert_comment ابزار قدرتمندی برای درج برنامه‌نویسی نظرات در وردپرس است. با رعایت نکات امنیتی، پاک‌سازی داده‌ها و مدیریت وضعیت (تایید، اسپم، حذف) می‌توانید جریان تولید نظر را به‌صورت کاملاً سفارشی کنترل کنید. برای اجرای جریان کامل ارسال نظر (اعلان، کوکی، فیلترهای فرم) از توابع سطح بالاتر مانند wp_new_comment بهره ببرید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال