WP_Abilities_Registry::register │ public │ WP 6.9.0

Registers a new ability.

Do not use this method directly. Instead, use the wp_register_ability()

Method of the class: WP_Abilities_Registry{}

Returns

WP_Ability|null. The registered ability instance on success, null on failure.

Usage

$WP_Abilities_Registry = new WP_Abilities_Registry();
$WP_Abilities_Registry->register( $name, $args ): ?WP_Ability;

$name(string) (required)

The name of the ability. The name must be a string containing a namespace prefix, i.e. my-plugin/my-ability. It can only contain lowercase alphanumeric characters, dashes and the forward slash.

$args(array) (required)

.

Notes

• See: wp_register_ability()

Changelog

WP_Abilities_Registry::register() WP Abilities Registry::register code ^{WP 6.9}

public function register( string $name, array $args ): ?WP_Ability {
	if ( ! preg_match( '/^[a-z0-9-]+\/[a-z0-9-]+$/', $name ) ) {
		_doing_it_wrong(
			__METHOD__,
			__(
				'Ability name must be a string containing a namespace prefix, i.e. "my-plugin/my-ability". It can only contain lowercase alphanumeric characters, dashes and the forward slash.'
			),
			'6.9.0'
		);
		return null;
	}

	if ( $this->is_registered( $name ) ) {
		_doing_it_wrong(
			__METHOD__,
			/* translators: %s: Ability name. */
			sprintf( __( 'Ability "%s" is already registered.' ), esc_html( $name ) ),
			'6.9.0'
		);
		return null;
	}

	/**
	 * Filters the ability arguments before they are validated and used to instantiate the ability.
	 *
	 * @since 6.9.0
	 *
	 * @param array<string, mixed> $args {
	 *     An associative array of arguments for the ability.
	 *
	 *     @type string               $label                 The human-readable label for the ability.
	 *     @type string               $description           A detailed description of what the ability does.
	 *     @type string               $category              The ability category slug this ability belongs to.
	 *     @type callable             $execute_callback      A callback function to execute when the ability is invoked.
	 *                                                       Receives optional mixed input and returns mixed result or WP_Error.
	 *     @type callable             $permission_callback   A callback function to check permissions before execution.
	 *                                                       Receives optional mixed input and returns bool or WP_Error.
	 *     @type array<string, mixed> $input_schema          Optional. JSON Schema definition for the ability's input.
	 *     @type array<string, mixed> $output_schema         Optional. JSON Schema definition for the ability's output.
	 *     @type array<string, mixed> $meta                  {
	 *         Optional. Additional metadata for the ability.
	 *
	 *         @type array<string, bool|string> $annotations  Optional. Annotation metadata for the ability.
	 *         @type bool                       $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
	 *     }
	 *     @type string               $ability_class         Optional. Custom class to instantiate instead of WP_Ability.
	 * }
	 * @param string               $name The name of the ability, with its namespace.
	 */
	$args = apply_filters( 'wp_register_ability_args', $args, $name );

	// Validate ability category exists if provided (will be validated as required in WP_Ability).
	if ( isset( $args['category'] ) ) {
		if ( ! wp_has_ability_category( $args['category'] ) ) {
			_doing_it_wrong(
				__METHOD__,
				sprintf(
					/* translators: %1$s: ability category slug, %2$s: ability name */
					__( 'Ability category "%1$s" is not registered. Please register the ability category before assigning it to ability "%2$s".' ),
					esc_html( $args['category'] ),
					esc_html( $name )
				),
				'6.9.0'
			);
			return null;
		}
	}

	// The class is only used to instantiate the ability, and is not a property of the ability itself.
	if ( isset( $args['ability_class'] ) && ! is_a( $args['ability_class'], WP_Ability::class, true ) ) {
		_doing_it_wrong(
			__METHOD__,
			__( 'The ability args should provide a valid `ability_class` that extends WP_Ability.' ),
			'6.9.0'
		);
		return null;
	}

	/** @var class-string<WP_Ability> */
	$ability_class = $args['ability_class'] ?? WP_Ability::class;
	unset( $args['ability_class'] );

	try {
		// WP_Ability::prepare_properties() will throw an exception if the properties are invalid.
		$ability = new $ability_class( $name, $args );
	} catch ( InvalidArgumentException $e ) {
		_doing_it_wrong(
			__METHOD__,
			$e->getMessage(),
			'6.9.0'
		);
		return null;
	}

	$this->registered_abilities[ $name ] = $ability;
	return $ability;
}