Route Cache Reference

Webrick route cache stores compiled routing artifacts so boot and match work can be reused across requests.

Modes

• sharded: directory of PHP artifacts

• fused: single PHP artifact file

• generated: no route-cache artifact files

Build with PHP API

use Infocyph\Webrick\Support\RouteCache;

RouteCache::build([
    'matcher' => 'sharded',
    'cache' => __DIR__ . '/../.route-cache',
    'routes' => __DIR__ . '/../routes.php',
    'signKey' => $_ENV['WEBRICK_SIGN_KEY'] ?? 'dev-key',
    'signedDefaultTtl' => 900,
    'registrarOptions' => [
        'exposeUrlServices' => true,
        'urlBaseUri' => $_ENV['WEBRICK_URL_BASE_URI'] ?? 'http://localhost',
    ],
]);

Build with CLI

php ./webrick route:cache --matcher=sharded --cache=.route-cache --routes=routes.php
php ./webrick route:clear --matcher=sharded --cache=.route-cache

Runtime wiring

use Infocyph\Webrick\Router\Definition\Registrar;
use Infocyph\Webrick\Router\Kernel\RouterKernel;
use Infocyph\Webrick\Router\Matching\ShardedMatcher;
use Psr\Log\NullLogger;

$kernel = RouterKernel::bootWithRegistrar(
    log: new NullLogger(),
    matcher: ShardedMatcher::make(__DIR__ . '/../.route-cache'),
    register: static function (Registrar $registrar): void {
        unset($registrar);
        require __DIR__ . '/../routes.php';
    },
    routeCache: __DIR__ . '/../.route-cache',
);

Use .route-cache/__routes.php instead when you choose fused mode.

What the cache includes

• compiled route tables

• name-to-path and name-to-domain lookup metadata

• middleware and domain metadata

• URL-generation templates used by Route::urlFor(...)

Operational notes

• Build cache during CI or deploy, not during live request handling in production.

• Keep route registration flow identical between cache builds and runtime boot.

• Preserve the .route-cache/.gitignore sentinel when clearing sharded caches.

• When signed URL generation is enabled, keep signKey, TTL defaults, and urlBaseUri aligned between build and runtime.