Skip to main content

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.

TaskSkillsDocumentation
Install, migrate, raw routesbr-install-and-migrate, br-routesInstall, Migration
PHP 8.3 compatibilitybr-php83-upgrade2.0 migration
Resource CRUD and permissionsbr-resource-cpt, br-resource-table, br-resource-policy, br-write-schema, br-owned-resource-guardsResource API
Authentication and networkbr-auth-middleware, br-jwks-jwt-auth, br-hmac-signature, br-network-securityMiddleware catalog
Write safetybr-idempotency, br-atomic-idempotency, br-optimistic-locking, br-single-use-tokenMigration
Browser reads and errorsbr-cors-public-client, br-etag-cache, br-rate-limiting, br-error-contractError contract
Woo CRUDbr-woo-routesConfiguration, Customers, Coupons
Native reportsbr-woo-analyticsAnalytics
Contractsbr-openapiOpenAPI
Observability and cryptobr-audit-enrichment, br-cryptoMiddleware 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, _fields and 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.