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

تابع get_role() یکی از ابزارهای مفید برای کار با نقش‌ها (Roles) در وردپرس است. این تابع یک شیء از کلاس WP_Role را برمی‌گرداند که به شما اجازه می‌دهد قابلیت‌ها (Capabilities) را مشاهده یا تغییر دهید. در این مقاله به صورت جامع ساختار، کاربردها، مثال‌های عملی و نکات امنیتی مرتبط با get_role() را بررسی می‌کنیم.

چرا get_role() مهم است؟

مدیریت نقش‌ها و قابلیت‌ها بخش مهمی از کنترل دسترسی در سایت‌های وردپرس است. با استفاده از get_role() می‌توانید به صورت برنامه‌نویسی نقش‌ها را تغییر دهید، قابلیت جدید اضافه کنید یا قابلیت‌های موجود را حذف نمایید — بدون نیاز به افزونه‌های واسط.

خروجی و نوع بازگشتی

تابع get_role( $role_name ) یک شیء WP_Role یا مقدار null بازمی‌گرداند. پارامتر $role_name باید شناسه نقش باشد مثل ‘administrator’ یا ‘editor’.

متدها و ویژگی‌های مهم WP_Role

• $role->capabilities: آرایه‌ای از قابلیت‌ها و مقادیر بولی
• $role->add_cap( $cap ): افزودن قابلیت به نقش
• $role->remove_cap( $cap ): حذف قابلیت از نقش

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

1. دریافت شیء نقش و فهرست قابلیت‌ها

add_action('init', function() {
    $role = get_role('editor');
    if ( $role ) {
        foreach ( $role->capabilities as $cap => $grant ) {
            error_log( $cap . ' => ' . ($grant ? 'true' : 'false') );
        }
    }
});

توضیح: این کد در هوک init اجرا می‌شود، شیء نقش ‘editor’ را دریافت می‌کند و سپس تمام قابلیت‌ها را در log ثبت می‌کند. استفاده از init ضروری است چون نقش‌ها معمولا بعد از راه‌اندازی وردپرس قابل دسترس هستند.

2. افزودن Capability به یک نقش (مثال عملی)

add_action('init', function() {
    $role = get_role('author');
    if ( $role && ! $role->has_cap('edit_theme_options') ) {
        $role->add_cap('edit_theme_options');
    }
});

توضیح: در این مثال قابلیت edit_theme_options به نقش ‘author’ اضافه می‌شود، ولی قبل از اضافه کردن با has_cap بررسی می‌شود که از قبل وجود نداشته باشد. این الگو از افزودن تکراری جلوگیری می‌کند.

3. حذف Capability از نقش

add_action('init', function() {
    $role = get_role('subscriber');
    if ( $role && $role->has_cap('upload_files') ) {
        $role->remove_cap('upload_files');
    }
});

توضیح: اگر نقش ‘subscriber’ به اشتباه قابلیت upload_files داشته باشد، این کد آن را حذف می‌کند. دقت کنید که تغییرات نقش روی تمام کاربرانی که آن نقش را دارند تاثیر می‌گذارد.

تفاوت get_role() با توابع دیگر

• get_role(): روی نقش (Role) کار می‌کند و شیء WP_Role بازمی‌گرداند.
• get_userdata() / WP_User: اطلاعات کاربر را برمی‌گرداند؛ برای فهمیدن نقش‌های یک کاربر از $user->roles استفاده کنید.
• add_role(): یک نقش جدید می‌سازد. get_role برای دسترسی و ویرایش نقش‌های موجود کاربرد دارد.

نکات امنیتی و بهترین شیوه‌ها

• تغییر Capabilityها روی نقش‌ها روی تمام کاربران با آن نقش اثر می‌گذارد. قبل از اعمال تغییرات در محیط تولید، در محیط تست امتحان کنید.
• از has_cap یا بررسی وجود $role استفاده کنید تا از خطاهای احتمالی (مانند null) جلوگیری شود.
• برای تغییرات دائمی و کنترل شده، بهتر است کدهای تغییر نقش را داخل activation hook افزونه یا اسکریپتی که فقط یک‌بار اجرا می‌شود قرار دهید، نه در هر بار لود سایت.
• اگر قصد دارید قابلیت خاصی را فقط برای چند کاربر خاص اعمال کنید، بهتر است از متدهای WP_User::add_cap و remove_cap استفاده کنید تا به نقش‌ها دست نزنید.

الگوی امن برای اعمال تغییر تنها یک‌بار (مثال)

register_activation_hook( __FILE__, function() {
    $role = get_role('editor');
    if ( $role ) {
        $role->add_cap('manage_custom_reports');
    }
});

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

موارد احتیاط در محیط multisite

در حالت شبکه (Multisite) مدیریت نقش‌ها کمی متفاوت است. نقش‌ها معمولاً در سطح هر سایت تعریف می‌شوند و get_role برای سایت فعلی کار می‌کند. برای تغییر نقش‌ها در سایت‌های مختلف باید از context مناسب یا switch_to_blog استفاده کنید.

نمونه: لیست همه نقش‌ها و قابلیت‌ها

add_action('admin_init', function() {
    global $wp_roles;
    foreach ( $wp_roles->roles as $role_key => $role_info ) {
        $role = get_role( $role_key );
        if ( $role ) {
            echo '<h4>' . esc_html( $role_info['name'] ) . '</h4>';
            echo '<ul>';
            foreach ( $role->capabilities as $cap => $grant ) {
                echo '<li>' . esc_html( $cap ) . ' : ' . ($grant ? 'yes' : 'no') . '</li>';
            }
            echo '</ul>';
        }
    }
});

توضیح: این کد در صفحه مدیریت اجرا شده و همه نقش‌ها را از متغیر سراسری $wp_roles می‌گیرد و برای هر نقش، قابلیت‌ها را نمایش می‌دهد. دقت کنید که برای خروجی در فرانت یا admin باید esc_html یا توابع مشابه برای جلوگیری از XSS استفاده شود.

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

تابع get_role() ابزاری ساده اما قدرتمند برای دسترسی و مدیریت نقش‌ها در وردپرس است. با دریافت شیء WP_Role می‌توانید قابلیت‌ها را بخوانید، اضافه یا حذف کنید. برای امنیت و پایداری، تغییرات را کنترل‌شده و در زمان مناسب (مثلاً activation hook) اعمال کنید و همواره از بررسی وجود نقش و قابلیت قبل از تغییر استفاده کنید.

در صورت نیاز به مثال‌های سفارشی یا اسکریپت مشخص برای سایت خودتان می‌توانم کد متناسب با ساختار نقش‌ها و نیاز شما آماده کنم.

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

ارسال