Skip to content

Customize user roles

The default WordPress roles and capabilities may be insufficient for the needs of some sites. A collection of helper functions are available in vip-go-mu-plugins for creating new roles or modifying existing roles. VIP recommends using these helper functions rather than the traditional methods to ensure that the code works as expected on the WordPress VIP platform.

  • The helper functions should be added with the admin_init hook.
  • Custom changes made to roles and capabilities will trigger a database update. Because of this, ensure that the helper functions only run when the role definitions need to change. One approach is to use a version value stored in the options table to check for changes (see code below)
  • For sites with a high amount of traffic—or a site with many concurrently active editors—it is possible for changes to roles and capabilities to trigger a sudden spike of multiple identical database updates that can lead to performance issues. To prevent these issues, VIP recommends triggering the update with an added admin button on a special settings page, or to create a custom CLI command.
  • If more than one plugin on a site adds or customizes roles, each plugin should have a separate option.

In this example, a new role for a “Reviewer” is created and defined using the wpcom_vip_add_role() function: 

add_action(
	'admin_init',
	function() {
		$ver = 42; // Incrementally update each time this code is changed.
		
		// Check if this has been run already.
		if ( $ver <= get_option( 'myplugin_roles_version' ) ) {
			return;
		}
	 
		// Add a Reviewer role.
		wpcom_vip_add_role(
			'reviewer',
			'Reviewer',
			array(
				'read'                 => true,
				'edit_posts'           => true,
				'edit_others_posts'    => true,
				'edit_private_posts'   => true,
				'edit_published_posts' => true,
				'read_private_posts'   => true,
				'edit_pages'           => true,
				'edit_others_pages'    => true,
				'edit_private_pages'   => true,
				'edit_published_pages' => true,
				'read_private_pages'   => true,
			)
		);
	 
		// Update the version to prevent this running again.
		update_option( 'myplugin_roles_version', $ver );
	}
);

The following code example demonstrates a variety of customizations and modifications that can be accomplished with the available VIP helper methods. As before, this uses an example technique to only trigger the actions when a version value changes:

add_action(
	'admin_init',
	function() {
		$ver = 43; // Incrementally update each time this code is changed.
		
		// Check if this has been run already.
		if ( $ver <= get_option( 'myplugin_roles_version' ) ) {
			return;
		}
		 
		// Add new role.
		wpcom_vip_add_role( 'reader', 'Reader', array( 'read' => true ) );
	 
		// Remove publish_posts cap from authors.
		wpcom_vip_merge_role_caps( 'author', array( 'publish_posts' => false ) );

		// Duplicate an existing role and modify some caps.
		wpcom_vip_duplicate_role(
			'administrator',
			'station-administrator',
			'Station Administrator',
			array( 'manage_categories' => false )
		);
	 
		// Add custom cap to a role.
		wpcom_vip_add_role_caps( 'administrator', array( 'my-custom-cap' ) );
	 
		// Remove cap from a role.
		wpcom_vip_remove_role_caps( 'author', array( 'publish_posts' ) );
	 
		// Update the version to prevent this running again.
		update_option( 'myplugin_roles_version', $ver );
	}
);

Last updated: December 26, 2023

Relevant to

  • WordPress