AI Agent Guidance
This guidance targets Better Route 2.0, PHP 8.3+. Read migration guidance before changing an existing integration and release notes for the scope.
Resolve the actual version first
composer show better-route/better-route
composer require better-route/better-route:^2.0
composer check-platform-reqs --no-dev
The Composer package version, application REST namespace and OpenAPI info.version are independent. Do not rename an application's routes when updating the library. PHP 8.1/8.2 consumers can use the 1.1.3 security patch without the 2.0 runtime change.
Skill discovery and freshness
Use the portable, public Better Route skill collection. It contains 25 task-specific Markdown skills, including Analytics and the PHP 8.3 upgrade. Check each skill's tested-version metadata and the installed package version; the format works with compatible agent clients without requiring a particular hosted tool service.
| Task | Skills | Documentation |
|---|---|---|
| Install, migrate, raw routes | br-install-and-migrate, br-routes | Install, Migration |
| PHP 8.3 compatibility | br-php83-upgrade | 2.0 migration |
| Resource CRUD and permissions | br-resource-cpt, br-resource-table, br-resource-policy, br-write-schema, br-owned-resource-guards | Resource API |
| Authentication and network | br-auth-middleware, br-jwks-jwt-auth, br-hmac-signature, br-network-security | Middleware catalog |
| Write safety | br-idempotency, br-atomic-idempotency, br-optimistic-locking, br-single-use-token | Migration |
| Browser reads and errors | br-cors-public-client, br-etag-cache, br-rate-limiting, br-error-contract | Error contract |
| Woo CRUD | br-woo-routes | Configuration, Customers, Coupons |
| Native reports | br-woo-analytics | Analytics |
| Contracts | br-openapi | OpenAPI |
| Observability and crypto | br-audit-enrichment, br-crypto | Middleware catalog |
Non-obvious integration rules
- Register during rest_api_init. Every raw route needs explicit permission/public/middleware intent; protectedByMiddleware alone does not authenticate or authorize a request.
- WordPress args validation runs before the permission callback. Keep validators cheap and side-effect-free. Native pre-handler errors can retain WordPress's error format.
- CustomerRolePolicy applies across list/detail/mutations. Request roles only narrow it; privileged targets need explicit trusted opt-in and native mutation capabilities still apply.
- Customer list and coupon list/detail defaults omit metadata; customer detail/write responses can include filtered public metadata. Protect authorization/session keys and coupon internal metadata; never replace service-specific guards with a generic metadata helper.
- Coupon state is read-only management information, not checkout eligibility.
- Analytics is manually registered. Preserve native WP identity, upstream report permissions
and historical import readiness. Unlike Woo CRUD, it rejects
_locale,_fieldsand context. - Use strict OpenAPI export and validate serialized JSON. Supply custom schemas and actual auth definitions; permission callbacks are not inferred as security schemes. PUT/PATCH IDs differ, and ambiguous operations/configuration now fail explicitly.
Evidence before a release
composer test
composer analyse
composer cs-check
php tests/openapi/export.php /tmp/better-route-openapi.json
python -m pip install -r tests/openapi/requirements.txt
python tests/openapi/validate.py /tmp/better-route-openapi.json
Run native WP/Woo checks against disposable synthetic data and the host's actual auth/cache stack. The 2.0 CI covers PHP 8.3–8.5, plus WP 6.9.4/Woo 10.9.4 runtime checks on PHP 8.3/8.5 with HPOS/CPT and native ownership checks. That is not evidence for every version, external IdP, background import or third-party extension combination. Report uncovered deployment paths explicitly.