arraypress/wp-capabilities-utils

A lean WordPress library for working with capabilities and permissions

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

Requires

• php: >=7.4

GPL-2.0-or-later

• David Sherlock

• security
• wordpress
• capabilities
• permissions
• wp
• access-control
• arraypress

README

A lightweight WordPress library for working with capabilities and permissions. Provides clean APIs for capability analysis, user permission auditing, and capability management.

Features

• 🎯 Clean API: WordPress-style snake_case methods with consistent interfaces
• 🔍 Capability Analysis: System-wide capability discovery and categorization
• 👥 User Comparisons: Compare and analyze user permissions
• 📊 Permission Auditing: Find users/roles with specific capabilities
• 📋 Form-Ready Options: Perfect value/label arrays for selects and forms
• 🔍 Search Functionality: Built-in capability search

Requirements

• PHP 7.4 or later
• WordPress 5.0 or later

Installation

composer require arraypress/wp-capabilities-utils

Basic Usage

Working with Single Capabilities

use ArrayPress\CapabilitiesUtils\Capability;

// Check if capability exists
if ( Capability::exists( 'edit_posts' ) ) {
	// Capability exists
}

// Check user capability
if ( Capability::user_has( 'edit_posts', 123 ) ) {
	// User has capability
}

// Format capability name for display
$formatted = Capability::format_name( 'edit_posts' ); // "Edit Posts"

// Get capability type/category
$type = Capability::get_type( 'edit_posts' ); // "post"

// Find users with capability
$user_ids = Capability::get_users_with( 'edit_posts' );

// Check which users from list have capability
$filtered_users = Capability::users_have( 'edit_posts', [ 1, 2, 3 ] );

// Find roles with capability
$roles = Capability::get_roles_with( 'edit_posts' ); // ['editor', 'administrator']

// Check if capability is primitive
if ( Capability::is_primitive( 'edit_posts' ) ) {
	// Not a meta capability
}

// Get as option array
$option = Capability::get_option( 'edit_posts' );
// Returns: ['value' => 'edit_posts', 'label' => 'Edit Posts']

Working with Multiple Capabilities

use ArrayPress\CapabilitiesUtils\Capabilities;

// Get all capabilities
$all_caps = Capabilities::get();

// Check which capabilities exist
$existing = Capabilities::exists( [ 'edit_posts', 'invalid_cap', 'publish_posts' ] );

// Get primitive capabilities only
$primitive = Capabilities::get_primitive();

// Get capabilities by type
$post_caps = Capabilities::get_by_type( 'post' );
$user_caps = Capabilities::get_by_type( 'user' );

// User capability operations
$user_caps      = Capabilities::get_for_user( 123 );
$multiple_users = Capabilities::get_for_users( [ 1, 2, 3 ] );

// Check user capabilities
if ( Capabilities::user_has_any( [ 'edit_posts', 'edit_pages' ], 123 ) ) {
	// User has at least one capability
}

if ( Capabilities::user_has_all( [ 'edit_posts', 'publish_posts' ], 123 ) ) {
	// User has all capabilities
}

// Compare users
$comparison = Capabilities::compare_users( 123, 456 );
// Returns: ['common' => [...], 'only_user1' => [...], 'only_user2' => [...]]

// Find common capabilities
$common = Capabilities::get_common( [ 1, 2, 3 ] );

// Get capability options
$options = Capabilities::get_options();
// Returns: [['value' => 'edit_posts', 'label' => 'Edit Posts'], ...]

// Grouped by type
$grouped = Capabilities::get_options( true );
// Returns: ['post' => [...], 'user' => [...], ...]

// Simple key-value options
$simple = Capabilities::get_simple_options();
// Returns: ['edit_posts' => 'Edit Posts', ...]

// Search capabilities
$results        = Capabilities::search( 'edit' );
$search_options = Capabilities::search_options( 'post' );

// Sanitize capabilities
$clean_caps = Capabilities::sanitize( [ 'edit_posts', 'invalid', 'publish_posts' ] );

Capability Analysis

// System-wide capability discovery
$all_capabilities = Capabilities::get();
$primitive_only   = Capabilities::get_primitive();

// Categorize capabilities
$post_related  = Capabilities::get_by_type( 'post' );
$admin_related = Capabilities::get_by_type( 'core' );

// User permission auditing
$admin_users  = Capability::get_users_with( 'manage_options' );
$editor_roles = Capability::get_roles_with( 'edit_others_posts' );

// Permission comparison
$user_comparison    = Capabilities::compare_users( 123, 456 );
$shared_permissions = Capabilities::get_common( [ 1, 2, 3, 4 ] );

Form Integration

// Capability select options
$capability_options = Capabilities::get_options();

// Grouped by category
$grouped_options = Capabilities::get_options( true );

// Simple dropdown
$simple_select = Capabilities::get_simple_options();

// Search-based selection
$search_results = Capabilities::search_options( 'edit' );

Key Features

• Value/Label Format: Perfect for forms and selects
• Capability Analysis: System-wide capability discovery
• User Auditing: Find users with specific permissions
• Permission Comparison: Compare capabilities between users
• Search Functionality: Built-in capability search
• Type Categorization: Group capabilities by function

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