Role-Based Content in WordPress Without Membership Plugins

ate is loaded. This is the optimal point to intercept requests and redirect unauthorized users.

/**
 * Enforce access control on singular views.
 */
function enforce_singular_access(): void {
    if (!is_singular()) {
        return;
    }

    $post = get_post();
    if (!evaluate_content_visibility($post->ID)) {
        // Redirect to login with redirect_to parameter
        wp_safe_redirect(wp_login_url(get_permalink($post->ID)));
        exit;
    }
}
add_action('template_redirect', 'enforce_singular_access');

4. Inline Content Gating via Shortcodes

For granular control within post content, we implement shortcodes. This allows editors to hide specific sections based on user roles.

/**
 * Render content based on role requirements.
 * Usage: [role_gate roles="editor,subscriber"]Restricted text[/role_gate]
 */
function render_role_gated_block(array $atts, ?string $content = null): string {
    $atts = shortcode_atts(['roles' => ''], $atts, 'role_gate');
    
    if (empty($content)) {
        return '';
    }

    $required_roles = array_map('trim', explode(',', $atts['roles']));
    $user = wp_get_current_user();

    if (!$user->exists()) {
        return '';
    }

    if (!empty(array_intersect($required_roles, (array) $user->roles))) {
        return do_shortcode($content);
    }

    return '';
}
add_shortcode('role_gate', 'render_role_gated_block');

5. Editor Interface

Editors require a UI to define visibility policies. We add a meta box to the post editor screen.

/**
 * Register meta box for visibility configuration.
 */
function register_visibility_meta_box(): void {
    add_meta_box(
        'content_visibility_panel',
        'Access Control',
        'render_visibility_panel',
        ['post', 'page'],
        'side',
        'high'
    );
}
add_action('add_meta_boxes', 'register_visibility_meta_box');

/**
 * Render meta box content.
 */
function render_visibility_panel(WP_Post $post): void {
    wp_nonce_field('visibility_nonce_action', 'visibility_nonce_field');
    
    $policy = get_post_meta($post->ID, '_access_gate', true);
    $policy = is_array($policy) ? $policy : [];
    
    $roles = wp_roles()->roles;
    ?>
    <div class="visibility-controls">
        <label>
            <input type="checkbox" name="access_policy[]" value="anyone" 
                <?php checked(in_array('anyone', $policy)); ?>>
            Public Access
        </label>
        
        <label>
            <input type="checkbox" name="access_policy[]" value="unauthenticated" 
                <?php checked(in_array('unauthenticated', $policy)); ?>>
            Guests Only
        </label>
        
        <hr>
        <strong>Allowed Roles:</strong>
        <?php foreach ($roles as $role_key => $role_data): ?>
            <label>
                <input type="checkbox" name="access_policy[]" value="<?php echo esc_attr($role_key); ?>" 
                    <?php checked(in_array($role_key, $policy)); ?>>
                <?php echo esc_html($role_data['name']); ?>
            </label>
        <?php endforeach; ?>
    </div>
    <?php
}

/**
 * Persist visibility policy on post save.
 */
function persist_visibility_meta(int $post_id): void {
    if (!isset($_POST['visibility_nonce_field']) || 
        !wp_verify_nonce($_POST['visibility_nonce_field'], 'visibility_nonce_action')) {
        return;
    }

    if (defined('DOING_AUTOSAVE') && DOING_AUTOSAVE) {
        return;
    }

    if (!current_user_can('edit_post', $post_id)) {
        return;
    }

    if (isset($_POST['access_policy']) && is_array($_POST['access_policy'])) {
        $sanitized = array_map('sanitize_text_field', $_POST['access_policy']);
        update_post_meta($post_id, '_access_gate', $sanitized);
    } else {
        delete_post_meta($post_id, '_access_gate');
    }
}
add_action('save_post', 'persist_visibility_meta');

Pitfall Guide

Production implementations of content gating must address specific edge cases. The following pitfalls are derived from real-world deployment scenarios.

1. Query Explosion on Large Sites

   • Explanation: Iterating through all posts in pre_get_posts causes severe performance degradation on sites with thousands of posts.
   • Fix: Implement a transient cache for the accessible IDs list, or limit the query to specific post types/categories. For enterprise scale, consider a custom database table or Elasticsearch integration.

2. Cache Poisoning

   • Explanation: Page caching plugins may serve restricted content to unauthenticated users if the cache key does not vary by user role.
   • Fix: Configure your caching solution to exclude pages with _access_gate meta. Alternatively, use a cache variation based on user cookies or implement a "no-cache" header for restricted content.

3. Role vs. Capability Mismatch

   • Explanation: Roles are labels; capabilities are permissions. Relying solely on role slugs can break if roles are renamed or custom capabilities are used.
   • Fix: Map roles to capabilities internally, or allow policy definitions based on capabilities. Use user_can() for checks where possible.

4. Shortcode Leakage in Feeds

   • Explanation: Shortcodes may render in RSS feeds or REST API responses, exposing restricted content to scrapers.
   • Fix: Disable shortcodes in feeds using remove_filter('the_excerpt_rss', 'do_shortcode') and filter REST API responses to strip gated content.

5. Admin Lockout

   • Explanation: Logic errors in the evaluation function can inadvertently block administrators from accessing content.
   • Fix: Always include an explicit super-admin bypass at the start of the evaluation function. Test thoroughly with a secondary admin account.

6. Direct URL Bypass via Embeds

   • Explanation: WordPress embeds may bypass template_redirect checks, exposing content via oEmbed endpoints.
   • Fix: Hook into oembed_request and embed_template to enforce access checks. Return a 404 or redirect for restricted posts in embed contexts.

7. Meta Serialization Issues

   • Explanation: Storing complex data without validation can lead to corrupted meta values or security vulnerabilities.
   • Fix: Strictly sanitize input using sanitize_text_field and validate data types. Use update_post_meta with explicit type casting.

Production Bundle

Action Checklist

• Define visibility policy structure and meta key naming convention.
• Implement evaluate_content_visibility function with super-admin bypass.
• Hook apply_query_level_gating to pre_get_posts with safety checks.
• Hook enforce_singular_access to template_redirect for direct URL protection.
• Register meta box and save handler with nonce verification.
• Configure page caching exclusion rules for restricted content.
• Test shortcode behavior in feeds and REST API responses.
• Verify admin bypass functionality across all access points.

Decision Matrix

Configuration Template

Use this template to standardize role mappings and policy defaults across your project.

/**
 * Configuration constants for content gating.
 */
define('GATING_META_KEY', '_access_gate');
define('GATING_PUBLIC_FLAG', 'anyone');
define('GATING_GUEST_FLAG', 'unauthenticated');

/**
 * Default policy for new posts.
 * Returns array of allowed roles.
 */
function get_default_visibility_policy(): array {
    return [GATING_PUBLIC_FLAG];
}

/**
 * Map custom roles to capabilities if needed.
 */
function map_role_to_capabilities(string $role): array {
    $role_obj = get_role($role);
    return $role_obj ? array_keys($role_obj->capabilities) : [];
}

Quick Start Guide

1. Paste the Evaluator: Add evaluate_content_visibility to your theme's functions.php or a custom plugin.
2. Add Hooks: Include the pre_get_posts and template_redirect handlers.
3. Deploy UI: Add the meta box registration and render functions.
4. Test Access: Create a test post, set visibility to "Editor Only", and verify access as different user roles.
5. Configure Cache: Exclude posts with _access_gate meta from your caching layer.

This architecture provides a robust, performant solution for role-based content visibility. By leveraging WordPress core capabilities and adhering to production best practices, you can implement granular access control without the overhead of membership plugins.