arraypress/wp-user-access

A lean WordPress library for user access control, roles, and capabilities

dev-main 2025-11-16 10:09 UTC

Requires

• php: >=7.4

GPL-2.0-or-later

• David Sherlock

• wordpress
• capabilities
• roles
• permissions
• rbac
• wp
• user-management
• access-control
• arraypress

README

A lean WordPress library for user access control, roles, and capabilities. Simple APIs for the permission management tasks you actually need in plugin development.

Features

• 🎯 Focused API - Just the methods you'll actually use
• 👤 User Checks - Simple permission and role verification
• 🔐 Role Management - Create, delete, and modify roles
• 💪 Capability Control - Add/remove capabilities from roles
• 📋 Form Options - Ready-to-use arrays for dropdowns
• 🔍 User Queries - Find users by role or capability

Requirements

• PHP 7.4 or later
• WordPress 5.0 or later

Installation

composer require arraypress/wp-user-access

Usage

User Class - Check and manage user permissions

use ArrayPress\WPUserAccess\User;

// Check roles and capabilities
if ( User::has_role( 'editor', $user_id ) ) {
    // User is an editor
}

if ( User::has_capability( 'edit_posts', $user_id ) ) {
    // User can edit posts
}

// Check multiple permissions (has ANY of these)
if ( User::has_any( ['administrator', 'editor', 'manage_options'], $user_id ) ) {
    // User has at least one permission
}

// Check multiple permissions (has ALL of these)
if ( User::has_all( ['edit_posts', 'upload_files'], $user_id ) ) {
    // User has all permissions
}

// Quick admin checks
if ( User::is_admin( $user_id ) ) {
    // User can manage options
}

if ( User::can_edit_others( $user_id ) ) {
    // User can edit others' posts
}

// Manage user roles
User::set_role( 'editor', $user_id );      // Replace all roles
User::add_role( 'author', $user_id );      // Add additional role
User::remove_role( 'subscriber', $user_id ); // Remove role

// Get user roles
$roles = User::get_roles( $user_id );

Role Class - Manage role capabilities

use ArrayPress\WPUserAccess\Role;

// Check if role exists
if ( Role::exists( 'shop_manager' ) ) {
    // Role exists
}

// Create custom role
$role = Role::create( 'shop_manager', 'Shop Manager', [
    'read'         => true,
    'edit_posts'   => true,
    'upload_files' => true,
] );

// Delete role (e.g., on plugin uninstall)
Role::delete( 'shop_manager' );

// Manage capabilities
Role::add_capability( 'editor', 'manage_shop' );
Role::remove_capability( 'editor', 'delete_pages' );

// Check role capabilities
if ( Role::has_capability( 'editor', 'edit_posts' ) ) {
    // Editor can edit posts
}

// Get all capabilities for a role
$capabilities = Role::get_capabilities( 'editor' );

Capability Class - Work with capabilities

use ArrayPress\WPUserAccess\Capability;

// Check if capability exists
if ( Capability::exists( 'manage_shop' ) ) {
    // Capability is registered
}

// Find which roles have a capability
$roles = Capability::get_roles_with( 'edit_posts' );
// Returns: ['administrator', 'editor', 'author']

Query Class - Find users

use ArrayPress\WPUserAccess\Query;

// Get users by role
$editors = Query::get_users_with_role( 'editor' );
$staff   = Query::get_users_with_role( ['editor', 'administrator'] );

// Get users by capability
$can_manage = Query::get_users_with_capability( 'manage_options' );

// Count users in a role
$count = Query::count_users_with_role( 'subscriber' );

// Get all roles or capabilities
$all_roles = Query::get_all_roles();
// Returns: ['administrator' => 'Administrator', 'editor' => 'Editor', ...]

$all_caps = Query::get_all_capabilities();
// Returns: ['edit_posts', 'publish_posts', 'upload_files', ...]

Options Class - Form helpers

use ArrayPress\WPUserAccess\Options;

// Get role options for dropdowns (simple format)
$roles = Options::get_roles();
// Returns: ['administrator' => 'Administrator', 'editor' => 'Editor', ...]

// Get role options in value/label format
$roles = Options::get_roles( ['format' => 'value_label'] );
// Returns: [['value' => 'editor', 'label' => 'Editor'], ...]

// Get capability options
$caps = Options::get_capabilities();
// Returns: ['edit_posts' => 'Edit Posts', 'publish_posts' => 'Publish Posts', ...]

// Get only editable roles (respects current user permissions)
$editable = Options::get_editable_roles();

Utils Class - Helper functions

use ArrayPress\WPUserAccess\Utils;

// Check if current user can edit another user
if ( Utils::current_user_can_edit_user( $user_id ) ) {
    // Show edit button
}

// Get user object (with fallback to current user)
$user = Utils::get_user( $user_id );

Common Patterns

Custom Post Type Permissions

// On activation - create role
Role::create( 'product_manager', 'Product Manager', [
    'read'                => true,
    'edit_products'       => true,
    'edit_others_products'=> true,
    'publish_products'    => true,
    'delete_products'     => true,
] );

// Add capabilities to existing roles
Role::add_capability( 'administrator', 'edit_products' );
Role::add_capability( 'editor', 'edit_products' );

Settings Page Access

// Check permissions
if ( ! User::is_admin() ) {
    wp_die( 'Access denied' );
}

// Or check specific capability
if ( ! User::has_capability( 'manage_shop' ) ) {
    wp_die( 'Access denied' );
}

User Edit Screen

// Get roles for dropdown
$roles = Options::get_editable_roles();
?>
<select name="role">
    <?php foreach ( $roles as $role => $name ) : ?>
        <option value="<?php echo esc_attr( $role ); ?>">
            <?php echo esc_html( $name ); ?>
        </option>
    <?php endforeach; ?>
</select>

Plugin Uninstall Cleanup

// Remove custom role
Role::delete( 'shop_manager' );

// Remove custom capabilities from all roles
foreach ( Query::get_all_roles() as $role => $name ) {
    Role::remove_capability( $role, 'manage_shop' );
}

Find Users for Notifications

// Notify all administrators
$admins = Query::get_users_with_capability( 'manage_options' );
foreach ( $admins as $user_id ) {
    wp_mail( /* send notification */ );
}

// Notify specific role
$managers = Query::get_users_with_role( 'shop_manager' );

Why This Library?

• Memorable API - You'll remember these methods in 6 months
• No Bloat - ~30 methods total, each one actually useful
• Clean Code - Consistent naming, proper types, clear docblocks
• Real-World Focus - Built for actual plugin development needs

License

GPL-2.0-or-later

Support

• Documentation
• Issue Tracker