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 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Lonsdale201/wp-agent-skills --skill bd-better-route-bridge技能说明
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_routedirectly inside my better-data consumer code, parseWP_REST_Requestmyself, and callMyDto::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:
- Register the route on
better-route'sRoutervia the appropriate HTTP-verb method. - On request, hydrate a
WP_REST_Request-shaped object into the DTO (URL params, JSON body, query string — buckets resolved persourceoption). - 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). - Validate the DTO via the
BuiltInValidator. - Call the handler with
(DataObject $dto, mixed $request). - If the handler returns a
DataObject, present throughPresenter::for($dto)->context(PresentationContext::rest()).
Other AI-prone misconceptions:
- "I'll add
better-route/better-routeas 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
permissionCallbackinside the DTO." Wrong — those are route-owned and pass through the bridge's$optionsto better-route'sRouteBuilder. 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
DataObjectfor 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'
阅读完整来源 ↗