Routing and controllers

URL routing parses parameters from URL and passess execution to corresponding controller action. Routes are defined in Plugin/MyPluginName/routes.php file on each individual plugin. If route accepts paramters, they will be passed as arguments to controller action.

Basic route

// Open http://www.example.com/hello-world URL
$routes['hello-world'] = function() {
    return 'Hello world!';
};

Route parameter

// Open http://www.example.com/hello/John URL
$routes['hello/{name}'] = function($name) {
    return 'Hello ' . esc($name) . '!';
};

Optional route parameter

// Open http://www.example.com/hello 
// or 
// http://www.example.com/hello/John

$routes['hello{/name}'] = function($name = 'World') {
    return 'Hello ' . esc($name) . '!';
};

Two optional route parameters

// Open http://www.example.com/catallog
// or 
// http://www.example.com/catalog/xxx
// or
// http://www.example.com/catalog/xxx/yyy

$routes['catalog{/category,size}'] = function($category = 'Shirts', $size = 'm' ) {
    return 'Success';
};

Routing to controller'S method

// Open http://www.example.com/hello/John
// Plugin/MyPluginName/PublicController::hello($name) will handle that

$routes['hello{/name}'] = 'hello';

Routing to controller's method. Extended syntax

$routes['hello{/name}'] = array(
    'action' => 'hello', // You can pass a function instead of a string
);

or

$routes['hello{/name}'] = array(
    'plugin' => 'PluginName',
    'controller' => 'PublicController',
    'action' => 'create'
);

This will execute function create in Plugin/PluginName/PublicController.php class.

<?php

namespace Plugin\PluginName;

class PublicController
{
    public function create($name = null)
    {
        //do stuff
    }
}

Regular expression route constraints

// Open http://www.example.com/user/123

$routes['user/{id}'] = array(
    'where' => array(
        'id' => '\d+',
    ),
    'action' => function($id) {
        return 'User ' . $id;
    }
};

REQUEST METHOD ROUTE CONSTRAINTS

$routes['somepath'] = array(
  'action' => 'create',
  'method' => 'POST', // valid values 'GET', 'POST'
);

Generating route urls

$routes['user/{id}'] = array(
    'name' => 'userProfile',
    'action' => function($id) {
        return 'User url: ' . ipRouteUrl('userProfile', array('id' => $id));
    }
};

Multilingual URLs

ImpressPages takes care of multilingual routes. All routes will be available in all languages. E.g. if you have a route example.com/myroute, then that route will be automatically available in all languages example.com/xx/myroute.

Access information about current route anywhere in your code

All information about the current route can be accessed using function ipRoute(). It is not someth

ing you would use in a day today cases but sometimes very useful. E.g. you can use ipRoute()->plugin(), ipRoute()->action(), ipRoute()->variables() in your event handler.

Widgets and content management in routes

For widgets to work on routed pages, you have to set the page that's responsible to store that content. See example bellow:

$routes['test-url'] = array(
    'name' => 'MyPlugin_testRoute',
    'controller' => 'SiteController',
    'action' => 'doTheTest',
    'page' => ipContent()->getPage('page_alias_or_id')
);

Please keep in mind, that you have to create the page in Pages section of admin before using this route. You can point many routes to the same page. The result will be shared content between those routes. It doesn't matter where you place that page. You can create separate menu for routed pages or even hide them, but they have to actually exist in the database.

If you have many routes, you can create pages on the fly in routes.php file using ipContent() shorthand

Routing and controllers

Access information about current route anywhere in your code

Widgets and content management in routes

See also