Navigation
Overview
Navigation builds URLs from route names. A link in a view refers to front::post_show, not to /post/42. When a route path changes, every link follows, because only the route definition knows the pattern. The same system also builds redirects and answers questions about the active route.
The navigation system has four parts:
Navigator: the service that builds URLs and redirects, and reads the matched route.RouteUri: the objectto()returns. It is a URI you can still change. It becomes a string only when you print it.NavOptions: the settings for one call, such as the URL mode or whether a missing route is muted.- Navigation events: hooks that run while a URL is built.
Route names and patterns are defined in the Routing page.
Getting the Navigator
Get the Navigator from the application container. Controllers can use NavigableTrait, which injects it as $this->nav. Views receive it as the $nav variable.
<?php
use Windwalker\Core\Router\Navigator;
$nav = $app->retrieve(Navigator::class);Showcase: Post Links and Redirects
This example extends the post routes from the Routing page. It adds a list route and a store route, and both use names instead of paths.
Add these routes to routes/front/post.php:
<?php
declare(strict_types=1);
namespace App\Routes;
use App\Module\Front\Post\PostController;
use Windwalker\Core\Router\RouteCreator;
/** @var RouteCreator $router */
$router->get('post_index', '/posts')
->handler(PostController::class, 'index');
$router->get('post_show', '/post/{id:\d+}')
->handler(PostController::class, 'show');
$router->save('post_store', '/post')
->handler(PostController::class, 'store');Add these methods to PostController, and add use NavigableTrait; to the class body:
<?php
declare(strict_types=1);
namespace App\Module\Front\Post;
use Windwalker\Core\Router\NavigableTrait;
use Windwalker\Core\Router\RouteUri;
use Windwalker\Http\Response\JsonResponse;
class PostController
{
use NavigableTrait;
public function index(): JsonResponse
{
// Load the IDs from the database in a real app.
$ids = [1, 2, 3];
$links = [];
foreach ($ids as $id) {
$links[] = (string) $this->nav->to(
'front::post_show',
['id' => $id],
);
}
return new JsonResponse(['links' => $links]);
}
public function store(): RouteUri
{
// Save the post here, then redirect to its page.
$id = 4;
return $this->nav->to('front::post_show', ['id' => $id]);
}
}The store() method returns a RouteUri. Windwalker turns it into a 303 redirect, so the browser lands on the new post page. The list page prints the URLs as strings.
GET /posts 200 links: /post/1, /post/2, /post/3
POST /post 303 Location: /post/4In a view, the same call builds a link:
<a href="{{ $nav->to('front::post_show', ['id' => $post->id]) }}">
{{ $post->title }}
</a>Building URLs with to()
to() takes a route name, the route variables and query values, and an optional NavOptions. Values that match a placeholder fill the path. The remaining values become the query string:
<?php
/** @var Navigator $nav */
$nav->to('front::post_show', ['id' => 42]);
// /post/42
$nav->to('front::post_show', ['id' => 42, 'tab' => 'comments']);
// /post/42?tab=commentsThe path starts at the app root. The examples above assume the app is installed at the root of the domain.
Route Names
Route names have the form namespace::name. Inside a route of a group, you can use the short name. Navigator looks in the matched route's namespace first:
<?php
/** @var Navigator $nav */
// Matched route: front::post_index
$nav->to('post_show', ['id' => 42]);
// Resolves to front::post_showUse has() to check a name before you build a URL:
<?php
/** @var Navigator $nav */
if ($nav->has('front::post_show')) {
// The route exists.
}Outside a view, to() throws RouteNotFoundException when the name is unknown. Views mute this error by default. See Muted Links and Debug Mode.
Chaining Methods on RouteUri
RouteUri has methods that set one variable each. Each method returns a new object, so the chain can be reused safely:
<?php
/** @var Navigator $nav */
$uri = $nav->to('front::post_show', ['id' => 42])
->page(2)
->var('lang', 'en');
// /post/42?page=2&lang=enThe main methods are:
var(): sets any variable. Enum values and UUIDs are converted to scalars.id(),page(),layout(),task(),alias(): shortcuts forvar()with a fixed name.withReturn(): adds the current URL, encoded, to areturnvariable. Use it for login links.full(),path(),raw(): change the URL mode for this link. See Navigation Options.mute(): mutes a missing route for this link only.allowQuery(): filters the query values. See Current Page and Active State.withStatus(): sets the status code used when the URI becomes a redirect.withMessage(): adds a flash message. It needswindwalker/session.
A login link can return to the current page after sign-in:
<a href="{{ $nav->to('login')->withReturn() }}">Log in</a>INFO
RouteUri::alias() sets the alias query variable. It does not create a route alias. Route aliases are set with alias() on the Route in the Routing page.
Using a RouteUri
A RouteUri can be used in four ways:
- Printed as a string, for links and templates.
- Returned from a controller, which sends a redirect.
- Converted to a response with
toResponse(). - Passed to
redirect(), which is described below.
<?php
use Windwalker\Core\Router\RouteUri;
/** @var RouteUri $uri */
$response = $uri->toResponse(302);Custom URLs with createRouteUri()
Use createRouteUri() when the target is not a named route, such as a file or an external API. It takes a URL and a query array:
<?php
/** @var Navigator $nav */
$url = $nav->createRouteUri('/api/search', ['q' => 'php 8']);
echo $url;
// /api/search?q=php+8Pass a closure to compute the URL when it is printed. The closure returns [$url, $query], the same shape as the internal route handler:
<?php
/** @var Navigator $nav */
$uri = $nav->createRouteUri(
fn (array $vars) => ['/post/' . $vars['slug'], []],
['slug' => 'hello-world'],
);
echo $uri;
// /post/hello-worldUse named routes for pages in your app. A named route updates when its pattern changes, and a hard-coded path does not.
Redirects and Outside URLs
Navigator has several redirect methods. Each returns a ResponseInterface, so a controller can return it:
redirect($uri, $code = 303): redirects to a local URL.redirectOutside($uri, $code = 303): redirects to any URL.redirectTo($route, $query, $code = 303): redirects to a named route.redirectSelf($code = 303): redirects to the current route.redirectInstant($uri, $code = 303): sends the response and ends the request at once.back(): returns aRouteUrito the referrer.
<?php
use Windwalker\Core\Router\Navigator;
/** @var Navigator $nav */
return $nav->redirectTo('front::post_show', ['id' => 42]);redirect() accepts only local URLs. A URL is local when it starts with / or with the app root:
<?php
/** @var Navigator $nav */
$nav->redirect('/post/42');
// Location: /post/42
$nav->redirect('https://other.example/');
// Location: https://example.com/ (the app root)WARNING
redirect() replaces a non-local URL with the app root, and it does not report an error. A link to another site silently sends the user to your home page. Use redirectOutside() for an outside URL.
redirectOutside() turns off the check for one redirect:
<?php
/** @var Navigator $nav */
return $nav->redirectOutside('https://payment.example/checkout');WARNING
Only pass trusted URLs to redirectOutside(). Never pass a value from the request, such as a return parameter, because it lets an attacker send users to any site.
back() uses the Referer header only when it is a local URL. Otherwise it returns the app root. The header comes from the client, so do not use it for security decisions.
Current Page and Active State
self() builds a URL for the matched route. It keeps the route variables and drops the query string, unless you allow some query values:
<?php
use Windwalker\Core\Router\NavOptions;
/** @var Navigator $nav */
// Current route with the same ID.
$nav->self();
// Current route, page 2.
$nav->self()->page(2);
// Current route, keep only the page query value.
$nav->self(new NavOptions(allowQuery: ['page']));selfNoQuery() is the same as self() with withoutQuery set. Use redirectSelf() to send the user back to the current route.
Check the active route in a menu:
<a class="nav-link {{ $nav->isActive('front::home') ? 'active' : '' }}"
href="{{ $nav->to('front::home') }}">Home</a>isActive() accepts several forms:
'front::home': an exact route name.'post_show': a short name, without the namespace.'post_*': a wildcard, matched against the name or the route path.['home', 'post_show']: any of the values in the list.
inGroup('admin') checks the group of the matched route. Set a menu key on a route with extra('menu', ...), and isActive() matches it too.
Navigation Options
NavOptions changes one link or redirect. The mode decides the shape of the URL:
NavMode::PATH(default): a path from the app root, such as/post/42.NavMode::FULL: includes the scheme and host, such ashttps://example.com/post/42.NavMode::RAW: returns the path without resolving the app root.
<?php
use Windwalker\Core\Router\NavMode;
use Windwalker\Core\Router\NavOptions;
/** @var Navigator $nav */
$nav->to('front::post_show', ['id' => 42], new NavOptions(
mode: NavMode::FULL,
));
// https://example.com/post/42INFO
RAW output has no leading slash, such as post/42. Use it only when you build the URL in your own code.
The other options are:
mute: a missing route returns#instead of throwing.debugAlert: withmute, a missing route returns a JavaScript alert.allowOutside: allows an outside URL in a redirect.instant: sends the redirect response and ends the request at once.withoutVars:self()omits the route variables.withoutQuery:self()omits the query values.ignoreEvents: skips the navigation events.allowQuery: keeps all query values (true), drops all (false), or keeps the listed names (array).base: a prefix added byabsolute().extra: free-form data for event listeners. See Events.
Options passed to a call override the Navigator's defaults for that call. To change the defaults for every link in a scope, use withOptions(). It returns a copy of the Navigator:
<?php
use Windwalker\Core\Router\NavOptions;
use Windwalker\Core\Router\Navigator;
/** @var Navigator $nav */
$muted = $nav->withOptions(new NavOptions(mute: true));
echo $muted->to('front::missing');
// #INFO
The integer flags in NavConstantInterface, such as TYPE_FULL, still work but are deprecated. Use NavOptions in new code.
Muted Links and Debug Mode
The $nav variable in views is a Navigator with mute enabled. A link to an unknown route renders as #, so one bad name does not break the page. When the app runs in debug mode, debugAlert is also enabled, and the link shows a message:
<a href="{{ $nav->to('front::missing') }}">Missing</a>Production:
<a href="#">Missing</a>
Debug:
<a href="javascript: alert('Route: front::missing not found.');">WARNING
A mistyped route name in a view renders # without any error in production. Check the names in debug mode, or call has() in tests.
Use mute() on one link when a route can be missing on purpose:
<?php
/** @var Navigator $nav */
$uri = $nav->to('front::home')->mute();Navigation Events
Navigation emits three events while it builds a URL:
PrepareRouteBuildEvent: before the route lookup. You can change the route name, the query, and the options.BeforeRouteBuildEvent: after the route is found. You can change the query and the options.AfterRouteBuildEvent: after the URL is built. You can change the URL and the query.
They live in the Windwalker\Core\Router\Event namespace. All three are skipped when ignoreEvents is set.
The extra option carries your own data into the events. Core does not read it. This example adds a utm_source query value to links built with extra: ['source' => ...]:
<?php
declare(strict_types=1);
namespace App\Listener;
use Windwalker\Core\Router\Event\AfterRouteBuildEvent;
use Windwalker\Event\Attributes\EventSubscriber;
use Windwalker\Event\Attributes\ListenTo;
#[EventSubscriber]
class NavTrackingSubscriber
{
#[ListenTo(AfterRouteBuildEvent::class)]
public function addSource(AfterRouteBuildEvent $event): void
{
$source = $event->options->extra['source'] ?? null;
if ($source !== null) {
$event->query['utm_source'] = $source;
}
}
}Attach the subscriber to a route, as shown in the Request Lifecycle page. Then build the link with the option:
<?php
use App\Listener\NavTrackingSubscriber;
use Windwalker\Core\Router\NavOptions;
/** @var RouteCreator $router */
$router->get('post_show', '/post/{id}')
->handler(PostController::class, 'show')
->subscribe(NavTrackingSubscriber::class);
// In a view:
// $nav->to('front::post_show', ['id' => 42],
// new NavOptions(extra: ['source' => 'sidebar']));
// /post/42?utm_source=sidebarTIP
Use the Prepare event to map old route names to new ones, so existing templates keep working after a rename.