Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Search & research

bd-better-route-bridge

Compose better-data DTOs with the better-route library — use BetterRouteBridge::{get, post, put, patch, delete} to register a REST route that hydrates the request into a DTO, validates, calls the handler with (DataObject, mixed $request), and presents returned DataObject values through Presenter with PresentationContext::rest(). Contract — the bridge is method-name based (duck-types Router / RouteBuilder) so better-data takes no hard Composer dependency on better-route. URL-owned fields go into routeFields option — those are merged from URL params AND rejected from JSON / body / query buckets via RequestParamCollisionException; this is the route-side equivalent of RequestSource::noCollision. Use when wiring DTO-backed REST endpoints, feeding DTO schemas into better-route's OpenAPI exporter, or moving request data from a route handler into a better-data DataObject. Triggers on BetterRouteBridge::get/post/put/patch/delete, routeFields, RequestParamCollisionException, OpenAPI / OpenApi DT

Lonsdale201 · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add Lonsdale201/wp-agent-skills --skill bd-better-route-bridge

About this skill


name: bd-better-route-bridge description: Compose better-data DTOs with the better-route library — use BetterRouteBridge::{get, post, put, patch, delete} to register a REST route that hydrates the request into a DTO, validates, calls the handler with (DataObject, mixed $request), and presents returned DataObject values through Presenter with PresentationContext::rest(). Contract — the bridge is method-name based (duck-types Router / RouteBuilder) so better-data takes no hard Composer dependency on better-route. URL-owned fields go into routeFields option — those are merged from URL params AND rejected from JSON / body / query buckets via RequestParamCollisionException; this is the route-side equivalent of RequestSource::noCollision. Use when wiring DTO-backed REST endpoints, feeding DTO schemas into better-route's OpenAPI exporter, or moving request data from a route handler into a better-data DataObject. Triggers on BetterRouteBridge::get/post/put/patch/delete, routeFields, RequestParamCollisionException, OpenAPI / OpenApi DTO schema in better-data. metadata: wp-skills-author: "Soczó Kristóf" wp-skills-contact: "mailto:lonsdale201@hotmail.com" wp-skills-plugin: "better-data" wp-skills-plugin-version-tested: "phase-9" wp-skills-php-min: "8.3" wp-skills-last-updated: "2026-04-29"

better-data: Composing with better-route

For developers using better-data and better-route together — DTO-backed REST endpoints, OpenAPI generation from DTO schemas, request hydration into typed DataObject instances inside route handlers. The integration seam is the optional BetterRouteBridge (src/Route/BetterRouteBridge.php); using it correctly keeps the data layer free of router concerns and the router layer free of data-shape concerns.

Misconception this skill corrects

"I'll just use register_rest_route directly inside my better-data consumer code, parse WP_REST_Request myself, and call MyDto::fromArray($request->get_params())."

That works for one route. For an API of 10+ routes, it duplicates the request-parsing, validation, route-owned-field, and Presenter-projection wiring at every callsite. The bridge centralizes that pipeline:

  1. Register the route on better-route's Router via the appropriate HTTP-verb method.
  2. On request, hydrate a WP_REST_Request-shaped object into the DTO (URL params, JSON body, query string — buckets resolved per source option).
  3. Reject collisions: a route-owned field like id (in the URL /posts/{id}) MUST NOT also appear in the JSON body — RequestParamCollisionException (line 194, 680).
  4. Validate the DTO via the BuiltInValidator.
  5. Call the handler with (DataObject $dto, mixed $request).
  6. If the handler returns a DataObject, present through Presenter::for($dto)->context(PresentationContext::rest()).

Other AI-prone misconceptions:

  • "I'll add better-route/better-route as a hard runtime dep of better-data so the bridge always works." Wrong — the bridge is deliberately duck-typed by method name (class docblock at lines 21-26) so better-data installs without better-route. Don't break that.
  • "Permission and middleware concerns are data-layer, so I'll put permissionCallback inside the DTO." Wrong — those are route-owned and pass through the bridge's $options to better-route's RouteBuilder. The data layer doesn't care who's allowed; the route layer does.
  • "I'll reimplement better-route's Resource DSL inside better-data so consumers only need one library." Wrong — the bridge composes; it doesn't replace either side. Keep the boundary.

When to use this skill

Trigger when ANY of the following is true:

  • The diff or PR registers a REST route AND uses a DataObject for request parsing or response shaping.
  • Calls to BetterRouteBridge::{get, post, put, patch, delete}.
  • The diff modifies src/Route/BetterRouteBridge.php.
  • OpenAPI exporter setup that includes DTO schemas.
  • The consumer asks "how do I get a DTO from WP_REST_Request?" or "how do I avoid duplicating request parsing across 20 routes?".

Workflow

1. Read better-route's flow first when behavior is unclear

Don't edit better-route from a better-data PR. The relevant files in the sibling repo:

  • ../better-route/README.md — overview.
  • ../better-route/src/Router/Router.php — main entry.
  • ../better-route/src/Router/RouteBuilder.php — fluent builder for one route.
  • ../better-route/src/OpenApi/OpenApiExporter.php — schema export.

Use the bridge as the integration seam; if you find yourself wanting to change better-route to make the bridge work, that's a sign the bridge needs to absorb the concern instead.

2. Register a read route

use BetterData\Route\BetterRouteBridge;
use MyPlugin\Dto\PostDto;

$router = my_plugin_get_router();  // returns the better-route Router instance

BetterRouteBridge::get(
    $router,
    '/posts/{id}',
    PostDto::class,
    function (PostDto $dto, $request) {
        // $dto is hydrated from URL params (id in particular)
        // $request is the original better-route / WP_REST_Request-ish object
        return PostDto::fromPost($dto->id);  // re-hydrate from store, return for projection
    },
    [
        'routeFields'        => ['id'],  // 'id' lives in the URL, not in body / query
        'permissionCallback' => 'is_user_logged_in',
    ],
);

The handler returns a DataObject. The bridge wraps the response through Presenter::for($returned)->context(PresentationContext::rest())->toArray(), applying Sensitive / Secret redaction automatically.

3. Register a write route

BetterRouteBridge::post(
    $router,
    '/posts',
    CreatePostDto::class,
    function (CreatePostDto $dto, $request) {
        $id = $dto->saveAsPost();  // via HasWpSinks
        return PostDto::fromPost($id);
    },
    [
        // No routeFields — entire DTO comes from JSON body
        'permissionCallback' 
Read the complete source ↗