routing-and-caching

Statamic Routing and Caching

Collection Routes

Define URL patterns for collection entries in the collection's YAML configuration file (e.g., content/collections/blog.yaml). The route property controls how Statamic generates and resolves URLs for every entry in the collection.

Single-site route

route: /blog/{slug}

Available route variables include {slug}, {year}, {month}, {day}, and any field defined on the entry's blueprint. Combine variables to create structured URL hierarchies:

route: /blog/{year}/{month}/{slug}    # Date-based: /blog/2026/03/my-post
route: /docs/{parent_slug}/{slug}     # Nested: /docs/getting-started/installation

The route pattern determines both URL generation (when outputting {{ url }} in templates) and URL resolution (when Statamic matches an incoming request to an entry). If no route is defined on a collection, its entries have no front-end URLs.

Multisite routes

Specify per-site route patterns when running a multisite installation:

route:
  en: /blog/{slug}
  fr: /blogue/{slug}

Each site handle maps to its own URI pattern, allowing fully localized URL structures while sharing the same underlying collection. Ensure every configured site has an entry in the route map, or entries for that site will lack front-end URLs.

Statamic Routes (Route::statamic)

Register template-based routes in routes/web.php using Route::statamic(). These routes render Antlers (or Blade) templates without requiring a controller or entry.

Route::statamic('about', 'about');                         // URI + template
Route::statamic('about', 'about', ['title' => 'About']);   // URI + template + injected data
Route::statamic('things/{thing}', 'things.show');          // Route with parameters
Route::statamic('feed', 'feed', ['content_type' => 'atom']); // Custom content type

First argument: the URI pattern. Second argument: the template name (dot notation resolves to subdirectories). Third argument (optional): an array of data injected into the template's cascade, plus special keys like content_type.

Use Route::statamic for one-off pages that do not belong to a collection (contact, legal, feeds, sitemaps). These routes participate in the Antlers cascade, so layout variables, globals, and nav data are all available within the rendered template.

Standard Laravel routes (Route::get, Route::post, etc.) still work alongside Statamic routes. Use standard Laravel routes for form handlers, webhooks, or any endpoint that returns JSON rather than a rendered template.

Error Pages

Create error templates at resources/views/errors/{status_code}.antlers.html to customize error responses. Common status codes:

• 404.antlers.html -- Page not found
• 500.antlers.html -- Server error
• 503.antlers.html -- Maintenance mode

Define a shared error layout at resources/views/errors/layout.antlers.html. Error templates receive the standard Antlers cascade, including globals and navigation data, so maintain consistent site chrome on error pages.

Statamic checks for a matching status-code template first. If none exists, Laravel's default error handling takes over. Create at minimum a 404.antlers.html template for every project.

Headless Mode

Disable all front-end routes to run Statamic as a headless CMS (API-only or CP-only):

// config/statamic/routes.php
'enabled' => false,

When disabled, Statamic serves no front-end pages. The Control Panel and REST/GraphQL APIs remain active. Use this configuration when a separate front-end application (Next.js, Nuxt, SvelteKit, etc.) consumes content exclusively via the Content API or GraphQL endpoint. Collection routes, Route::statamic calls, and error page templates are all bypassed in headless mode.

Caching

Statamic provides four distinct caching layers. Understand each layer to diagnose performance issues and configure appropriate invalidation.

Layer 1: Stache (Content Cache)

The Stache is Statamic's flat-file indexing system. It reads YAML/Markdown content files and builds an in-memory index for fast querying. The Stache cannot be disabled -- it is fundamental to how Statamic resolves content.

Key commands:

php please stache:clear     # Remove all Stache indexes
php please stache:warm      # Rebuild all Stache indexes from content files
php please stache:refresh   # Clear + rebuild in one step
php please stache:doctor    # Diagnose Stache issues

Configuration (config/statamic/stache.php):

'watcher' => env('STATAMIC_STACHE_WATCHER', 'auto'), // auto|true|false
'stores' => [
    'entries' => ['directory' => base_path('content/collections')],
],
'indexes' => ['custom_field'], // Additional fields to index for query performance
'lock' => ['enabled' => true, 'timeout' => 30],

• watcher: Controls file-change detection. Set to auto (recommended) or false in production when content does not change on disk between deploys.
• stores: Map store names to content directories. Rarely changed from defaults.
• indexes: Add field names that appear in where clauses to speed up queries.
• lock: Prevents concurrent Stache rebuilds. Keep enabled in production.

Layer 2: Application Cache

The standard Laravel cache, used by Statamic for computed data and query results. Backed by the configured cache driver (file, Redis, Memcached, etc.).

php artisan cache:clear    # Clear the entire application cache

Clearing the application cache does not affect the Stache or static cache.

Layer 3: View Fragments

Cache expensive template sections using the Antlers cache tag:

{{ cache for="1 hour" }}
    {{# Expensive query or computation here #}}
{{ /cache }}

Fragment caches are stored in the application cache and respect the same cache driver and TTL configuration. Use for navigation trees, sidebar widgets, footer content, or any repeated partial that performs expensive queries. The for parameter accepts human-readable durations: "30 minutes", "1 hour", "1 day".

Nest fragment caches carefully -- avoid caching an outer block that already contains cached inner blocks, as this can lead to stale content or redundant cache entries.

Layer 4: Static Caching

Full-page caching for maximum performance. Two strategies are available.

Half Measure (Application Driver)

Store rendered pages in the Laravel cache. Requests still pass through PHP, but skip template rendering. Approximately 50% faster than uncached responses.

// config/statamic/static_caching.php
'strategy' => 'half',

No server configuration changes required. Suitable for sites where full-measure server rewrite setup is impractical, or for pages that need some dynamic behavior (e.g., CSRF tokens, session-dependent content). The half measure still respects invalidation on content save.

Full Measure (File Driver)

Generate static .html files served directly by the web server, bypassing PHP entirely. Response times around 2ms.

// config/statamic/static_caching.php
'strategy' => 'full',
'strategies' => ['full' => [
    'driver' => 'file',
    'path' => public_path('static'),
    'warm_concurrency' => 25,
]],

Requirements:

• Server rewrite rules for Apache, Nginx, or IIS to serve static files before hitting PHP.
• Auto-invalidation triggers on content save through Statamic's event system.

Static cache commands:

php please static:warm           # Crawl all URLs and generate cached pages
php please static:warm --queue   # Run warming in the background via queue
php please static:clear          # Remove all cached static pages

Set warm_concurrency to control how many pages are warmed in parallel during static:warm. Start with 25 and adjust based on server capacity.

Choosing a strategy

Criterion	Half Measure	Full Measure
Speed gain	~50% faster	~98% faster (2ms responses)
Server config	None	Rewrite rules required
Dynamic content	Supported (runs PHP)	Not supported (static HTML)
Setup complexity	Low	Medium

Use the {{ nocache }} tag to exclude dynamic sections (forms, user-specific content) from static caching when using the full measure. Content within {{ nocache }}...{{ /nocache }} blocks is rendered on each request even when the surrounding page is served from the static cache.

Deployment Checklist

Follow these steps when deploying Statamic to production:

1. Set environment variables:

   • APP_ENV=production
   • APP_DEBUG=false
   • STATAMIC_STACHE_WATCHER=false (or auto)

2. Warm the Stache after deploy:

   php please stache:warm
   

3. Configure static caching for performance (half or full measure as appropriate).

4. Rebuild search indexes:

   php please search:update --all
   

5. Clear application cache if deploy script requires it:

   php artisan cache:clear
   

6. Configure Git Automation push for content changes made through the Control Panel.

A typical deploy script runs these in sequence: cache:clear -> stache:warm -> static:warm -> search:update --all.

Common deployment pitfalls

• Forgetting stache:warm: First request after deploy triggers a cold Stache build, causing a slow response for that visitor. Always warm proactively.
• Leaving APP_DEBUG=true: Exposes stack traces and sensitive configuration to end users. Verify this is false before going live.
• Stache watcher in production: Setting STATAMIC_STACHE_WATCHER=true on a server where files do not change between deploys wastes resources on filesystem polling. Use false or auto.
• Missing static cache invalidation: If using full-measure static caching, ensure the deploy script runs static:clear before static:warm to avoid serving stale pages.

Key Conventions

• Use Antlers (.antlers.html) as the default template language.
• Prefix partial-only views with an underscore: _card.antlers.html.
• Store content as flat files unless scaling demands the Eloquent driver.
• Use inject on collections for default cascade values.
• Never commit .env to version control.
• Access configuration in templates with {{ config:app:key }} syntax.
• Use version range constraints (^6.0) in composer.json.
• Maintain a README documenting any overrides to Statamic defaults.

CLI Commands

For the complete Statamic CLI command reference organized by category (project management, content creation, cache management, search, code generation, git/deployment, imports/migrations, starter kits, and updating), see references/cli-commands.md.

Essential cache commands (quick reference)

Command	Purpose
php please stache:clear	Remove Stache indexes
php please stache:warm	Rebuild Stache from files
php please stache:refresh	Clear + warm in one step
php please static:warm	Crawl and cache all pages
php please static:clear	Remove all static cache files
php artisan cache:clear	Clear Laravel application cache
php please glide:clear	Clear image manipulation cache