Routing

1Basic routing

Temma's basic routing is intentionally very simple.

By default, URLs are mapped to the names of the controllers.

When logging into www.site.com/article/show/123/title
Temma executes the code Article::show(123, 'title')
and uses the template article/show.tpl

Routes are used to define "virtual controllers", serving as aliases for real controllers. This is particularly useful for allowing access to controllers under file names (such as the classic robots.txt and sitemap.xml).

This also makes it possible to have the same controller which responds on several different URLs, possibly doing different processing depending on the controller name requested.

Example:

<?php

return [
    'routes' => [
        'article'              => 'Posts',
        'sitemap.xml'          => '\App\Controllers\Sitemap',
        'sitemap.extended.xml' => '\App\Controllers\ExtendedSitemap',
    ]
];
  • Line 4: Definition of routes.
  • Line 5: Definition of the article virtual controller, which is an alias of the Posts controller.
    For example, a call to the URL http://www.site.com/article/list will call the list() method of the Posts object.
  • Line 6: We make sure that a call to the URL http://www.site.com/sitemap.xml results in the execution of the __invoke() method of the \App\Controllers\Sitemap controller.
  • Line 7: We make sure that a call to the URL http://www.site.com/sitemap.extended.xml results in the execution of the __invoke() method of the \App\Controllers\ExtendedSitemap controller.

2Advanced routing

The \Temma\Plugins\Router plugin allows you to activate more elaborate routing.

It needs to be enabled in the etc/temma.php file as a pre-plugin, and it uses extended configuration to define which controllers/actions to run based on the URL called.

Objects to be called as controllers must start with a backslash character (\), even if they are placed in the global namespace.
If a URL is not defined in the plugin configuration, Temma will use the values defined in the general configuration (notably the rootController and defaultController directives). The proxyController directive always takes precedence. 

<?php

return [
 'plugins' => [
     '_pre' => [
         '\Temma\Plugins\Router'
     ]
 ],
 'x-router' => [
     'GET:/articles'                                   => '\MyApp\Ctrl\Cms::list()',
     'GET:/articles/[sort:enum:alpha,date]'            => '\MyApp\Ctrl\Cms::list($sort)',
     'GET:/articles/[sort:enum:alpha,date]/[page:int]' => '\MyApp\Ctrl\Cms:list($sort, $page, "#f00"',
     '*:/article/[id:int]/[title:string]'              => '\MyApp\Ctrl\Cms::show($id, $title)',
 ]
];
  • Line 6: The \Temma\Plugins\Router object is defined as pre-plugin. It will thus take control and will be able to modify the plugins, the controller and the action that will be executed by the framework.
  • Line 9: Extended configuration specific to the advanced router.
  • Lines 10 and 11: We define that for the URL /articles called in GET, it is necessary to execute the list() method of the \MyApp\Ctrl\Cms object.
  • Lines 12 and 13: We define that a GET call to the URL /articles/ can be followed by a parameter (which we will call sort) which can only contain alpha, date or mark values. In this case, Temma will have to execute the list() method of the \MyApp\Ctrl\Cms object, giving it the sort value as a parameter.
  • Liens 14 and 15: A GET call to the /articles/ URL can also receive two parameters. The first is a sort type (as seen above), the second is a page number. The list() method is then called, with the sort type as first parameter, the page number as second parameter, and a fixed string as third parameter.
  • Lines 16 and 17: We define that for the URL /article/, followed by an integer parameter (which will be called id) and a text parameter (named title), Temma must execute the show() method of the \MyApp\Ctrl\Cmsobject, providing it with the id and title values retrieved from the URL as parameters. This route works regardless of the method used (GET, POST, PUT…).

In addition to defining the action to be performed for each route, it is also possible to define the pre-plugins and post-plugins to be called. 

<?php

return [
 'x-router' => [
     'GET:/articles' =>
         '\MyApp\Ctrl\Cms::list()',
     'GET:/articles/[sort:enum:alpha,date,mark]' =>
         '\MyApp\Ctrl\Cms::list($sort)',
     '*:/article/[id:int]/[title:string]' =>
         '\MyApp\Ctrl\Cms::show($id, $title)',
     'POST:/article' =>
         '_pre'   => '\MyApp\Plugins\Auth',
         'action' => '\MyApp\Ctrl\Cms::create()',
         '_post'  =>[
             '\MyApp\Plugins\LogFlow',
             '\MyApp\Plugins\EmailToAdmin',
         ],
     ],
     'PUT:/article/[id:int]' => [
         '_pre' => [
             '\MyApp\Plugins\Auth',
             '\MyApp\Plugins\DataCheck',
         ],
         'action' => '\MyApp\Ctrl\Cms::update($id)',
         '_post'  => '\MyApp\Plugins\LogFlow',
     ]
 ]
]
  • Line 11: We define a route for the /article URL called in POST.
    • Line 12: A pre-plugin is called for this route.
    • Line 13: We specify the controller and the action associated to this route.
    • Line 14 to 17: We configure two post-plugins to run for this route. If there are several plugins, you have to create a list.
  • Line 19: We define a route for the /article/ URL, followed by an integer parameter (which we will call id), called with the PUT method.
    • Line 20 to 23: There are two pre-plugins for this route.
    • Line 24: We specify the controller and the action associated to this route.
    • Line 25: There is a post-plugin for this route.