تابع remove_role در وردپرس

تابع remove_role() در وردپرس برای حذف یک نقش کاربری (Role) از سیستم نقش‌ها و توانایی‌ها (Capabilities) استفاده می‌شود. این تابع معمولا در پلاگین‌ها یا زمان پاک‌سازی (uninstall/deactivate) به‌کار می‌رود تا نقش‌هایی که هنگام فعال‌سازی ایجاد شده‌اند، حذف شوند.

مکانیزم کار remove_role()

وردپرس نقش‌ها را در گزینهٔ پایگاه‌داده‌ای به نام wp_user_roles ذخیره می‌کند. remove_role() به‌طور مستقیم، ورودی مربوط به آن نقش را از ساختار نقش‌ها حذف می‌کند. توجه داشته باشید که این عمل روی متادیتای کاربران تأثیری مستقیم ندارد؛ یعنی کاربران همچنان مقدار نقش‌شان را در wp_usermeta خواهند داشت، اما آن نقش دیگر تعریف نشده و در نتیجه آن کاربران در عمل نقشی نخواهند داشت (یا سطح دسترسی‌شان صفر خواهد شد).

زمان استفاده مناسب

حذف نقش‌های اختصاصی‌ای که پلاگین شما هنگام فعال‌سازی ایجاد کرده است.
پاک‌سازی نقش‌ها هنگام حذف پلاگین (uninstall) برای جلوگیری از ایجاد بی‌نظمی در گزینه‌ها.
در محیط شبکه (Multisite) وقتی نقش‌ها در هر سایت جداگانه تنظیم شده‌اند و لازم است در هر بلاگ حذف شوند.

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

if ( ! function_exists( 'remove_role' ) ) {
    return;
}

// حذف نقش سفارشی "custom_manager"
remove_role( 'custom_manager' );

کد بالا نقش با شناسه custom_manager را از مجموعه نقش‌ها حذف می‌کند. پس از اجرا، نقش دیگر قابل دسترسی نخواهد بود، اما کاربران قبلی که این نقش به آن‌ها اختصاص یافته بود، هنوز متادیتای نقش را در دیتابیس دارند که بی‌اثر می‌شود.

حذف نقش در زمان غیرفعال‌سازی یا حذف پلاگین

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

register_deactivation_hook( __FILE__, 'my_plugin_deactivate' );
register_uninstall_hook( __FILE__, 'my_plugin_uninstall' );

function my_plugin_deactivate() {
    // اگر نیاز است فقط غیرفعال‌سازی، می‌توان حذف نکرد و فقط داده‌ها را نگه داشت
}

function my_plugin_uninstall() {
    // حذف نقش‌های ایجاد شده توسط پلاگین
    remove_role( 'my_plugin_role' );
}

در کد بالا، هنگام حذف کامل پلاگین (uninstall) تابع remove_role فراخوانی شده و نقش مربوطه حذف می‌شود. از register_deactivation_hook برای کارهای موقتی و از register_uninstall_hook برای پاک‌سازی نهایی استفاده کنید.

توجهات مهم و نکات امنیتی

قبل از حذف نقش‌ها، حتماً بررسی کنید که کاربران دارای آن نقش‌ها به نقش دیگری منتقل شده یا اطلاع‌رسانی شده‌اند. در غیر این صورت ممکن است حساب آن‌ها عملاً بلااستفاده شود.
از حذف نقش‌های سیستمی (مثل administrator، editor، subscriber) اجتناب کنید مگر اینکه کاملا بدانید چه می‌کنید.
در محیط شبکه (Multisite)، remove_role فقط برای سایت جاری اجرا می‌شود — اگر پلاگین به صورت Network-Activated باشد، باید برای هر بلاگ حلقه زده و با switch_to_blog نقش‌ها را حذف کنید.

مثال توسعه‌یافته: حذف نقش در همهٔ سایت‌های شبکه

function remove_role_networkwide( $role ) {
    if ( ! is_multisite() ) {
        remove_role( $role );
        return;
    }

    $sites = get_sites();
    foreach ( $sites as $site ) {
        switch_to_blog( $site->blog_id );
        remove_role( $role );
        restore_current_blog();
    }
}

// نمونهٔ فراخوانی
remove_role_networkwide( 'my_plugin_role' );

در این مثال، اگر وردپرس در حالت Multisite باشد، ابتدا فهرست سایت‌ها گرفته شده و سپس با switch_to_blog روی هر سایت نقش حذف می‌شود. پس از هر حذف، restore_current_blog فراخوانی می‌شود تا محیط به حالت قبلی بازگردد.

بهتر است به جای حذف کامل نقش، قابلیت‌ها را مدیریت کنید؟

گاهی لازم است نقش را کامل حذف نکنید و تنها برخی قابلیت‌ها را از نقش بردارید. برای این کار توابع add_cap و remove_cap مناسب هستند. حذف کامل نقش باعث می‌شود کاربران قبلی آن نقش دسترسی خود را از دست بدهند؛ اما حذف یک Capability می‌تواند کنترل دقیق‌تری فراهم کند.

$role = get_role( 'editor' );
if ( $role ) {
    // حذف قابلیت ویرایش برخی پست‌ها
    $role->remove_cap( 'edit_others_posts' );
}

کد بالا با get_role شیء نقش editor را می‌گیرد و سپس با remove_cap قابلیت مشخصی را کم می‌کند. این روش برای تغییر تدریجی و دقیق سطوح دسترسی مناسب‌تر است تا حذف کامل نقش.

جدول مقایسه توابع مرتبط

تابع	کاربرد
add_role()	ایجاد نقش جدید با مجموعه قابلیت‌ها
remove_role()	حذف کامل یک نقش از سیستم
get_role()	بازیابی شیء نقش برای اصلاح قابلیت‌ها
remove_cap()	حذف یک capability از یک نقش خاص

شیوهٔ ایمن برای جابجایی کاربران قبل از حذف نقش

// تغییر نقش کاربران از custom_manager به subscriber قبل از حذف
$args = array(
    'role' => 'custom_manager'
);
$users = get_users( $args );

foreach ( $users as $user ) {
    $user->set_role( 'subscriber' );
}

// حالا که کاربران منتقل شدند، نقش را حذف می‌کنیم
remove_role( 'custom_manager' );

در این کد ابتدا تمامی کاربران با نقش custom_manager گرفته شده، سپس با set_role به نقش جدید منتقل می‌شوند و در نهایت نقش حذف می‌شود. این روش تضمین می‌کند کاربران دسترسی خود را ناگهانی از دست ندهند.

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

remove_role() ابزار مفیدی برای پاک‌سازی نقش‌های پلاگین است، اما با احتیاط استفاده شود.
قبل از حذف، کاربران را منتقل یا اطلاع‌رسانی کنید و از حذف نقش‌های سیستمی اجتناب کنید.
برای تغییر توانایی‌ها، ابتدا consider کنید remove_cap یا add_cap مناسب‌تر است تا حذف کامل نقش.
در شبکه، حتماً نقش‌ها را در هر سایت پردازش کنید.

با رعایت نکات بالا می‌توانید از remove_role() به شکل امن و مناسب برای مدیریت نقش‌ها در پروژه‌های وردپرس استفاده کنید و از پیامدهای ناخواسته جلوگیری نمایید.

آیا این مطلب برای شما مفید بود ؟

خیر

بله