{"id":29651294,"url":"https://github.com/arraypress/wp-user-utils","last_synced_at":"2025-07-22T05:06:32.969Z","repository":{"id":302497261,"uuid":"1011400922","full_name":"arraypress/wp-user-utils","owner":"arraypress","description":"A lean WordPress library for working with users and user metadata.","archived":false,"fork":false,"pushed_at":"2025-07-02T17:14:23.000Z","size":11,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-02T18:28:04.033Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arraypress.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-30T18:56:58.000Z","updated_at":"2025-07-02T17:14:26.000Z","dependencies_parsed_at":"2025-07-02T18:29:04.939Z","dependency_job_id":"e9fd3d5a-bbe3-4dfc-88bc-e2ca1782fdc0","html_url":"https://github.com/arraypress/wp-user-utils","commit_stats":null,"previous_names":["arraypress/wp-user-utils"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/arraypress/wp-user-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-user-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-user-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-user-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-user-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arraypress","download_url":"https://codeload.github.com/arraypress/wp-user-utils/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-user-utils/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266430667,"owners_count":23927169,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-22T05:06:32.487Z","updated_at":"2025-07-22T05:06:32.956Z","avatar_url":"https://github.com/arraypress.png","language":"PHP","readme":"# WordPress User Utilities\n\nA 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.\n\n## Features\n\n* 🎯 **Clean API**: WordPress-style snake_case methods with consistent interfaces\n* 🔍 **Built-in Search**: User search with value/label formatting\n* 📋 **Form-Ready Options**: Perfect value/label arrays for selects and forms\n* 👤 **User Information**: Easy access to user data and meta\n* 🔐 **Authentication**: Simple authentication status checks\n* 📊 **Meta Operations**: User meta handling with type safety\n* 🚀 **Bulk Operations**: Process multiple users efficiently\n* ➕ **User Creation**: Create single or multiple users with flexible options\n\n## Requirements\n\n* PHP 7.4 or later\n* WordPress 5.0 or later\n\n## Installation\n\n```bash\ncomposer require arraypress/wp-user-utils\n```\n\n## Basic Usage\n\n### Working with Single Users\n\n```php\nuse ArrayPress\\UserUtils\\User;\n\n// Get user by ID\n$user = User::get( 123 );\n\n// Get user with current user fallback\n$user = User::get(); // Gets current user if ID is 0\n\n// Check if user exists\nif ( User::exists( 123 ) ) {\n\t// User exists\n}\n\n// Create a new user\n$user = User::create( 'johndoe', 'john@example.com' );\n\n// Create user with additional data\n$user = User::create( 'johndoe', 'john@example.com', [\n\t'user_pass'    =\u003e 'custom_password',\n\t'role'         =\u003e 'editor',\n\t'display_name' =\u003e 'John Doe',\n\t'first_name'   =\u003e 'John',\n\t'last_name'    =\u003e 'Doe',\n\t'description'  =\u003e 'Content editor'\n] );\n\n// Create user only if they don't exist\n$user = User::create_if_not_exists( 'johndoe', 'john@example.com' );\n\n// Get user by different identifiers\n$user = User::get_by_email( 'user@example.com' );\n$user = User::get_by_login( 'username' );\n$user = User::get_by_slug( 'user-slug' );\n\n// Get user information\n$full_name    = User::get_full_name( 123 );\n$email        = User::get_email( 123 );\n$display_name = User::get_display_name( 123 );\n$login        = User::get_login( 123 );\n\n// Get specific field\n$field_value = User::get_field( 123, 'description' );\n\n// Authentication checks\n$is_logged_in = User::is_logged_in();\n$is_guest     = User::is_guest();\n$is_current   = User::is_current( 123 );\n\n// Capabilities and roles\n$has_cap      = User::has_capability( 123, 'edit_posts' );\n$has_role     = User::has_role( 123, 'editor' );\n$roles        = User::get_roles( 123 );\n$capabilities = User::get_capabilities( 123 );\n\n// User meta\n$meta_value        = User::get_meta( 123, 'custom_field' );\n$meta_with_default = User::get_meta_with_default( 123, 'preference', 'default_value' );\n\n// Update meta only if changed\nUser::update_meta_if_changed( 123, 'last_activity', time() );\n\n// Delete meta\nUser::delete_meta( 123, 'temp_data' );\n\n// Date information\n$reg_date    = User::get_registration_date( 123, 'Y-m-d' );\n$account_age = User::get_account_age( 123 ); // Days since registration\n$time_since  = User::get_time_since_registration( 123 ); // \"2 years ago\"\n\n// Delete user\nUser::delete( 123, 456 ); // Delete user 123, reassign content to user 456\n```\n\n### Working with Multiple Users\n\n```php\nuse ArrayPress\\UserUtils\\Users;\n\n// Get multiple users\n$users = Users::get( [ 1, 2, 3 ] );\n\n// Create multiple users\n$result = Users::create( [\n\t[\n\t\t'user_login'   =\u003e 'johndoe',\n\t\t'user_email'   =\u003e 'john@example.com',\n\t\t'display_name' =\u003e 'John Doe',\n\t\t'role'         =\u003e 'editor'\n\t],\n\t[\n\t\t'user_login'   =\u003e 'janedoe',\n\t\t'user_email'   =\u003e 'jane@example.com',\n\t\t'display_name' =\u003e 'Jane Doe',\n\t\t'role'         =\u003e 'author'\n\t]\n] );\n\n// Create users with shared defaults\n$result = Users::create( [\n\t[\n\t\t'user_login' =\u003e 'user1',\n\t\t'user_email' =\u003e 'user1@example.com'\n\t],\n\t[\n\t\t'user_login' =\u003e 'user2',\n\t\t'user_email' =\u003e 'user2@example.com'\n\t]\n], [\n\t'role' =\u003e 'subscriber', // Default role for all users\n\t'send_user_notification' =\u003e false\n] );\n\n// Create users only if they don't exist\n$result = Users::create_if_not_exists( [\n\t[\n\t\t'user_login' =\u003e 'admin',\n\t\t'user_email' =\u003e 'admin@example.com',\n\t\t'role'       =\u003e 'administrator'\n\t],\n\t[\n\t\t'user_login' =\u003e 'editor',\n\t\t'user_email' =\u003e 'editor@example.com',\n\t\t'role'       =\u003e 'editor'\n\t]\n] );\n\n// Check results\nif ( ! empty( $result['created'] ) ) {\n\tforeach ( $result['created'] as $user ) {\n\t\techo \"Created user: \" . $user-\u003euser_login . \"\\n\";\n\t}\n}\n\nif ( ! empty( $result['existing'] ) ) {\n\tforeach ( $result['existing'] as $user ) {\n\t\techo \"User already exists: \" . $user-\u003euser_login . \"\\n\";\n\t}\n}\n\nif ( ! empty( $result['errors'] ) ) {\n\tforeach ( $result['errors'] as $error ) {\n\t\techo \"Error: \" . $error . \"\\n\";\n\t}\n}\n\n// Get users by identifiers (IDs, emails, usernames)\n$user_ids     = Users::get_by_identifiers( [ 'admin', 'user@example.com', 123 ] );\n$user_objects = Users::get_by_identifiers( [ 'admin', 'user@example.com' ], true );\n\n// Get users by role\n$editors     = Users::get_by_role( 'editor' );\n$admin_count = Users::count_by_role( 'administrator' );\n\n// Get recent users\n$recent_users = Users::get_recent( 10 );\n\n// Get users by meta\n$premium_users = Users::get_by_meta( 'subscription_type', 'premium' );\n\n// Search users and get options\n$options = Users::search_options( 'john' );\n// Returns: [['value' =\u003e 1, 'label' =\u003e 'John Doe'], ...]\n\n// Search users\n$search_results = Users::search( 'smith' );\n\n// Get all users as options\n$all_options = Users::get_options();\n// Returns: [1 =\u003e 'John Doe', 2 =\u003e 'Jane Smith', ...]\n\n// Get options with custom args\n$author_options = Users::get_options( [\n\t'role'       =\u003e 'author',\n\t'meta_key'   =\u003e 'active_status',\n\t'meta_value' =\u003e 'active'\n] );\n\n// Bulk operations\n$results = Users::update_meta( [ 1, 2, 3 ], 'newsletter', true );\n$results = Users::delete_meta( [ 1, 2, 3 ], 'temp_data' );\n$results = Users::delete( [ 4, 5, 6 ], 1 ); // Delete users, reassign to user 1\n\n// Utility methods\n$existing_users = Users::exists( [ 1, 2, 3, 999 ] ); // Returns [1, 2, 3]\n$clean_ids      = Users::sanitize( [ '1', 'invalid', '3' ] ); // Returns [1, 3]\n```\n\n### User Creation Examples\n\n```php\n// Plugin activation - create default users\nfunction create_default_users() {\n\t$default_users = [\n\t\t[\n\t\t\t'user_login'   =\u003e 'site_manager',\n\t\t\t'user_email'   =\u003e 'manager@yoursite.com',\n\t\t\t'display_name' =\u003e 'Site Manager',\n\t\t\t'role'         =\u003e 'editor'\n\t\t],\n\t\t[\n\t\t\t'user_login'   =\u003e 'content_writer',\n\t\t\t'user_email'   =\u003e 'writer@yoursite.com',\n\t\t\t'display_name' =\u003e 'Content Writer',\n\t\t\t'role'         =\u003e 'author'\n\t\t]\n\t];\n\n\t$result = Users::create_if_not_exists( $default_users );\n\n\t// Log creation results\n\terror_log( sprintf( 'Created %d users, %d already existed',\n\t\tcount( $result['created'] ),\n\t\tcount( $result['existing'] )\n\t) );\n}\n\n// Import users from CSV data\nfunction import_users_from_csv( $csv_data ) {\n\t$users = [];\n\n\tforeach ( $csv_data as $row ) {\n\t\t$users[] = [\n\t\t\t'user_login'   =\u003e $row['username'],\n\t\t\t'user_email'   =\u003e $row['email'],\n\t\t\t'display_name' =\u003e $row['full_name'],\n\t\t\t'role'         =\u003e $row['role'] ?? 'subscriber'\n\t\t];\n\t}\n\n\treturn Users::create( $users, [\n\t\t'send_user_notification' =\u003e false // Don't email new users\n\t] );\n}\n\n// Create test users for development\nfunction create_test_users() {\n\t$test_users = [\n\t\t'Test Admin'      =\u003e 'administrator',\n\t\t'Test Editor'     =\u003e 'editor',\n\t\t'Test Author'     =\u003e 'author',\n\t\t'Test Subscriber' =\u003e 'subscriber'\n\t];\n\n\t$users_data = [];\n\tforeach ( $test_users as $name =\u003e $role ) {\n\t\t$username     = strtolower( str_replace( ' ', '_', $name ) );\n\t\t$users_data[] = [\n\t\t\t'user_login'   =\u003e $username,\n\t\t\t'user_email'   =\u003e $username . '@test.local',\n\t\t\t'display_name' =\u003e $name,\n\t\t\t'role'         =\u003e $role\n\t\t];\n\t}\n\n\treturn Users::create_if_not_exists( $users_data );\n}\n```\n\n### Search Functionality\n\n```php\n// Basic search\n$users = Users::search( 'john doe' );\n\n// Search with custom args\n$users = Users::search( 'manager', [\n\t'role'       =\u003e 'editor',\n\t'number'     =\u003e 5,\n\t'meta_key'   =\u003e 'department',\n\t'meta_value' =\u003e 'marketing'\n] );\n\n// Get search results as options for forms\n$options = Users::search_options( 'admin' );\n```\n\n### User Validation and Sanitization\n\n```php\n// Validate user ID with current user fallback\n$user_id = User::validate_id( 0, true ); // Returns current user ID if logged in\n\n// Check which users exist\n$existing = Users::exists( [ 1, 2, 999 ] ); // Returns [1, 2]\n\n// Sanitize mixed identifiers\n$clean_users = Users::sanitize( [ 'admin', 'user@example.com', 123 ] );\n```\n\n## Key Features\n\n- **Value/Label Format**: Perfect for forms and selects\n- **Search Functionality**: Built-in user search with flexible options\n- **User Creation**: Create single or multiple users with validation\n- **Meta Operations**: Simple user meta handling\n- **Bulk Operations**: Process multiple users efficiently\n- **Authentication Helpers**: Login status and current user checks\n- **Flexible Identifiers**: Use IDs, emails, usernames, or objects interchangeably\n\n## Requirements\n\n- PHP 7.4+\n- WordPress 5.0+\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the GPL-2.0-or-later License.\n\n## Support\n\n- [Documentation](https://github.com/arraypress/wp-user-utils)\n- [Issue Tracker](https://github.com/arraypress/wp-user-utils/issues)","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farraypress%2Fwp-user-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farraypress%2Fwp-user-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farraypress%2Fwp-user-utils/lists"}