Subchapter 3.9

Shared Core Service

references/shared-core-service.mdMarkdown15 KBView on GitHub

Shared core service — keeping abilities in lockstep with REST and UI

When an ability mirrors something a human can already do through a supported UI or workflow, the ability MUST consume the same code path as that UI or workflow — same permissions, same validation, same business rules. Three call sites for the same operation (UI, REST, ability — possibly CLI too) drift apart over time unless they all delegate to a shared service.

Shared Core Service · Wp Abilities API · WordPress/agent-skills · Skills Docs

Shape	Example	Verdict
Re-implement the logic in the execute callback.	The callback runs its own SQL, applies its own permission checks, builds its own response.	Avoid. Guaranteed drift the first time the original code path changes.
Delegate to the existing REST controller via `WP_REST_Request`.	The ability builds a `WP_REST_Request` from its input, dispatches via `rest_do_request()`, and returns the response data. The dispatched request flows through the registered controller’s permission check, validation, and handler.	Conditional shortcut. Acceptable only when all three hold: the backing handler is a pure data-fetch (read-only, no side effects), the operation is itself a read, and the ability runs predominantly inside REST contexts. Read “Side effects on the existing REST path” below before assuming the conditions hold.
Extract a service class that ability + REST controller + UI handler all consume.	`My_Plugin::get_things_service()->list( $args )` called from the ability, the REST controller, and an admin-side handler.	Default. Choose this unless every delegation condition above holds. It is the only shape that removes drift entirely and the only shape that scales when an endpoint later grows a side effect, a write counterpart, or a non-REST caller.

public static function execute_get_things( $input = null ) {
    $request = new WP_REST_Request( 'GET', '/my-plugin/v1/things' );
    $request->set_query_params( (array) $input );

    $response = rest_do_request( $request );
    if ( $response->is_error() ) {
        return $response->as_error();
    }

    return $response->get_data();
}

// includes/admin/class-rest-things-controller.php
class My_Plugin_REST_Things_Controller {
    public function get_things( WP_REST_Request $request ) {
        $args = self::sanitize_query_args( $request->get_params() );
        $rows = $this->repo->find( $args );

        // Side effects (audit log, hooks, notifications) live on the REST adapter.
        do_action( 'my_plugin/things_listed', $rows );

        return rest_ensure_response( array_map( [ $this, 'format' ], $rows ) );
    }
}

// src/Internal/Abilities/Abilities_Registrar.php
public static function execute_get_things( $input = null ) {
    // PROBLEM: re-implements sanitization, repo call, formatting.
    // Drifts the first time the controller's get_things() changes.
    $args = MyPlugin\Sanitize::query_args( (array) $input );
    $rows = ( new MyPlugin\Things_Repo() )->find( $args );
    return array_map( [ MyPlugin\Things_Formatter::class, 'format' ], $rows );
}

// src/Service/class-things-service.php
class Things_Service {
    public function list_things( array $args ) {
        $clean = Sanitize::query_args( $args );
        $rows  = $this->repo->find( $clean );
        return array_map( array( Things_Formatter::class, 'format' ), $rows );
    }
}

// includes/admin/class-rest-things-controller.php
class My_Plugin_REST_Things_Controller {
    public function get_things( WP_REST_Request $request ) {
        $rows = $this->service->list_things( $request->get_params() );

        // Side effects (audit log, hooks, notifications) stay on the REST adapter — clean.
        do_action( 'my_plugin/things_listed', $rows );

        return rest_ensure_response( $rows );
    }
}

// src/Internal/Abilities/Abilities_Registrar.php
public static function execute_get_things( $input = null ) {
    if ( ! class_exists( '\MyPlugin\Things_Service' ) ) {
        return new WP_Error( 'myplugin_not_initialized', __( 'My Plugin is not initialized.', 'my-plugin' ) );
    }
    return MyPlugin::get_things_service()->list_things( (array) $input );
}

Shared Core Service