Routes in Wayfinder

¶ How Wayfinder interprets URLs

Wayfinder takes the URL and routes it to interpret your code. While custom routes take priority if defined, it will assume that this is the format is being used: yourhost.com/Controller/method/parameters.

¶ The default route

There is one exception, which is the root of your domain or project at /. You have to specify what it should point to in the /app/config/routes.php file. Here's the default configuration.

$_routes = [
    '/' => [
        'controller' => 'documentation',
        'method' => 'home'
    ]
}

<?php
$wf = new Documentation;
$wf->home();

This URL is a custom route. Out of the box, it points to the Documentation Class and calls the home() method. If no method is specified, Wayfinder assumes you want to use the index() method in your Class.

¶ Class only

You can access your Class and the default index() method by passing just the Class' name through the URL.

<?php
    $wf = new User;
    $wf->index();

¶ Class and method

If you want to call a specific method, just append that to the URL.

<?php
    $wf = new User;
    $wf->profile();

¶ Class, method and parameters

For parameters, you can append those too, separated by slashes:

<?php
    $wf = new User;
    $wf->profile('cafu');

cafu would be the paramater passed to your method. In the following example, you would get two variables, one with the value cafu and another with the value achievements:

<?php
    $wf = new User;
    $wf->profile('cafu', 'achievements');

¶ Custom routes

Taking advantage of the routing mechanism helps to keep your URLs clean. One example of this is where you don't want to reveal the Class or method name.

¶ Simple route

This can be routed directly to a specific Class, which will use the index() method by default.

$_route = [
    '/foo' => [
        'controller' => 'Bar'
    ]
];

<?php
    $wf = new Bar;
    $wf->index();

¶ Class and method routes

This can be routed directly to a specific Class and method. In this case, it will call $bar->myFunc().

$_route = [
    '/foo' => [
        'controller' => 'Bar',
        'method' => 'myFunc'
    ]
];

<?php
    $wf = new Bar;
    $wf->myFunc();

¶ More complex route

You can either use routing in Wayfinder to take complex URLs and simplify the logic or you can use it to take a simple URL and call something more complex behind the scenes. Let's look at what this 'complex' URL could be doing behind the scenes.

$_route = [
    '/foo/bar/bar/foo' => [
        'controller' => 'Bar',
        'method' => 'myFunc'
    ]
];

<?php
    $wf = new Bar;
    $wf->myFunc();

¶ Advanced custom routes

All of the different types of routes can do more than just call the right Class and method. You can predefine parameters or pass them in through the URL. In fact, you can do both at the same time.

¶ Passing parameters to custom routes

Just like the default Class, method, param routes, you can also pass parameters to your route as part of the URL for custom routes too.

$_route = [
    '/mycustomroute' => [
        'controller' => 'Bar',
        'method' => 'myFunc'
    ]
];

<?php
    $wf = new Bar;
    $wf->myFunc('myparam');

In the example above, the route would call the myFunc() method from the Bar Class while passing myparam as a parameter.

¶ Routes with predefined parameters

You can predefine parameters as part of your route.

It appears the route above would only call the Class and method, but in fact it's being routed to call them and to pass two predefined parameters.

$_route = [
    '/mycustomroute' => [
        'controller' => 'Bar',
        'method' => 'myFunc',
        'params' => [
            'parameter 1',
            'parameter 2'
        ]
    ]
];

<?php
    $wf = new Bar;
    $wf->myFunc('parameter 1', 'parameter 2');

¶ Combining parameters

Taking the two previous examples, you can bring them together so that you can pass predefined parameters and accept parameters passed through the URL.

You get access to the predefined parameters first, followed by the parameters passed through the URL.

array(4) {
    [0]=>
    string(11) "parameter 1"
    [1]=>
    string(11) "parameter 2"
    [2]=>
    string(12) "myfirstparam"
    [3]=>
    string(13) "mysecondparam"
}

<?php
    $wf = new Bar;
    $wf->myFunc('parameter 1', 'parameter 2', 'myfirstparam', 'mysecondparam');

¶ Numbered methods in routes

While the controller has to be defined when matching route is found, you can optionally set the method param to reference the position in the URL to use instead.

$_route = [
    '/mycustomroute' => [
        'controller' => 'Bar',
        'method' => 3
    ]
];

The above configuration would pick the third item in the URL that follows the matching route. The URL below would call a Class called Bar and a method called thirdparam. The method name is dropped from the URL and everything else is treated as a parameter.

This is an extreme example of how you can make routes work for your app, but it becomes useful when you want a route to map to a Class and want to call it's methods without having to define a route for each of them.

¶ Catch all routes

Wayfinder can optionally map the first param as a user generated path (think /username) when no route or controller matches. You need to change the __CATCH_FIRST_PARAM setting in the conf.php file to true.

If your path was /username, this can be interpreted as /defaultRouteController/defaultRouteMethod/username. As with all custom routes, you can predefine paramters in routes.php and you can pass additional parameters in the URL.

¶ Things to be aware of

In Wayfinder, prefixing a method with an underscore indicates that it is private and available only to the Class they are defined in.

Wayfinder does what it can to find a matching route. Once a matching route is found that provides a Class and a method, any additional characters are treated as parameters.

¶ Duplicate content

Adding more parameters to a URL can create duplicate content if not handled correctly.

Either this can be dealt with in the controller's logic or your markup can use the rel="canonical" attribute to help search engines find the right content.

¶ Query strings

Query strings can be used for things like cache breaking if required (for things like CDNs), but they are ignored by Wayfinder's internal routing.

¶ Error messages

If a matching Class, method or route can't be found, a 404 page will be returned. These pages use the default layout and styling as the docs pages but you can change this in the _displayError method found in the app/controllers/Error.php file.