Routing

Overview

All site requests are handled by Statamic unless you create your own Laravel routes. Here are the ways Statamic defines URLs.

Content Routes

Collection entries and taxonomy terms can have their own URLs as defined by their own flexible route patterns in their respective configuration areas.

Statamic Routes

Statamic provides a Route::statamic() method to do all the CMS "magic" for you, like injecting data (globals and system variables, for example), applying middleware, fetching the view, layout, and so on.

Route::statamic('uri', 'view', ['foo' => 'bar']);

{{ myglobal }} // globals are available
{{ foo }} // bar

{{ $myglobal }} // globals are available
{{ $foo }} // bar

The first argument is the URI, the second is the name of the template, and the third is an optional array of additional data.

When the template is the same as the URI, you can provide the one argument and Statamic will fall back to use the URI as the template:

Route::statamic('my-page'); // Implies 'my-page'
Route::statamic('/my-page'); // Implies 'my-page'
Route::statamic('/foo/bar'); // Implies 'foo.bar'

Parameters

You may use wildcard parameters in your routes. This allows you to match multiple URLs with the same route.

Route::statamic('things/{thing}', 'things.show');

The parameter values will be available in your templates. For example, if you visited /things/foo:

{{ thing }}

foo

Layout

When using Route::statamic(), Statamic will automatically inject the selected view into the default layout. You can customize which layout is used by adding a layout to the route data.

Route::statamic('uri', 'view', ['layout' => 'custom']);

Content Type Headers

You can control the content type headers by setting 'content_type' => '{content_type}'. To make your life easier we also support a few shorthand syntaxes for the most common content types. Nobody wants to memorize this stuff, ourselves included.

Dynamic Closure Based Routes

If needed, you can define more dynamic view or data logic by passing a closure.

For example, you might want to dynamically return a view based on dynamic segments in your URI. You can do this by passing a closure into the second argument:

Route::statamic('/{component}/{mode}', function ($component, $mode) {
    return view($component, ['mode' => $mode]);
});

By returning view() from a closure, Statamic will still apply all the "magic" like middleware, layout, globals, system variables, etc.

Note: If you don't return view(), middleware will still get applied, but layout, globals, system variables, etc. will not be. For example, returning an array would output JSON, just like it would with Route::get() in Laravel, but with Statamic's middlware stack applied.

Dynamic Route Data

Or, maybe you just want to dynamically compose data that's passed into a static view. You can do this by passing a closure into the third data argument:

Route::statamic('stats/{category}', 'statistics.show', function ($category) {
    return ['stats' => Stats::gatherDataExpensively($category)];
});

Note: Passing closures into both the second and the third parameter are not supported. If you need to dynamically handle both your view and your data, pass a closure into the second argmuent as detailed above.

Dependency Injection

You may also type-hint dependencies in your closure based routes, just as you can with Laravel:

use Illuminate\Http\Request;
 
Route::statamic('stats', 'statistics.show', function (Request $request) {
    return ['stats' => Stats::gatherDataExpensively($request->category)];
});

Redirects

Creating redirects can be done in your routes/web.php using native Laravel Route methods:

Route::redirect('/here', '/there');
Route::redirect('/here', '/there', 301);
Route::permanentRedirect('/here', '/there');

More details on the Laravel docs.

Laravel Routes

You can also configure regular Laravel routes much like you would in a regular Laravel application in routes/web.php. You can use closures, point to a controller, and so on. This is standard Laravel stuff and the standard Laravel docs apply.

Route::get('/thingy', function () {
    // ...
})->middleware(\Statamic\StaticCaching\Middleware\Cache::class);

Error Pages

Whenever an error is encountered, a view will be rendered based on the status code. It will look for the view in resources/views/errors/{status_code}.antlers.html.

You can use a custom layout for errors by creating a resources/views/errors/layout.antlers.html view.

Statamic will automatically render 404 pages for any unhandled routes.

Disable Statamic Routes

If you want to defer everything to explicit Laravel routes (perhaps you're using Statamic as a headless CMS or API), you can disable this behavior by setting it in config/statamic/routes.php.

// Lemme do it my way
'enabled' => false,