automattic / jetpack-wp-abilities
Shared utilities for registering abilities with the WordPress Abilities API from Jetpack packages and plugins.
Package info
github.com/Automattic/jetpack-wp-abilities
Type:jetpack-library
pkg:composer/automattic/jetpack-wp-abilities
Requires
- php: >=7.4
Requires (Dev)
- automattic/phpunit-select-config: ^1.0.12
- brain/monkey: ^2.6.2
- yoast/phpunit-polyfills: ^4.0.0
Suggests
- automattic/jetpack-autoloader: Allow for better interoperability with other plugins that use this package.
Provides
None
Conflicts
None
Replaces
None
README
Shared utilities for registering a category and its abilities with the WordPress Abilities API from Jetpack packages and plugins.
The Registrar base class owns the boilerplate every consumer would otherwise hand-roll: hooking into wp_abilities_api_categories_init / wp_abilities_api_init (or registering right away when init() runs inside wp_abilities_api_categories_init; WordPress rejects registrations outside these actions), and guarding the Abilities API function calls so the class is safe on WordPress versions older than 6.9.
Usage
Extend Registrar, override the three static getters and enabled_by_default(), and call init() from the consumer's bootstrap.
use Automattic\Jetpack\WP_Abilities\Registrar; class My_Plugin_Abilities extends Registrar { protected static function enabled_by_default(): bool { return true; } public static function get_category_slug(): string { return 'my-plugin'; } public static function get_category_definition(): array { return array( 'label' => 'My Plugin', 'description' => __( 'Abilities for My Plugin.', 'my-plugin' ), ); } public static function get_abilities(): array { return array( 'my-plugin/get-things' => array( 'label' => __( 'List things', 'my-plugin' ), 'description' => __( 'Return the list of things the user can access.', 'my-plugin' ), 'input_schema' => array( 'type' => 'object', 'default' => array(), 'properties' => array(), 'additionalProperties' => false, ), 'execute_callback' => array( __CLASS__, 'get_things' ), 'permission_callback' => array( __CLASS__, 'can_read_things' ), 'meta' => array( 'annotations' => array( 'readonly' => true, 'destructive' => false, 'idempotent' => true, ), 'public' => true, 'show_in_rest' => true, 'mcp' => array( 'public' => true, 'type' => 'tool', ), ), ), ); } public static function can_read_things(): bool { return current_user_can( 'read' ); } public static function get_things( $input = null ) { return array( 'things' => array() ); } } My_Plugin_Abilities::init();
If an ability spec omits category, the registrar auto-injects get_category_slug(). If the spec sets category explicitly (for cross-registrar shared abilities), the explicit value is preserved.
Turning registration off
Registration is on by default for Jetpack's own registrars. init() checks the jetpack_wp_abilities_enabled filter, whose default comes from the registrar's enabled_by_default(). Return false to turn registration off for a site or a single request.
enabled_by_default() returns false unless a registrar overrides it. The newest copy of Registrar on a site loads for every plugin, so a registrar from an older plugin release, which doesn't override it, stays off. Override it to return true in a new registrar once its abilities are ready to be on by default.
// Turn Jetpack abilities off on this site. add_filter( 'jetpack_wp_abilities_enabled', '__return_false' );
Add the filter in an mu-plugin. Registration starts before a theme loads, so a theme's functions.php is too late.
The filter does not cover Forms: its abilities shipped before the filter existed and register whatever it returns.
Per-registration gate
For finer-grained control, every category and every ability also passes through the jetpack_wp_abilities_should_register filter (only reached when jetpack_wp_abilities_enabled has already returned true). Returning false skips a single registration.
// Globally enabled, but hold back a single ability until it's GA. add_filter( 'jetpack_wp_abilities_should_register', static function ( bool $enabled, string $type, string $slug ): bool { if ( 'ability' === $type && 'my-plugin/experimental-write' === $slug ) { return current_user_can( 'manage_options' ); } return $enabled; }, 10, 3 );
The filter fires once per category and once per individual ability, so callbacks can switch on $type ('category' or 'ability') and/or $slug for granular control.
Using this package in your WordPress plugin
If you plan on using this package in your WordPress plugin, we recommend using Jetpack Autoloader as your autoloader for maximum interoperability with other plugins that use this package.
Security
Need to report a security vulnerability? Go to https://automattic.com/security/ or directly to our security bug bounty site https://hackerone.com/automattic.
License
Jetpack WP Abilities is licensed under GNU General Public License v2 (or later).