Roles Capabilities and User Metadata

Summary: Learning about Roles and Capabilities in WordPress and the User Metadata.

Roles

WordPress uses a concept of Roles designed to give the site owner the ability to control what users can and cannot do within the site. A site owner can manage the user access to such tasks as writing and editing posts, creating Pages, creating categories, moderating comments, managing plugins, managing themes, and managing other users, by assigning a specific role to each of the users.

A Role defines a set of tasks a user assigned the role is allowed to perform. For instance, the Super Admin role encompasses every possible task that can be performed within a Network of virtual WordPress sites. The Administrator role limits the allowed tasks only to those which affect a single site. On the other hand, the Author role allows the execution of just a small subset of tasks.

• Super Admin – somebody with access to the site network administration features and all other features. See the Create a Network article.
• Administrator (slug: ‘administrator’) – somebody who has access to all the administration features within a single site.
• Editor (slug: ‘editor’) – somebody who can publish and manage posts including the posts of other users.
• Author  (slug: ‘author’)  – somebody who can publish and manage their own posts.
• Contributor (slug: ‘contributor’) – somebody who can write and manage their own posts but cannot publish them.
• Subscriber (slug: ‘subscriber’) – somebody who can only manage their profile.

Creating a Role

function simple_role() {
	add_role(
		'simple_role',
		'Simple Role',
		array(
			'read'         => true,
			'edit_posts'   => true,
			'upload_files' => true,
		),
	);
}

// Add the simple_role.
add_action( 'init', 'simple_role' );

Removing Roles

function simple_role_remove() {
	remove_role( 'simple_role' );
}

// Remove the simple_role.
add_action( 'init', 'simple_role_remove' );

Adding Capabilities

function simple_role_caps() {
	// Gets the simple_role role object.
	$role = get_role( 'simple_role' );

	// Add a new capability.
	$role->add_cap( 'edit_others_posts', true );
}

// Add simple_role capabilities, priority must be after the initial role definition.
add_action( 'init', 'simple_role_caps', 11 );

Checking Capabilities of User

if ( current_user_can( 'edit_posts' ) ) {
	edit_post_link( esc_html__( 'Edit', 'Movie' ), '<p>', '</p>' );
}

User Metadata

usermeta is a table in the database that stores metadata (additional information) about users. This metadata is not part of the core user data but is instead used to store custom information that might be needed by plugins or themes. User meta is used to store additional custom information about users that is not included in the default WordPress user profile. This could include profile settings, preferences, user roles and capabilities, social media links, and more.

Get User Metadata

get_user_meta() function retrieves metadata for a specific user. We can fetch a single meta key’s value or all meta values for a user.

get_user_meta(
    int $user_id,
    string $key = '',
    bool $single = false
);

• $user_id: The ID of the user whose meta data we want to retrieve.
• $meta_key (optional): The meta key we want to retrieve. If not specified, it retrieves all user meta for the user.
• $single (optional): If true, it returns a single value. If false (default), it returns an array of values.

$user_id = 1;
$nickname = get_user_meta( $user_id, 'nickname', true );
echo $nickname;  // Output the user's nickname

Update User Metadata

update_user_meta() function updates a user meta field based on the user ID. If the meta key does not exist, it will create a new one.

update_user_meta(
    int $user_id,
    string $meta_key,
    mixed $meta_value,
    mixed $prev_value = ''
);

• $user_id: The ID of the user for whom we want to update the meta data.
• $meta_key: The meta key we want to update.
• $meta_value: The new value we want to set for the meta key.
• $prev_value (optional): If specified, only updates existing metadata entries with this value. Useful for avoiding overwrites.

$user_id = 1;
update_user_meta( $user_id, 'nickname', 'adi' );

Add User Metadata

add_user_meta()function adds a new user meta field. If the meta key already exists, it will not add a duplicate unless $unique is set to false.

add_user_meta(
    int $user_id,
    string $meta_key,
    mixed $meta_value,
    bool $unique = false
);

• $user_id: The ID of the user for whom we want to add the meta data.
• $meta_key: The meta key we want to add.
• $meta_value: The value we want to set for the meta key.
• $unique (optional): If true, will not add the meta data if the key already exists (default is false).

$user_id = 1;
add_user_meta( $user_id, 'favorite_color', 'blue', true );

Delete User Metadata

delete_user_meta() function deletes a user meta field based on the user ID. It can delete all entries with the specified meta key, or only those with a specific value.

delete_user_meta(
    int $user_id,
    string $meta_key,
    mixed $meta_value = ''
);

• $user_id: The ID of the user for whom we want to delete the meta data.
• $meta_key: The meta key we want to delete.
• $meta_value (optional): If specified, only deletes entries with this value.

$user_id = 1;
delete_user_meta( $user_id, 'favorite_color' );