Block hooks only for certain user roles in WordPress

Understanding WordPress User Roles and Capabilities

WordPress has a built-in user role management system, which includes several default roles like Administrator, Editor, Author, Contributor, and Subscriber, each with predefined capabilities. Custom roles can also be created with tailored capabilities. Restricting block hooks based on user roles involves ensuring that certain hooks or blocks only execute for users with specific roles.

Capabilities define what users can do, such as editing posts or managing options, and actions/hooks can be conditionally applied by checking these roles or capabilities. Understanding this system is foundational before manipulating block hooks conditionally.

Blocking Hooks by User Role Using Conditional Checks

The simplest approach in code to block hooks for specific user roles is by checking the current user's role or capabilities within the hook callback. For example, to restrict a hook from running for certain roles, use the `current_user_can()` function or check user roles directly:

php
function custom_hook_for_specific_roles() {
    if ( ! current_user_can('editor') && ! current_user_can('administrator') ) {
        return; // Exit if user is not editor or administrator
    }
    // Code for allowed user roles only
}
add_action('init', 'custom_hook_for_specific_roles');

Alternatively, you can check for specific roles with a more detailed user object approach:

php
function block_hook_for_roles() {
    if ( is_user_logged_in() ) {
        $user = wp_get_current_user();
        $blocked_roles = array('subscriber', 'contributor'); // Roles to block
        if ( array_intersect($blocked_roles, $user->roles) ) {
            return; // Block hook execution for these roles
        }
        // Allowed roles execute hook code here
    }
}
add_action('init', 'block_hook_for_roles');

This method effectively blocks hook code for defined roles by returning early in the function if the user has a blocked role.

Restricting Gutenberg Blocks by User Role

In relation to the WordPress Block Editor (Gutenberg), one common use case is to restrict certain blocks from appearing or being editable by specific user roles. This is useful for simplifying the editor interface or enforcing content restrictions.

Using Plugins to Restrict Blocks by Role

Plugins like Conditional Blocks Pro provide an easy interface to restrict blocks' visibility based on user roles. After installing, users can select blocks in the editor, configure visibility or restriction rules, and define which roles can see or interact with those blocks. These plugins often support native and custom roles, membership plugins, WooCommerce roles, and user role editors.

Example steps include:
- Installing Conditional Blocks Pro.
- Selecting a block in the Gutenberg editor.
- Setting visibility conditions based on user roles.
- Configuring block actions (show/hide) depending on the user's role.

This method requires no coding and works seamlessly with most user role management tools.

Programmatic Hiding of Blocks

Developers can manually filter available blocks for certain user roles by using the `allowed_block_types` filter:

php
function restrict_blocks_by_role($allowed_blocks, $post) {
    if ( current_user_can('author') ) {
        // Allow only a restricted set of blocks for authors
        return array('core/paragraph', 'core/image', 'core/heading');
    }
    return $allowed_blocks; // For other roles, allow all blocks
}
add_filter('allowed_block_types', 'restrict_blocks_by_role', 10, 2);

This filter controls which blocks a user can see and use when editing content and can be customized per role.

Restricting Access to Pages or Posts in WordPress by Role

Besides restricting block visibility and hooks, WordPress sites often require restricting entire pages or posts from some users. This can be done through custom code or plugins.

Using Custom Meta and Hooks

With custom fields (e.g., Advanced Custom Fields plugin), you can tag posts/pages with restricted users or roles. In hook callbacks like `template_redirect`, check if the current user is allowed:

php
function restrict_page_access() {
    if ( is_singular() ) {
        global $post;
        $blocked_roles = get_post_meta( $post->ID, 'blocked_roles', true );
        if ( ! empty($blocked_roles) && is_user_logged_in() ) {
            $user = wp_get_current_user();
            if ( array_intersect( $blocked_roles, $user->roles ) ) {
                wp_die(__('You do not have permission to view this content.'));
            }
        }
    }
}
add_action('template_redirect', 'restrict_page_access');

This example blocks access to pages/posts for users with roles listed in custom meta.

Plugins for Content Restriction

Many membership and role management plugins recommend and support content restriction by user roles. For example, plugins like Restrict Content, Paid Memberships Pro, and MemberPress create custom user roles and integrate with block visibility plugins.

Creating Custom Roles and Applying Restrictions

Custom user roles can be created using either plugins like User Role Editor or with code:

php
add_role(
    'custom_role',
    __('Custom Role'),
    array(
        'read' => true,
        'edit_posts' => true,
        'delete_posts' => false,
    )
);

After creating custom roles, blocks and hooks can be restricted similarly by checking for these roles in the functions that output or enable hooks.

Block Restrictions in PublishPress Permissions

PublishPress Permissions, a popular plugin, offers role-based block restrictions with a detailed setup. It distinguishes between groups and user roles in blocking behavior, allowing fine-grained control over which roles can use certain blocks or post types.

The plugin provides "block" settings that allow blocking based on roles, although not always available for groups. It integrates well with site permissions management, enabling blocks or post edit permissions to be limited for certain roles.

Hide or Limit Blocks from Editor Based on Role

To prevent confusion or clutter in the Gutenberg editor, some tools or hooks allow hiding specific blocks for certain user roles. For example, a site might block the "Table" block for contributors or subscribers by filtering blocks visible in the block editor:

php
function filter_blocks_for_user_roles($allowed_blocks, $post) {
    if ( current_user_can('contributor') ) {
        // Remove specific blocks
        $allowed_blocks = array_filter($allowed_blocks, function($block) {
            return $block !== 'core/table';
        });
    }
    return $allowed_blocks;
}
add_filter('allowed_block_types', 'filter_blocks_for_user_roles', 10, 2);

This approach enhances user experience by simplifying the available blocks for less-privileged users.

Summary of Techniques for Block Hook User Role Restrictions

- Use `current_user_can()` and `wp_get_current_user()` inside hook callbacks to conditionally block hook execution by role.
- Use the `allowed_block_types` filter to restrict specific Gutenberg blocks by user roles.
- Employ custom meta fields and frontend hooks like `template_redirect` to restrict access to content by role.
- Create custom roles for tailored capability sets, then restrict blocks and hooks based on those roles.
- Utilize plugins such as Conditional Blocks Pro, PublishPress Permissions, and membership plugins to manage block visibility and content restriction without custom code.
- Customize the editor block list per role to simplify the editing experience and enforce role-based restrictions.

Further Reading and Resources

- The official WordPress block editor handbook provides guides on filters and hooks available in Gutenberg to modify the editor experience.
- Plugin documentation for Conditional Blocks Pro, User Role Editor, PublishPress Permissions, and Membership plugins provide detailed configuration steps for role-based visibility.
- WordPress Codex and Developer Resources explain `current_user_can()`, user roles, capabilities, and role creation.