Custom Capabilities in WordPress for the Block Editor

Last Updated: September 18, 2025 @ 11:27am

As part of the migration to Blocks, the Role_Editor is now registering 2 new Roles and a custom capability. Here’s the what, why and how.

The Roles

Adminstrator: Stays the same, reserved for web developers
Front-End: Used for anyone who handles the front-end design of the site
Content Editor: Used for anyone who should only be updating content (e.g. Content Team, clients, RMs, etc.)

The Capability

The Role_Editor registers a “can_unlock_blocks” capability that the Gutenberg_Handler uses to determine what permissions a user has regarding block locking and which blocks are available for use.

Silencing Warnings in VS Code

When the Gutenberg_Handler (and anywhere else) checks for capabilities, if you’re using a custom capability, PHP Sniff will throw a warning. To properly silence that warning, go to the phpcs.xml.dist file and update the XML array:

Copy Code

<rule ref="WordPress.WP.Capabilities">
		<properties>
			<property name="custom_capabilities" type="array">
				<element value="can_unlock_blocks" />
			</property>
		</properties>
	</rule>

This will silence the following error:

Copy Code

Found unknown capability "${capability_name}" in function call to current_user_can(). Please check the spelling of the capability. If this is a custom capability, please verify the capability is registered with WordPress via a call to WP_Role(s)->add_cap().\nCustom capabilities can be made known to this sniff by setting the "custom_capabilities" property in the PHPCS ruleset.PHPCS(WordPress.WP.Capabilities.Unknown)

Learn more about customizing code standards here.

Custom Capabilities in WordPress for the Block Editor

The Roles

The Capability

Contact Us