WP_Roles::add_role( string $role, string $display_name, array $capabilities = array() )

Add role name with capabilities to list.

Description Description

Updates the list of roles, if the role doesn’t already exist.

The capabilities are defined in the following format array( 'read' => true ); To explicitly deny a role a capability you set the value for that capability to false.

Parameters Parameters


(string) (Required) Role name.


(string) (Required) Role display name.


(array) (Optional) List of role capabilities in the above format.

Default value: array()

Top ↑

Return Return

(WP_Role|void) WP_Role object, if role is added.

Top ↑

Source Source

File: wp-includes/class-wp-roles.php

	public function add_role( $role, $display_name, $capabilities = array() ) {
		if ( empty( $role ) || isset( $this->roles[ $role ] ) ) {

		$this->roles[$role] = array(
			'name' => $display_name,
			'capabilities' => $capabilities
		if ( $this->use_db )
			update_option( $this->role_key, $this->roles );
		$this->role_objects[$role] = new WP_Role( $role, $capabilities );
		$this->role_names[$role] = $display_name;
		return $this->role_objects[$role];

Top ↑

Changelog Changelog

Version Description
2.0.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

You must log in before being able to contribute a note or feedback.