WP_Ability::execute( mixed $input = null ): mixed|WP_Error

Source

public function execute( $input = null ) {
	/**
	 * Fires when an ability is invoked, before any processing takes place.
	 *
	 * This action fires for every call regardless of outcome (validation failure,
	 * permission denial, short-circuit, or successful execution), and before input
	 * normalization so the raw input is captured as-is.
	 *
	 * @since 7.1.0
	 *
	 * @param string     $ability_name The name of the ability.
	 * @param mixed      $input        The raw input data for the ability, before normalization.
	 * @param WP_Ability $ability      The ability instance.
	 */
	do_action( 'wp_ability_invoked', $this->name, $input, $this );

	$pre_execute_sentinel = new WP_Filter_Sentinel();

	/**
	 * Filters whether to short-circuit ability execution.
	 *
	 * Returning a value other than the received default bypasses the rest of `execute()` —
	 * input normalization, input validation, permission checks, the registered execute callback,
	 * output validation, and the surrounding actions — and the value is returned to the caller
	 * as-is. Useful for cached responses, rate limiting, maintenance mode, and test mocking.
	 *
	 * To continue with normal execution, return `$pre` unchanged. This preserves any value
	 * (including `null`, `false`, or arbitrary objects) as a valid short-circuit result.
	 *
	 * Because validation is bypassed, callers that short-circuit are responsible for the
	 * integrity of any value they consume from `$input`.
	 *
	 * @since 7.1.0
	 *
	 * @param mixed      $pre          The pre-computed result. Return this value unchanged to continue execution.
	 *                                 Default `WP_Filter_Sentinel` instance unique to this invocation.
	 * @param string     $ability_name The name of the ability.
	 * @param mixed      $input        The raw input passed to `execute()`.
	 * @param WP_Ability $ability      The ability instance.
	 */
	$pre = apply_filters( 'wp_pre_execute_ability', $pre_execute_sentinel, $this->name, $input, $this );
	if ( $pre !== $pre_execute_sentinel ) {
		return $pre;
	}

	$input = $this->normalize_input( $input );
	if ( is_wp_error( $input ) ) {
		return $input;
	}

	$is_valid = $this->validate_input( $input );
	if ( is_wp_error( $is_valid ) ) {
		return $is_valid;
	}

	$has_permissions = $this->check_permissions( $input );
	if ( true !== $has_permissions ) {
		if ( is_wp_error( $has_permissions ) ) {
			// Don't leak the permission check error to someone without the correct perms.
			_doing_it_wrong(
				__METHOD__,
				esc_html( $has_permissions->get_error_message() ),
				'6.9.0'
			);
		}

		return new WP_Error(
			'ability_invalid_permissions',
			/* translators: %s ability name. */
			sprintf( __( 'Ability "%s" does not have necessary permission.' ), $this->name )
		);
	}

	/**
	 * Fires before an ability gets executed, after input validation and permissions check.
	 *
	 * @since 6.9.0
	 * @since 7.1.0 Added the `$ability` parameter.
	 *
	 * @param string     $ability_name The name of the ability.
	 * @param mixed      $input        The input data for the ability.
	 * @param WP_Ability $ability      The ability instance.
	 */
	do_action( 'wp_before_execute_ability', $this->name, $input, $this );

	$result = $this->do_execute( $input );
	if ( is_wp_error( $result ) ) {
		return $result;
	}

	$is_valid = $this->validate_output( $result );
	if ( is_wp_error( $is_valid ) ) {
		return $is_valid;
	}

	/**
	 * Fires immediately after an ability finished executing.
	 *
	 * @since 6.9.0
	 * @since 7.1.0 Added the `$ability` parameter.
	 *
	 * @param string     $ability_name The name of the ability.
	 * @param mixed      $input        The input data for the ability.
	 * @param mixed      $result       The result of the ability execution.
	 * @param WP_Ability $ability      The ability instance.
	 */
	do_action( 'wp_after_execute_ability', $this->name, $input, $result, $this );

	return $result;
}

View all references View on Trac View on GitHub