https://github.com/arraypress/wp-user-access
A lean WordPress library for user access control, roles, and capabilities.
https://github.com/arraypress/wp-user-access
Last synced: 12 days ago
JSON representation
A lean WordPress library for user access control, roles, and capabilities.
- Host: GitHub
- URL: https://github.com/arraypress/wp-user-access
- Owner: arraypress
- Created: 2025-11-16T10:08:24.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2025-11-16T10:09:28.000Z (2 months ago)
- Last Synced: 2026-01-11T17:45:04.748Z (14 days ago)
- Language: PHP
- Size: 6.84 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# WordPress User Access Utilities
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
```bash
composer require arraypress/wp-user-access
```
## Usage
### User Class - Check and manage user permissions
```php
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
```php
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
```php
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
```php
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
```php
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
```php
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
```php
// 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
```php
// 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
```php
// Get roles for dropdown
$roles = Options::get_editable_roles();
?>
$name ) : ?>
```
### Plugin Uninstall Cleanup
```php
// 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
```php
// 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](https://github.com/arraypress/wp-user-access)
- [Issue Tracker](https://github.com/arraypress/wp-user-access/issues)