README

An extended WP_User class.

XtraPress\User extends the WP_User class adding some useful and logical methods to make interacting with a user much simpler.

The class provides methods to interact with user roles, capabilities, meta and properties in a more succinct manner.

Installation

Install via Composer:

composer require xtrapress/user

Use Composer's autoload:

<?php

require_once __DIR__ . '/vendor/autoload.php';

How to use

Attributes

The User class magic methods: __isset, __get, __set and __unset have been enhanced with aliased keys, so you don't have to prefix the core properties with "user_". The class also implements ArrayAccess, and provides has, get, add, and remove methods.

<?php

use XtraPress\User;

$user = new User(1);

isset($user->email); // true
$user->email; // same as $user->user_email
$user->email = 'email@example.com'; // sets $user->user_email property
unset($user->email); // unsets $user->user_email property

isset($user['email']);
$user['email'];
$user['email'] = 'email@example.com';
unset($user['email']);

$user->has('email');
$user->get('email');
$user->add('email', 'email@example.com');
$user->remove('email');

Capabilities

The User class provides (via the HasCapabilities trait) several methods to make interacting with capabilities ~~simple~~ slightly easier.

can(string $capability, ...$args): boolean
cannot(string $capability, ...$args): boolean
canAny(array $capabilities, ...$args): boolean
addCapability(string $capability): void
removeCapability(string $capability): void

<?php

use XtraPress\User;

$user = new User(1);

$user->can('edit_posts'); // true
$user->cannot('read') // false
$user->canAny(['read', 'manage_options']) // true

$user->addCapability('tames_unicorns');
$user->removeCapability('knows_limits');

Macros

The User class provides a macro method to add custom functionality to the class. This is useful for custom roles. The user instance is bound to $this, and the parameters are passed to the given callback.

<?php

use XtraPress\User;

User::macro('isCrustyJuggler', function() {
    return $this->hasRole('crusty_juggler');
});

User::macro('name', function() {
    return "{$this->first_name} {$this->last_name}";
});

User::macro('notify', function(string $subject, string $body, array $headers = [], array $attachments = []) {
    $to = "{$this->first_name} {$this->last_name} <{$this->email}>";

    return wp_mail($to, $subject, $body, $headers, $attachments);
});

$user = new User(1);

$user->isCrustyJuggler(); // true
$user->name(); // John Doe

$user->notify('email subject', "Hi {$user->first_name}");

Roles

The User class provides (via the HasRoles trait) several methods to make interacting with roles simple.

addRole( string $role ): void
setRole( string $role ): void
removeRole( string $role ): void
getRoles(): array
hasRole( string $role ): boolean
hasAnyRoles( array $roles ): boolean
hasAllRoles( array $roles ): boolean
isSubscriber(): boolean
isContributor(): boolean
isAuthor(): boolean
isEditor(): boolean
isAdministrator(): boolean

<?php

use XtraPress\User;

$user = new User(1);

$user->isAdministrator(); // true
$user->hasRole('subscriber') // false

$user->removeRole('administrator');
$user->addRole('subscriber');

$user->isSubscriber() // true
$user->hasRole('administrator') // false

Miscellaneous

You can delete the user with the delete method.

<?php

use XtraPress\User;

$user = new User(1);

$user->delete();

The User class implements JsonSerializable to output the user properties (including meta) as an array when encoded as JSON.

<?php

use XtraPress\User;

$user = new User(1);

echo json_encode( $user );

xtrapress / user

Maintainers

Details