Routing¶

The Router¶

The request builder asks the router for the correct package, controller and action. For this it passes the current request path to the routers match() method. The router then iterates through all configured routes and invokes their matches() method. The first route that matches, determines which action will be called with what parameters.

The same works for the opposite direction: If a link is generated the router calls the resolve() method of all routes until one route can return the correct URI for the specified arguments.

Routes¶

A route describes the way from your browser to the controller - and back.

With the uriPattern you can define how a route is represented in the browser’s address bar. By setting defaults you can specify package, controller and action that should apply when a request matches the route. Besides you can set arbitrary default values that will be available in your controller. They are called defaults because you can overwrite them by so called dynamic route parts.

But let’s start with an easy example:

Example: Simple route - Routes.yaml

-
  name: 'Homepage'
  uriPattern: ''
  defaults:
    '@package': 'My.Demo'

If you insert these lines at the beginning of the file Configurations/Routes.yaml, the indexAction of the StandardController in your My.Demo package will be called when you open up the homepage of your FLOW3 installation (http://localhost/).

URI patterns¶

The URI pattern defines the appearance of the URI. In a simple setup the pattern only consists of static route parts and is equal to the actual URI (without protocol and host).

In order to reduce the amount of routes that have to be created, you are allowed to insert markers, so called dynamic route parts, that will be replaced by the Routing Framework. You can even mark route parts optional.

But first things first.

-
  name: 'Static demo route'
  uriPattern: 'my/demo'
  defaults:
    '@package':    'My.Demo'
    '@controller': 'Product'
    '@action':     'list'

-
  name: 'Dynamic demo route'
  uriPattern: 'my/demo/{@action}'
  defaults:
    '@package':    'My.Demo'
    '@controller': 'Product'

-
  name: 'Dynamic demo route with parameter'
  uriPattern: 'products/list/{sortOrder}.{@format}'
  defaults:
    '@package':    'My.Demo'
    '@controller': 'Product'
    '@action':     'list'

-
  name: 'Single product route'
  uriPattern: 'products/{product}'
  defaults:
    '@package':    'My.Demo'
    '@controller': 'Product'
    '@action':     'show'

-
  name: 'Single product route'
  uriPattern: 'products/{product}'
  defaults:
    '@package':     'My.Demo'
    '@controller':  'Product'
    '@action':      'show'
  routeParts:
    product:
      objectType: 'My\Demo\Domain\Model\Product'

-
  name: 'Single product route'
  uriPattern: 'products/{product}'
  defaults:
    '@package':     'My.Demo'
    '@controller':  'Product'
    '@action':      'show'
  routeParts:
    product:
      objectType: 'My\Demo\Domain\Model\Product'
      uriPattern: '{category.title}/{name}'

Route Part Handlers¶

Route part handlers are classes that implement TYPO3\FLOW3\MVC\Web\Routing\DynamicRoutePartInterface. But for most cases it will be sufficient to extend TYPO3\FLOW3\MVC\Web\Routing\DynamicRoutePart and overwrite the methods matchValue and resolveValue.

Let’s have a look at a (very simple) route part handler that allows you to match values against configurable regular expressions:

Example: RegexRoutePartHandler.php

class RegexRoutePartHandler extends \TYPO3\FLOW3\MVC\Web\Routing\DynamicRoutePart {

        /**
         * Checks whether the current URI section matches the configured RegEx pattern.
         *
         * @param string $requestPath value to match, the string to be checked
         * @return boolean TRUE if value could be matched successfully, otherwise FALSE.
         */
        protected function matchValue($requestPath) {
                if (!preg_match($this->options['pattern'], $requestPath, $matches)) {
                        return FALSE;
                }
                $this->value = array_shift($matches);
                return TRUE;
        }

        /**
         * Checks whether the route part matches the configured RegEx pattern.
         *
         * @param string $value The route part (must be a string)
         * @return boolean TRUE if value could be resolved successfully, otherwise FALSE.
         */
        protected function resolveValue($value) {
                if (!is_string($value) || !preg_match($this->options['pattern'], $value, $matches)) {
                        return FALSE;
                }
                $this->value = array_shift($matches);
                return TRUE;
        }

}

The corresponding route might look like this:

Example: Route with route part handlers Configuration/Routes.yaml

-
  name: 'RegEx route - only matches index & list actions'
  uriPattern: 'blogs/{blog}/{@action}'
  defaults:
    '@package':    'My.Blog'
    '@controller': 'Blog'
  routeParts:
    '@action':
      handler:   'My\Blog\RoutePartHandlers\RegexRoutePartHandler'
      options:
        pattern: '/index|list/'

The method matchValue() is called when translating from an URL to a request argument, and the method resolveValue() needs to return an URL segment when being passed a value.

Optional route parts¶

By putting one or more route parts in round brackets you mark them optional. The following route matches http://localhost/my/demo and http://localhost/my/demo/list.html.

Example: Route with optional route parts - Configuration/Routes.yaml

-
  name: 'Dynamic demo route'
  uriPattern: 'my/demo(/{@action}.html)'
  defaults:
    '@package':    'My.Demo'
    '@controller': 'Product'
    '@action':     'list'

Case Sensitivity¶

By Default URIs are lower-cased. The following example with a username of “Kasper” will result in http://localhost/users/kasper

Example: Route with default case handling

-
  uriPattern: 'Users/{username}'
  defaults:
    '@package':    'My.Demo'
    '@controller': 'Product'
    '@action':     'show'

You can change this behavior for routes and/or dynamic route parts:

Example: Route with customised case handling

-
  uriPattern: 'Users/{username}'
  defaults:
    '@package':    'My.Demo'
    '@controller': 'Product'
    '@action':     'show'
  toLowerCase: false
  routeParts:
    username:
      toLowerCase: true

The option toLowerCase will change the default behavior for this route and reset it for the username route part. Given the same username of “Kasper” the resulting URI will now be http://localhost/Users/kasper (note the lower case “k” in “kasper”).

Matching of incoming URIs to static route parts is always done case sensitive. So “users/kasper” won’t match. For dynamic route parts the case is usually not defined. If you want to handle data coming in through dynamic route parts case-sensitive, you need to handle that in your own code.

Subroutes¶

For security reasons and to avoid confusion, only routes configured in your global configuration folder are active. But FLOW3 supports what we call SubRoutes enabling you to provide custom routes with your package and reference them in the global routing setup.

Imagine following routes in the Routes.yaml file inside your demo package:

Example: Demo Subroutes - My.Demo/Configuration/Routes.yaml

-
  name: 'Product routes'
  uriPattern: 'products/{@action}'
  defaults:
    '@controller': 'Product'

-
  name: 'Standard routes'
  uriPattern: '{@action}'
  defaults:
    '@controller': 'Standard'

And in your global Routes.yaml:

Example: Referencing SubRoutes - Configuration/Routes.yaml

-
  name: 'Demo SubRoutes'
  uriPattern: 'demo/<DemoSubroutes>(.{@format})'
  defaults:
    '@package': 'My.Demo'
    '@format':  'html'
  subRoutes:
    DemoSubroutes:
      package: 'My.Demo'

As you can see, you can reference SubRoutes by putting parts of the URI pattern in angle brackets (like <subRoutes>). With the subRoutes setting you specify where to load the SubRoutes from.

Internally the ConfigurationManager merges together the main route with its SubRoutes, resulting in the following routing configuration:

Example: Merged routing configuration

-
  name: 'Demo SubRoutes :: Product routes'
  uriPattern: 'demo/products/{@action}.{@format}'
  defaults:
    '@package':    'My.Demo'
    '@format':     'html'
    '@controller': 'Product'

-
  name: 'Demo SubRoutes :: Standard routes'
  uriPattern: 'demo/{@action}.{@format}'
  defaults:
    '@package':    'My.Demo'
    '@format':     'html'
    '@controller': 'Standard'

You can even reference multiple SubRoutes from one route - that will create one route for all possible combinations.

$ ./flow3 routing:list

Currently registered routes:
typo3/login(/{@action}.{@format})         TYPO3 :: Authentication
typo3/logout                              TYPO3 :: Logout
typo3/setup(/{@action})                   TYPO3 :: Setup
typo3                                     TYPO3 :: Backend Overview
typo3/content/{@action}                   TYPO3 :: Backend - Content Module
{node}.html/{type}                        TYPO3 :: Frontend content with format and type
{node}.html                               TYPO3 :: Frontend content with (HTML) format
({node})                                  TYPO3 :: Frontend content without a specified format
                                          TYPO3 :: Fallback rule – for when no site has been defined yet

Route Loading Order and the FLOW3 Application Context¶

• routes inside more specific contexts are loaded first, and after that, global ones
• so you can specify context-specific routes