Routing

Introduction

The WordPress Template Hierarchy is not the most intuitive thing. Because of that Assely routing flattens this hierarchy and immediately fallbacks to the index.php, where the router is executing.

Getting started

All application routes should be defined inside app\Http\routes.php file. This file is included on application bootstrap by the App\Providers\HttpServiceProvider class.

Basics of Routing

Adding routes is pretty straightforward, just give URL to which route has to answer.

Route::get('/', $callback);

Route::get('movie', $callback);

HTTP Methods

You can register routes to respond for specified or multiple HTTP methods.

Route::get($condition, $callback);
Route::post($condition, $callback);
Route::put($condition, $callback);
Route::delete($condition, $callback);

Route::match(['get', 'post'], $condition, $callback);
Route::any($condition, $callback);

Route Parameters

WordPress uses specific names for particular properties. For example, name for post slug or paged for current pagination number. You have to use that names as your route parameters.

Route::get('movie/{name}', function($name) {
    $movie = Post::type('movie')->find($name);
});

Route::get('genre/{term}', function($term) {
    $term = Term::type('genre')->find($name);
});

As you can see, the parameter values are passed into your route's callback when it is resolved. You can use them to do further queries.

In the following part of this documentation, you will find concrete examples how to correctly name your routes. Let's move on!

Route Conditions

Routes can be additional guarded with conditions. Conditioned routes will be resolved only when all its conditions meet. That way you can easily create routes for specific posts, pages etc.

To set conditions on selected route, simply call where method with an array of conditions as the parameter.

Route::get('{name}', function($name) {
    //
})->where([
    'post' => 'hello-world'
]);

The route above will be only resolved on a post with hello-world slug. Take a note, you can pass multiple condition values in array 'post' => [2, 'sample-post', 'Hello World!']. It can be id, slug or even title.

Route::get('{name}', function($name) {
    //
})->where([
    'post' => [2, 'sample-post', 'Hello World!']
]);

Creating Standard Routes

As was said before, you have to use specific names for route properties. Router requires these names to property resolve its values from global WP_Query.

This section contains a list of all available routes, which comes with WordPress and don't require to register any of custom rewrite rules.

Routing Homepage

Routing to the homepage is easy as pie:

Route::get('/', function() {
    //
});

Your website uses a static page and you want an explicit route? Narrow route from above with front condition.

Route::get('/', function() {
    //
})->where([
    'front' => true
]);

Routing Posttypes

Single Post

The {name} parameter allows you to route to the view of the single post.

Route::get('{name}', function($name) {
    //
});

Single Page

Use {pagename} to target single pages.

Route::get('{pagename}', function($pagename) {
    //
});

If you would like to target also children pages, add the second route with simple regular expression before parameter.

Route::get('(.+)/{pagename}', function($pagename) {
    //
});

Want to target all parent pages and children pages with one route? Just modify a little regular expression from above.

Route::get('(.+\/)?{pagename}', function($pagename) {
    //
});

Now, everything before {pagename} is optional, so both pages and children pages will be matched.

Single custom type Post

Route::get('movie/{name}', function($name) {
    //
});

Paginated list of Posts

Route::get('page/{paged}', function($paged) {
    //
});

Paginated list of Custom Type Posts

Route::get('movie/page/{paged}', function($name, $paged) {
    //
});

Routing Taxonomies

Single Category

Route::get('category/{category_name}', function($category_name) {
    //
});

Single Tag

Route::get('tag/{tag}', function($tag) {
    //
});

Single Term

Route::get('genre/{term}', function($term) {
    //
});

Paginated Term

Route::get('genre/{term}/page/{paged}', function($term, $paged) {
    //
});

Routing Search Results

Route::get('search/{s}', function($s) {
    //
});

Routing Author Page

Single Author

Route::get('author/{author_name}', function($author_name) {
    //
});

Paginated Author's Posts

Route::get('author/{author_name}/page/{paged}', function($author_name, $paged) {
    //
});

Creating Custom Routes

Creating custom routes takes place in two minor steps. First, registering new rewrite rule and then adding route which targets previously created path.

1. Register new Custom Rewrite Rule

Register new rewrite rule with desired URI in app/Http/rewrites.php file.

// @ /app/Http/rewrites.php

Rewrite::rule('favourite/movies/{from}/{to}')->where([
    'from' => '([0-9]{4})',
    'to' => '([0-9]{4})'
]);

2. Route Custom Rewrite Rules

Add new route which targets URI of the rewrite rule created in previous step.

// @ /app/Http/routes.php

Route::get('favourite/movies/{from}/{to}', function ($from, $to) {
   return "{$form}-{$to}"
});