/wp-abilities-api

Plugin-family patterns

This reference covers shared implementation mechanics — the call shape your execute callbacks follow when handing work to existing business logic. Two shapes are common enough across real-world WordPress plugins to be worth naming; which one fits is determined by how the backing controller is constructed, not by a choice you make up front. The choice still ripples through your delegate helper, your tests, and your error codes, so it's worth confirming early.

Family-specific registration conventions — loader path, ability category, MCP exposure defaults, error-code prefix house style — live in separate plugin-family overlays (for example, a WooCommerce-extension overlay), not in this reference. Apply any relevant overlay before scaffolding registration. The patterns below should stay portable: they describe how the execute callback talks to backing code, not what the registration metadata should look like for your plugin family.

There is also a third option that sits outside this dichotomy. If the operation does not yet have a shared service class — or if you can refactor toward one — extracting a service that the ability, the REST controller, and the UI all consume is the default per shared-core-service.md. Delegation through an existing REST controller (either shape below) is a conditional shortcut for low-stakes reads, not the starting point. Confirm the shape is right before you reach for either.

Shape: shared API client

Common in plugins that talk to a remote service (Stripe, a first-party SaaS, an upstream API). The plugin bootstraps a single API client, exposes it via a static accessor on a main plugin class, and every REST controller takes that client as a constructor argument.

Detection

# Inspect the backing REST controller's __construct signature.
grep -n "public function __construct" <path/to/rest-controller.php>

If the constructor takes a required typed argument (e.g. My_Plugin_API_Client $api_client), you're in the shared-API-client shape. Confirm the plugin has a central accessor:

grep -rn "get_api_client\|get_.*_api_client\|get_service" <path/to/plugin/main-class.php>

You're looking for a public static function get_<something>() that returns the shared client.

Minimal skeleton

<?php
namespace My_Plugin\Abilities;

class Abilities_Registrar {

    const CATEGORY_SLUG = 'my-plugin';

    public static function init() {
        add_action( 'wp_abilities_api_categories_init', [ __CLASS__, 'register_category' ] );
        add_action( 'wp_abilities_api_init', [ __CLASS__, 'register_abilities' ] );
    }

    public static function register_abilities() {
        wp_register_ability(
            'my-plugin/get-things',
            [
                'label'               => __( 'Get things', 'my-plugin' ),
                'description'         => __( 'List things with filters.', 'my-plugin' ),
                'category'            => self::CATEGORY_SLUG,
                'input_schema'        => [ /* ... */ ],
                'execute_callback'    => [ __CLASS__, 'execute_get_things' ],
                'permission_callback' => [ __CLASS__, 'current_user_has_capability' ],
                'meta'                => [
                    'annotations'  => [ 'readonly' => true, 'destructive' => false, 'idempotent' => true ],
                    'show_in_rest' => true,
                ],
            ]
        );
    }

    public static function execute_get_things( $input = null ) {
        return self::delegate_to_rest_controller(
            'My_Plugin_REST_Things_Controller',
            'get_things',
            '/my-plugin/v1/things',
            is_array( $input ) ? $input : null
        );
    }

    private static function delegate_to_rest_controller( $controller_class, $method, $route, $input, $http_method = 'GET' ) {
        $fqcn = '\\' . $controller_class;
        if ( ! class_exists( $fqcn ) ) {
            return new \WP_Error( 'my_plugin_not_initialized', __( 'My Plugin is not initialized.', 'my-plugin' ) );
        }

        // Shape specifics: fetch the shared API client and null-check.
        $api_client = null;
        if ( class_exists( '\My_Plugin' ) && method_exists( '\My_Plugin', 'get_api_client' ) ) {
            $api_client = \My_Plugin::get_api_client();
        }
        if ( null === $api_client ) {
            return new \WP_Error( 'my_plugin_not_initialized', __( 'My Plugin is not initialized.', 'my-plugin' ) );
        }

        $request = new \WP_REST_Request( $http_method, $route );
        if ( is_array( $input ) ) {
            foreach ( $input as $param => $value ) {
                $request->set_param( $param, $value );
            }
        }

        $controller = new $fqcn( $api_client );
        $response   = $controller->{$method}( $request );

        if ( is_wp_error( $response ) ) {
            return $response;
        }
        if ( $response instanceof \WP_REST_Response ) {
            $data = $response->get_data();
            return is_array( $data ) ? $data : [];
        }
        return is_array( $response ) ? $response : [];
    }
}

Testing implications

• Bootstrap test doubles need the API client. Unit tests that instantiate controllers must provide a mocked or stubbed client; otherwise the constructor fails with ArgumentCountError: Too few arguments.
• The "not initialized" error path is reachable and must be covered. One unit test should stub the accessor to return null and assert the ability returns <plugin>_not_initialized. This is a common failure during partial bootstraps (WP-CLI with restricted loading, test harnesses, admin pages with conditional autoloading).
• Integration tests need real or faked HTTP. The backing controller will hit the upstream unless the API client is mocked, so integration harnesses typically route through a fake transport.

Worked example: a plugin that talks to an external SaaS or upstream HTTP service typically follows this pattern. The plugin's main class exposes the API client via a static accessor (e.g. Plugin_Main::get_api_client()); REST controllers extend a base class whose constructor takes that client as a typed argument; the abilities registrar pulls the client through the same accessor before constructing controllers.

Shape: zero-arg controllers

Common in plugins/packages that delegate primarily to WordPress core mechanisms (custom post types, options, meta) and don't maintain a single shared API client. Controllers instantiate cleanly without a dependency graph.

Detection

grep -n "public function __construct" <path/to/rest-controller.php>

If the constructor takes no required arguments, or takes only simple scalars you can hardcode at the ability call site (e.g. a post-type string), you're in the zero-arg shape.

Also grep the plugin's main bootstrap class for the absence of a singleton API accessor — if there isn't one, the zero-arg shape is the honest choice.

Minimal skeleton

<?php
namespace My_Plugin\Abilities;

class Abilities_Registrar {

    const CATEGORY_SLUG = 'my-plugin';

    public static function init() {
        add_action( 'wp_abilities_api_categories_init', [ __CLASS__, 'register_category' ] );
        add_action( 'wp_abilities_api_init', [ __CLASS__, 'register_abilities' ] );
    }

    public static function register_abilities() {
        wp_register_ability(
            'my-plugin/get-things',
            [
                /* ... */
                'execute_callback' => [ __CLASS__, 'execute_get_things' ],
                /* ... */
            ]
        );
    }

    public static function execute_get_things( $input = null ) {
        $input    = is_array( $input ) ? $input : [];
        $endpoint = new \My_Plugin_Things_Endpoint();
        $request  = new \WP_REST_Request( 'GET', '/my-plugin/v1/things' );

        foreach ( [ 'page', 'per_page', 'status', 'search' ] as $key ) {
            if ( isset( $input[ $key ] ) ) {
                $request->set_param( $key, $input[ $key ] );
            }
        }

        $response = $endpoint->get_items( $request );
        if ( is_wp_error( $response ) ) {
            return $response;
        }
        return $response instanceof \WP_REST_Response ? $response->get_data() : $response;
    }
}

No helper is required — the construction step is a single line and inlining per callback stays readable. If you do extract a helper, it takes a constructor_args parameter because the controller class isn't constant across abilities:

/**
 * @param string     $controller_class Fully-qualified controller class.
 * @param string     $method           Method to invoke on the request.
 * @param string     $route            REST route used when constructing WP_REST_Request.
 * @param array|null $input            Ability input (or null).
 * @param string     $http_method      HTTP method. Defaults to 'GET'.
 * @param array      $constructor_args Optional scalar args for the controller's constructor.
 * @return array|\WP_Error
 */
private static function delegate_to_rest_controller(
    $controller_class,
    $method,
    $route,
    $input,
    $http_method = 'GET',
    $constructor_args = array()
) {
    /* ... */
}

The phpDoc carries the array|\WP_Error return shape; the function signature itself stays untyped on the return so this snippet parses on PHP 7.2+.

See delegate-helper-pattern.md for the full helper signature and guards.

Testing implications

• No API-client mock needed. Unit tests instantiate the ability registrar directly and call execute_* with input arrays.
• Test at the wp_get_ability() level when possible. With zero-arg controllers the backing often exists in WordPress core territory (e.g. custom post types), so integration tests can exercise the full pipeline without a fake transport.
• The <plugin>_not_initialized failure mode is less common. It still exists — if a package isn't loaded, class_exists on the backing controller still fails — but the surface area is smaller.

Worked example: a plugin whose REST controllers wrap a custom post type, taxonomy, option, or meta typically follows this pattern. Each execute callback constructs its controller inline (e.g. new My_CPT_Endpoint( 'my_cpt' )), passing whatever scalar (post-type slug, taxonomy name) the controller needs. No shared helper in the registrar; the construction step is small enough to inline.

Hybrid cases

A single plugin can legitimately use both patterns across different abilities:

• A shared-API-client ability for backing controllers that talk to the upstream service.
• A zero-arg ability for backing controllers that only touch WP core (e.g. a CPT-based settings endpoint in the same plugin).

If this happens, the helper in delegate-helper-pattern.md can support both via optional constructor_args — but resist the temptation to over-engineer until you have at least two zero-arg abilities that would share the helper.

Anti-pattern — inventing an API client where there isn't one

Don't introduce a fake shared API client to fit the shared-client helper shape. If the plugin is genuinely stateless / CPT-driven, inline construction is the honest answer. The helper is scaffolding that pays back when you have 4+ abilities sharing the build-request → instantiate → unwrap flow; before that, inline code is faster to read and review.

Picking quickly