arraypress/wp-roles-utils

A lean WordPress library for working with roles and capabilities

dev-main 2025-07-01 21:02 UTC

Requires

• php: >=7.4

GPL-2.0-or-later

• David Sherlock

• wordpress
• capabilities
• roles
• permissions
• rbac
• wp
• user-roles
• arraypress

README

A lightweight WordPress library for working with roles and capabilities. Provides clean APIs for role operations, capability management, and user-role assignments.

Features

• 🎯 Clean API: WordPress-style snake_case methods with consistent interfaces
• 🔐 Role Management: Create, check, and manage WordPress roles
• 💪 Capability Control: Add, remove, and check role capabilities
• 👥 User Assignment: Assign and manage user roles
• 📋 Form-Ready Options: Perfect value/label arrays for selects and forms
• 🔍 Search Functionality: Built-in role search with flexible options

Requirements

• PHP 7.4 or later
• WordPress 5.0 or later

Installation

composer require arraypress/wp-roles-utils

Basic Usage

Working with Single Roles

use ArrayPress\RolesUtils\Role;

// Get role object
$role = Role::get( 'editor' );

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

// Get role display name
$name = Role::get_display_name( 'editor' ); // "Editor"

// Role capabilities
$capabilities   = Role::get_capabilities( 'editor' );
$primitive_caps = Role::get_primitive_capabilities( 'editor' );

// Check if role has capability
if ( Role::has_capability( 'editor', 'edit_posts' ) ) {
	// Role has capability
}

// Add/remove capabilities
Role::add_capability( 'editor', 'custom_capability' );
Role::remove_capability( 'editor', 'custom_capability' );

// User-role assignments
Role::set_for_user( 'editor', 123 ); // Replace all roles
Role::add_to_user( 'author', 123 );  // Add additional role
Role::remove_from_user( 'contributor', 123 );

// Check user roles
if ( Role::user_has( 'editor', 123 ) ) {
	// User has editor role
}

$user_roles = Role::get_for_user( 123 );

// Multiple role checks
if ( Role::user_has_any( [ 'editor', 'administrator' ], 123 ) ) {
	// User has at least one role
}

if ( Role::user_has_all( [ 'editor', 'custom_role' ], 123 ) ) {
	// User has all specified roles
}

Working with Multiple Roles

use ArrayPress\RolesUtils\Roles;

// Get all roles
$role_names = Roles::get_names(); // ['editor' => 'Editor', ...]
$role_slugs = Roles::get_slugs(); // ['administrator', 'editor', ...]
$all_roles  = Roles::get(); // Full role data with capabilities

// Check which roles exist
$existing = Roles::exists( [ 'editor', 'custom_role', 'invalid' ] );

// Capability operations
$all_capabilities = Roles::get_all_capabilities();
$roles_with_cap   = Roles::get_with_capability( 'edit_posts' );
$common_caps      = Roles::get_common_capabilities( [ 'editor', 'author' ] );

// User operations
$editor_users     = Roles::get_users_with_roles( 'editor' );
$multi_role_users = Roles::get_users_with_roles( [ 'editor', 'author' ] );
$user_count       = Roles::count_users( 'administrator' );

// Get role options for forms (simple format by default)
$options = Roles::get_options();
// Returns: ['administrator' => 'Administrator', 'editor' => 'Editor', ...]

// Get options in value/label format
$options = Roles::get_options( [ 'format' => 'value_label' ] );
// Returns: [['value' => 'editor', 'label' => 'Editor'], ...]

// Include guest option
$options_with_guest = Roles::get_options( [ 'include_guest' => true ] );
// Returns: ['guest' => 'Guest', 'administrator' => 'Administrator', ...]

// Include guest with value/label format
$options_with_guest = Roles::get_options( [
	'include_guest' => true,
	'format'        => 'value_label'
] );
// Returns: [['value' => 'guest', 'label' => 'Guest'], ['value' => 'editor', 'label' => 'Editor'], ...]

// Custom guest label
$options = Roles::get_options( [
	'include_guest' => true,
	'guest_label'   => 'Visitor'
] );

// Search functionality
$search_results = Roles::search( 'edit' );
$search_options = Roles::search_options( 'admin' );

// Editable roles (respects current user permissions)
$editable_roles = Roles::get_editable();
$is_editable    = Roles::is_editable( 'editor' );

// Sanitize role input
$clean_roles = Roles::sanitize( [ 'editor', 'invalid', 'author' ] );

Role & Capability Management

// Check role capabilities
$editor_caps    = Role::get_capabilities( 'editor' );
$primitive_only = Role::get_primitive_capabilities( 'editor' );

// Modify role capabilities
Role::add_capability( 'editor', 'manage_widgets' );
Role::remove_capability( 'editor', 'edit_themes' );

// Find roles with specific capability
$roles_with_publish = Roles::get_with_capability( 'publish_posts' );

// Get all unique capabilities across roles
$all_caps = Roles::get_capabilities();

User Role Management

// Single user operations
Role::set_for_user( 'editor', 123 );     // Set single role (removes others)
Role::add_to_user( 'author', 123 );      // Add additional role
Role::remove_from_user( 'contributor', 123 );

// Check user roles
$has_role   = Role::user_has( 'editor', 123 );
$user_roles = Role::get_for_user( 123 );

// Multiple role checks
$has_any = Role::user_has_any( [ 'editor', 'admin' ], 123 );
$has_all = Role::user_has_all( [ 'editor', 'custom' ], 123 );

// Get users by roles
$editors = Roles::get_users_with_roles( 'editor' );
$staff   = Roles::get_users_with_roles( [ 'editor', 'administrator' ] );

Search & Options

// Search roles
$results = Roles::search( 'edit' ); // Roles containing "edit"
$options = Roles::search_options( 'admin' );

// Form options (simple format by default)
$select_options = Roles::get_options();
// Returns: ['administrator' => 'Administrator', 'editor' => 'Editor', ...]

// Value/label format for structured arrays
$structured_options = Roles::get_options( [ 'format' => 'value_label' ] );
// Returns: [['value' => 'editor', 'label' => 'Editor'], ...]

// With guest option
$with_guest = Roles::get_options( [ 'include_guest' => true ] );
// Returns: ['guest' => 'Guest', 'administrator' => 'Administrator', ...]

Key Features

• Value/Label Format: Perfect for forms and selects
• Search Functionality: Built-in role search
• Capability Management: Add, remove, and check capabilities
• User Assignment: Flexible user-role management
• Permission Aware: Respects current user's role editing permissions

Requirements

• PHP 7.4+
• WordPress 5.0+

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the GPL-2.0-or-later License.

Support

• Documentation
• Issue Tracker