Register the complete router during rest_api_init and declare the access intent of every route.
use BetterRoute\\Http\\Response;\nuse BetterRoute\\Router\\Router;\n\nadd_action('rest_api_init', static function (): void {\n $router = Router::make('myapp', 'v1');\n\n $router->get('/ping', static fn (): Response => Response::ok(['pong' => true]))\n ->publicRoute();\n\n $router->register();\n});\nIn 1.1 an omitted permission denies every raw route. This applies to GET, HEAD-style reads registered through the router, writes, and explicit OPTIONS routes.
Choose exactly one intent:
\n// WordPress permission/capability gate.\n$router->get('/admin/report', $handler)\n ->permission(static fn (): bool => current_user_can('manage_options'));\n\n// Let middleware authenticate/authorize after WordPress dispatches.\n$router->post('/account/orders', $handler)\n ->protectedByMiddleware('bearerAuth')\n ->middleware([$jwt]);\n\n// Deliberately anonymous. Also emits OpenAPI security: [].\n$router->post('/webhooks/provider', $handler)\n ->publicRoute()\n ->middleware([$signature]);\nDo not combine protectedByMiddleware() and permission() on one route. Both set the WordPress permission callback; the later call replaces the earlier intent.
Pass WordPress REST regex routes, not framework-style braces:
\n$router->get('/articles/(?P<id>\\d+)', $handler)\n ->publicRoute()\n ->args([\n 'id' => [\n 'required' => true,\n 'type' => 'integer',\n ],\n ]);\n/articles/{id} is an OpenAPI rendering, not a WordPress registration pattern.
WordPress validates and sanitizes registered args before permission_callback runs. Keep validate_callback and sanitize_callback cheap, deterministic, and side-effect free. Perform expensive or authorization-dependent validation in the handler or Resource writeSchema().
Use the signature deliberately:
\nuse BetterRoute\\Http\\RequestContext;\n\n// Zero parameters.\nstatic fn (): array => ['ok' => true];\n\n// One untyped/non-RequestContext parameter receives WP_REST_Request.\nstatic function ($request): array {\n return ['id' => (int) $request->get_param('id')];\n}\n\n// A RequestContext-compatible type receives RequestContext.\nstatic function (RequestContext $context): array {\n return ['requestId' => $context->requestId];\n}\n\n// Two parameters always receive RequestContext, then the WP request.\nstatic function (RequestContext $context, $request): array {\n return ['id' => (int) $request->get_param('id')];\n}\nA union containing RequestContext also selects the context for a one-parameter handler. A handler may require at most two parameters.
Callable forms supported by 1.1 include closures, callable objects, static [ClassName::class, 'method'] handlers, and instantiable handler classes. If a non-static class handler needs constructor arguments, instantiate it through the plugin container and pass the object; the router will not invent dependencies.
Return a BetterRoute\\Http\\Response, WP_REST_Response, array/scalar, or WP_Error. Arrays/scalars become 200 responses. Throw ApiException for an intentional normalized error.
$router->group('/account', static function (Router $router) use ($jwt): void {\n $router->middleware([$jwt]);\n\n $router->get('/me', $me)->protectedByMiddleware('bearerAuth');\n $router->patch('/profile', $update)->protectedByMiddleware('bearerAuth');\n});\nGlobal middleware runs before group middleware, which runs before route middleware. Nested group state is unwound in a finally block in 1.1, so an exception while defining one group cannot leak its prefix or middleware into later routes.
An explicit preflight route also needs intent:
\n$router->options('/account/profile', static fn () => null)\n ->publicRoute()\n ->middleware([$cors]);\nWhen CorsMiddleware is attached, its WordPress bridge can answer a matched preflight before normal dispatch and replace WordPress core CORS headers. See br-cors-public-client for the policy rules.
Call $router->register() during rest_api_init. Better-route 1.1 throws a clear RuntimeException when:
register_rest_route() is unavailable;rest_api_init has fired; orfalse while registering a route.Do not treat these as silent missing-route cases.
\npermission(), protectedByMiddleware(), or publicRoute().(?P<name>...) WordPress path parameters and declare their args.RequestContext only when it should receive the context; otherwise it receives the WP request.args validation cheap because WordPress runs it before permission checks.rest_api_init and call register() once after declarations.meta(['openapi' => ['include' => false]]) to omit a route from filtered OpenAPI contracts.br-auth-middleware for protectedByMiddleware() implementations.br-cors-public-client for browser preflight and authoritative CORS headers.br-openapi for contract export.br-error-contract for ApiException and normalized responses.src/Router/Router.phpsrc/Router/RouteBuilder.phpsrc/Router/WordPressRestDispatcher.phpsrc/Router/ArgumentResolver.phpsrc/Http/RequestContext.php