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

تابع wp_update_user() یکی از توابع اصلی وردپرس برای به‌روزرسانی اطلاعات کاربران در برنامه است. این تابع برای ویرایش فیلدهای پایه کاربر (مانند ایمیل، نام نمایش، گذرواژه و غیره) استفاده می‌شود و در کنار توابع دیگری مثل update_user_meta() و WP_User API، نقش مهمی در مدیریت کاربران ایفا می‌کند.

خلاصه‌ای از عملکرد و خروجی

• ورودی: یک آرایه یا آبجکت حاوی فیلدهای کاربر (حداقل باید شناسه کاربر ID مشخص شود برای آپدیت).
• خروجی: شناسه عددی کاربر در صورت موفقیت یا شیء WP_Error در صورت بروز خطا.
• قابل استفاده: در بک‌اند، افزونه‌ها، قالب‌ها یا پردازش فرم‌ها (با بررسی‌های امنیتی و اعتبارسنجی).

پارامترهای متداول که می‌توانید آپدیت کنید

نکات امنیتی و اعتبارسنجی

• قبل از هر به‌روزرسانی از تابع current_user_can(‘edit_user’, $user_id) برای بررسی صلاحیت ویرایش استفاده کنید.
• ورودی‌ها را با توابع مربوطه مانند sanitize_email() یا sanitize_text_field() پاک‌سازی کنید.
• در فرم‌های فرانت‌اند حتماً nonce و بررسی آن را انجام دهید (wp_verify_nonce).
• خطاها را با is_wp_error() بررسی و پیام مناسب به کاربر نشان دهید.

مثال ساده: به‌روزرسانی نام نمایش و ایمیل

 $user_id,
  'user_email'   => sanitize_email( 'newemail@example.com' ),
  'display_name' => sanitize_text_field( 'نام جدید' )
);

$result = wp_update_user( $userdata );

if ( is_wp_error( $result ) ) {
  // مدیریت خطا
  $error_message = $result->get_error_message();
  error_log( 'User update failed: ' . $error_message );
} else {
  // موفقیت
  // $result برابر با شناسه کاربر است
  do_action( 'my_plugin_user_updated', $result );
}
?>

توضیح: در این مثال ابتدا شناسه کاربر مشخص می‌شود و سپس آرایه‌ای با فیلدهای قابل آپدیت به wp_update_user ارسال می‌شود. خروجی تابع بررسی می‌شود که آیا WP_Error بازگشته یا شناسه کاربر. از توابع sanitize_* برای پاک‌سازی ورودی‌ها استفاده شده است.

آپدیت گذرواژه (Password) — نکات مهم

 $user_id,
  'user_pass' => $new_pass
) );

if ( is_wp_error( $result ) ) {
  // خطا
} else {
  // گذرواژه به‌صورت خودکار هش می‌شود
}
?>

توضیح: اگر فیلد user_pass را مستقیم ارسال کنید، وردپرس آن را هش می‌کند و نیازی به هش کردن دستی نیست. با این وجود حتماً گذرواژه‌ها را از سمت کلاینت ایمن و در سرور بررسی کنید و قوانین پیچیدگی را اعمال کنید.

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

wp_update_user فقط فیلدهای اصلی را مدیریت می‌کند؛ برای متای دلخواه از update_user_meta() استفاده کنید:

 $user_id,
  'display_name' => 'نام جدید'
) );

// آپدیت متادیتا
update_user_meta( $user_id, 'phone_number', sanitize_text_field( '09121234567' ) );
?>

توضیح: در اغلب موارد ترکیب wp_update_user برای فیلدهای اصلی و update_user_meta برای داده‌های سفارشی بهترین راهکار است.

تغییر نقش کاربر (best practice)

بهتر است برای تغییر نقش از کلاس WP_User استفاده کنید تا رفتار دقیق‌تری داشته باشید:

set_role( 'editor' );
}
?>

توضیح: با set_role نقش‌های قبلی حذف و نقش جدید تعیین می‌شود. اگر بخواهید نقش اضافی اضافه کنید می‌توان از add_role یا add_cap استفاده کرد.

موارد کاربردی و سناریوها

• ویرایش اطلاعات پروفایل در پنل مدیریت.
• ۶ایجاد فرم تغییر اطلاعات در فرانت‌اند با nonce و اعتبارسنجی.
• اتوماتیک آپدیت پروفایل پس از ثبت سفارش یا تغییر وضعیت (مثلاً افزودن امتیاز یا سطح).
• یکپارچه‌سازی سیستم‌های خارجی: درگاه پرداخت یا CRM که نیاز به همگام‌سازی اطلاعات کاربری دارد.

چک‌لیست قبل از استفاده از wp_update_user

• آیا شناسه کاربر معتبر است؟
• آیا کاربری که اقدام می‌کند دسترسی ویرایش کاربر مورد نظر را دارد؟
• آیا داده‌ها پاک‌سازی و اعتبارسنجی شده‌اند؟
• مدیریت خطا و نمایش پیام مناسب پیاده‌سازی شده است؟

جمع‌بندی و توصیه‌های تکمیلی

wp_update_user یک ابزار قوی برای ویرایش اطلاعات کاربران در وردپرس است اما باید همراه با بررسی‌های امنیتی و پاک‌سازی ورودی‌ها استفاده شود. برای متادیتای سفارشی از update_user_meta استفاده کنید و برای تغییر نقش از کلاس WP_User بهره ببرید. همیشه خروجی تابع را با is_wp_error بررسی کنید تا خطاها به درستی مدیریت شوند.

در صورت نیاز به مثال‌های پیچیده‌تر (مثلاً فرم فرانت‌اند با AJAX و nonce یا همگام‌سازی با سیستم خارجی)، می‌توان نمونه‌های اختصاصی‌تر و امن‌سازی‌شده تهیه کرد.

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

ارسال