PHPackages                             arraypress/wp-user-utils - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. arraypress/wp-user-utils

ActiveLibrary[Utility & Helpers](/categories/utility)

arraypress/wp-user-utils
========================

A lean WordPress library for working with users and user metadata

04PHP

Since Jul 3Pushed 10mo agoCompare

[ Source](https://github.com/arraypress/wp-user-utils)[ Packagist](https://packagist.org/packages/arraypress/wp-user-utils)[ RSS](/packages/arraypress-wp-user-utils/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

WordPress User Utilities
========================

[](#wordpress-user-utilities)

A lightweight WordPress library for working with users and user metadata. Provides clean APIs for user operations, search functionality, and value/label formatting perfect for forms and admin interfaces.

Features
--------

[](#features)

- 🎯 **Clean API**: WordPress-style snake\_case methods with consistent interfaces
- 🔍 **Built-in Search**: User search with value/label formatting
- 📋 **Form-Ready Options**: Perfect value/label arrays for selects and forms
- 👤 **User Information**: Easy access to user data and meta
- 🔐 **Authentication**: Simple authentication status checks
- 📊 **Meta Operations**: User meta handling with type safety
- 🚀 **Bulk Operations**: Process multiple users efficiently
- ➕ **User Creation**: Create single or multiple users with flexible options

Requirements
------------

[](#requirements)

- PHP 7.4 or later
- WordPress 5.0 or later

Installation
------------

[](#installation)

```
composer require arraypress/wp-user-utils
```

Basic Usage
-----------

[](#basic-usage)

### Working with Single Users

[](#working-with-single-users)

```
use ArrayPress\UserUtils\User;

// Get user by ID
$user = User::get( 123 );

// Get user with current user fallback
$user = User::get(); // Gets current user if ID is 0

// Check if user exists
if ( User::exists( 123 ) ) {
	// User exists
}

// Create a new user
$user = User::create( 'johndoe', 'john@example.com' );

// Create user with additional data
$user = User::create( 'johndoe', 'john@example.com', [
	'user_pass'    => 'custom_password',
	'role'         => 'editor',
	'display_name' => 'John Doe',
	'first_name'   => 'John',
	'last_name'    => 'Doe',
	'description'  => 'Content editor'
] );

// Create user only if they don't exist
$user = User::create_if_not_exists( 'johndoe', 'john@example.com' );

// Get user by different identifiers
$user = User::get_by_email( 'user@example.com' );
$user = User::get_by_login( 'username' );
$user = User::get_by_slug( 'user-slug' );

// Get user information
$full_name    = User::get_full_name( 123 );
$email        = User::get_email( 123 );
$display_name = User::get_display_name( 123 );
$login        = User::get_login( 123 );

// Get specific field
$field_value = User::get_field( 123, 'description' );

// Authentication checks
$is_logged_in = User::is_logged_in();
$is_guest     = User::is_guest();
$is_current   = User::is_current( 123 );

// Capabilities and roles
$has_cap      = User::has_capability( 123, 'edit_posts' );
$has_role     = User::has_role( 123, 'editor' );
$roles        = User::get_roles( 123 );
$capabilities = User::get_capabilities( 123 );

// User meta
$meta_value        = User::get_meta( 123, 'custom_field' );
$meta_with_default = User::get_meta_with_default( 123, 'preference', 'default_value' );

// Update meta only if changed
User::update_meta_if_changed( 123, 'last_activity', time() );

// Delete meta
User::delete_meta( 123, 'temp_data' );

// Date information
$reg_date    = User::get_registration_date( 123, 'Y-m-d' );
$account_age = User::get_account_age( 123 ); // Days since registration
$time_since  = User::get_time_since_registration( 123 ); // "2 years ago"

// Delete user
User::delete( 123, 456 ); // Delete user 123, reassign content to user 456
```

### Working with Multiple Users

[](#working-with-multiple-users)

```
use ArrayPress\UserUtils\Users;

// Get multiple users
$users = Users::get( [ 1, 2, 3 ] );

// Create multiple users
$result = Users::create( [
	[
		'user_login'   => 'johndoe',
		'user_email'   => 'john@example.com',
		'display_name' => 'John Doe',
		'role'         => 'editor'
	],
	[
		'user_login'   => 'janedoe',
		'user_email'   => 'jane@example.com',
		'display_name' => 'Jane Doe',
		'role'         => 'author'
	]
] );

// Create users with shared defaults
$result = Users::create( [
	[
		'user_login' => 'user1',
		'user_email' => 'user1@example.com'
	],
	[
		'user_login' => 'user2',
		'user_email' => 'user2@example.com'
	]
], [
	'role' => 'subscriber', // Default role for all users
	'send_user_notification' => false
] );

// Create users only if they don't exist
$result = Users::create_if_not_exists( [
	[
		'user_login' => 'admin',
		'user_email' => 'admin@example.com',
		'role'       => 'administrator'
	],
	[
		'user_login' => 'editor',
		'user_email' => 'editor@example.com',
		'role'       => 'editor'
	]
] );

// Check results
if ( ! empty( $result['created'] ) ) {
	foreach ( $result['created'] as $user ) {
		echo "Created user: " . $user->user_login . "\n";
	}
}

if ( ! empty( $result['existing'] ) ) {
	foreach ( $result['existing'] as $user ) {
		echo "User already exists: " . $user->user_login . "\n";
	}
}

if ( ! empty( $result['errors'] ) ) {
	foreach ( $result['errors'] as $error ) {
		echo "Error: " . $error . "\n";
	}
}

// Get users by identifiers (IDs, emails, usernames)
$user_ids     = Users::get_by_identifiers( [ 'admin', 'user@example.com', 123 ] );
$user_objects = Users::get_by_identifiers( [ 'admin', 'user@example.com' ], true );

// Get users by role
$editors     = Users::get_by_role( 'editor' );
$admin_count = Users::count_by_role( 'administrator' );

// Get recent users
$recent_users = Users::get_recent( 10 );

// Get users by meta
$premium_users = Users::get_by_meta( 'subscription_type', 'premium' );

// Search users and get options
$options = Users::search_options( 'john' );
// Returns: [['value' => 1, 'label' => 'John Doe'], ...]

// Search users
$search_results = Users::search( 'smith' );

// Get all users as options
$all_options = Users::get_options();
// Returns: [1 => 'John Doe', 2 => 'Jane Smith', ...]

// Get options with custom args
$author_options = Users::get_options( [
	'role'       => 'author',
	'meta_key'   => 'active_status',
	'meta_value' => 'active'
] );

// Bulk operations
$results = Users::update_meta( [ 1, 2, 3 ], 'newsletter', true );
$results = Users::delete_meta( [ 1, 2, 3 ], 'temp_data' );
$results = Users::delete( [ 4, 5, 6 ], 1 ); // Delete users, reassign to user 1

// Utility methods
$existing_users = Users::exists( [ 1, 2, 3, 999 ] ); // Returns [1, 2, 3]
$clean_ids      = Users::sanitize( [ '1', 'invalid', '3' ] ); // Returns [1, 3]
```

### User Creation Examples

[](#user-creation-examples)

```
// Plugin activation - create default users
function create_default_users() {
	$default_users = [
		[
			'user_login'   => 'site_manager',
			'user_email'   => 'manager@yoursite.com',
			'display_name' => 'Site Manager',
			'role'         => 'editor'
		],
		[
			'user_login'   => 'content_writer',
			'user_email'   => 'writer@yoursite.com',
			'display_name' => 'Content Writer',
			'role'         => 'author'
		]
	];

	$result = Users::create_if_not_exists( $default_users );

	// Log creation results
	error_log( sprintf( 'Created %d users, %d already existed',
		count( $result['created'] ),
		count( $result['existing'] )
	) );
}

// Import users from CSV data
function import_users_from_csv( $csv_data ) {
	$users = [];

	foreach ( $csv_data as $row ) {
		$users[] = [
			'user_login'   => $row['username'],
			'user_email'   => $row['email'],
			'display_name' => $row['full_name'],
			'role'         => $row['role'] ?? 'subscriber'
		];
	}

	return Users::create( $users, [
		'send_user_notification' => false // Don't email new users
	] );
}

// Create test users for development
function create_test_users() {
	$test_users = [
		'Test Admin'      => 'administrator',
		'Test Editor'     => 'editor',
		'Test Author'     => 'author',
		'Test Subscriber' => 'subscriber'
	];

	$users_data = [];
	foreach ( $test_users as $name => $role ) {
		$username     = strtolower( str_replace( ' ', '_', $name ) );
		$users_data[] = [
			'user_login'   => $username,
			'user_email'   => $username . '@test.local',
			'display_name' => $name,
			'role'         => $role
		];
	}

	return Users::create_if_not_exists( $users_data );
}
```

### Search Functionality

[](#search-functionality)

```
// Basic search
$users = Users::search( 'john doe' );

// Search with custom args
$users = Users::search( 'manager', [
	'role'       => 'editor',
	'number'     => 5,
	'meta_key'   => 'department',
	'meta_value' => 'marketing'
] );

// Get search results as options for forms
$options = Users::search_options( 'admin' );
```

### User Validation and Sanitization

[](#user-validation-and-sanitization)

```
// Validate user ID with current user fallback
$user_id = User::validate_id( 0, true ); // Returns current user ID if logged in

// Check which users exist
$existing = Users::exists( [ 1, 2, 999 ] ); // Returns [1, 2]

// Sanitize mixed identifiers
$clean_users = Users::sanitize( [ 'admin', 'user@example.com', 123 ] );
```

Key Features
------------

[](#key-features)

- **Value/Label Format**: Perfect for forms and selects
- **Search Functionality**: Built-in user search with flexible options
- **User Creation**: Create single or multiple users with validation
- **Meta Operations**: Simple user meta handling
- **Bulk Operations**: Process multiple users efficiently
- **Authentication Helpers**: Login status and current user checks
- **Flexible Identifiers**: Use IDs, emails, usernames, or objects interchangeably

Requirements
------------

[](#requirements-1)

- PHP 7.4+
- WordPress 5.0+

Contributing
------------

[](#contributing)

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

License
-------

[](#license)

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

Support
-------

[](#support)

- [Documentation](https://github.com/arraypress/wp-user-utils)
- [Issue Tracker](https://github.com/arraypress/wp-user-utils/issues)

###  Health Score

16

—

LowBetter than 5% of packages

Maintenance39

Infrequent updates — may be unmaintained

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity14

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/cd6eb8aff0903d87eb674d1ba3c5f3653899c0d7661504eb0deb7798ed86b643?d=identicon)[arraypress](/maintainers/arraypress)

---

Top Contributors

[![arraypress](https://avatars.githubusercontent.com/u/22668877?v=4)](https://github.com/arraypress "arraypress (4 commits)")

### Embed Badge

![Health badge](/badges/arraypress-wp-user-utils/health.svg)

```
[![Health](https://phpackages.com/badges/arraypress-wp-user-utils/health.svg)](https://phpackages.com/packages/arraypress-wp-user-utils)
```

###  Alternatives

[vonage/nexmo-bridge

Provides a bridge for using the Vonage PHP SDK with the older Nexmo namespace

5310.3M3](/packages/vonage-nexmo-bridge)[mediawiki/chameleon-skin

A highly flexible MediaWiki skin using Bootstrap 4

12481.8k2](/packages/mediawiki-chameleon-skin)[dragon-code/pretty-routes

Pretty Routes for Laravel

10058.7k4](/packages/dragon-code-pretty-routes)[aeon-php/calendar-holidays

Holidays calendar abstraction layer for Aeon Time management framework

14212.4k3](/packages/aeon-php-calendar-holidays)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)