Routing

Contents...

All HTTP request within the framework address space (i.e. URLs beginning with http://{DOMAIN_NAME}/{PATH_TO_FRAMEWORK}/*) are forwarded using mod_rewrite directives to the main front controller file index.php, which is located in the Webasyst root directory and performs initial user request routing.

The front controller analyzes the contents of the request URL and executes the corresponding application based on the retrieved URL parameters. Frontend routing is set up at two levels:

  1. System-wide level (required configuration level);
  2. Application-wide level (optional configuration level).

System-wide routing

System-wide routing distributes the entire frontend address space among installed applications. For instance, the routing rules can be set up so that requests which are sent to URLs beginning with http://{DOMAIN_NAME}/{PATH_TO_FRAMEWORK}/news/ are processed by the Blog application, and those beginning with http://{DOMAIN_NAME}/{PATH_TO_FRAMEWORK}/stickies/ are processed by Stickies app.

System-wide routing parameters are contained in file wa-config/routing.php. Example:

<?php

return array(
    'default' => array(
        'blog' => array(
            'url' => 'news/*',
            'app' => 'blog'
        ),
        'stickies' => array(
            'url' => 'stickies/*',
            'app' => 'stickies',
        ),
        'guestbook' => array(
            'url' => 'guestbook/*',
            'app' => 'guestbook',
            'module' => 'frontend'
        ),
    )
);

Configurable parameters are:

System-wide routing parameters are set during the initial framework setup; they are available for customization, do not depend on internal application logic, neither affect it in any way.

The system-level URL parsing stage determines the application and, optionally, the module+action pair of the application, which should process the request. For simple applications utilizing a single action, or when different actions are used for generation of several non-interlinked web pages, system-wide routing configuration may be sufficient. For more complex further analysis of the request URL is carried out according to the internal application routing rules.

Domain aliases

The framework provides a simple option to add domain names alias to create website mirrors. Aliases are added to the common routing configuration file wa-config/routing.php. For aliases, instead of arrays of routing parameters, the main domain name is specified whose routing parameters must be available in this file, they will be used for that domain's aliases:

<?php

return array(
    'myaliasdomain.com' => 'mydomain.com',
    'my-alias-domain.com' => 'mydomain.com',
    // for alias domains written in national alphabets (e.g., Russian) their Punycode versions must be specified as array keys, see http://en.wikipedia.org/wiki/Punycode
    'mydomain.com' => array(
        // ... here must be routing rules for main domain 'mydomain.com' similar to those shown in the previous example
    )
);

An alias utilizes routing rules of its main domain. If the contents of the alias website is identical to that of the main website, then it could have unpredictable results for the indexing by search engines. Be careful when creating aliases and consider the recommendations offered by search engines on the HTML contents and adding of links pointing from the main website to its aliases and vice versa; if an alias is simply a regional version of the main website, then these recommendations by Google on adding extra HTML markup for multilingual websites. If you are not sure whether it is really necessary and correct to create an alias, then you may consider adding a redirect (Redirect: 301 Moved Permanently),which you can set up in the “Structure” section of the Site app backend.

Application-level frontend request routing

The routing configuration within an application is optional and may be necessary, if the application is not limited to displaying only two or three different web pages but rather is used for generation of a large number of interlinked frontend pages.

Application-wide routing configuration rules are specified in file wa-apps/{APP_ID}/lib/config/routing.php. This file contains specific parameters of relationship between request URLs and the corresponding modules/actions.

For instance, routing configuration file for Blog application might have the following contents:

<?php

return array(
    'blog_tag' => array(
        'url' => 'tag/<tag>',
        'module' => 'post',
        'action' => 'tag'
    ),
    'blog_post' => array(
        'url' => 'post/<id:\d+>',
        'module' => 'post',
    ),
    'rss' => array(
        'url' => 'rss',
        'action' => 'rss'
    )
);

The value of parameter url in the above example is specified relative to the application's main frontend URL (for the above examples it would be an URL of the form http://{DOMAIN_NAME}/{PATH_TO_FRAMEWORK}/news/).

Parameters module and action specify the module and action, which should be executed to process requests at a specific URL. These two parameters are optional and, if either of them is not specified, the corresponding default module/action is called. The name of the default module/action is specified in system configuration file wa-config/routing.php (as explained above). If no default module name is specified in the system configuration file, then default module name frontend is used.

Application-wide routing is closely related to the internal application logic and is part of the application itself; it is, therefore, not configurable at the system routing level.

Examples of relationship between request URLs and module methods

Below are shown examples of the controller/action methods search algorithm operation, which are responsible for request processing (these examples correspond to the rules specified in the above configuration file example):

/news/tag/travel

  1. blogPostTagController->execute()
  2. blogPostTagAction->execute()
  3. blogPostActions->tagAction()

/news/post/45

  1. blogPostController->execute()
  2. blogPostAction->execute()
  3. blogPostActions->defautAction()

/news/rss

  1. blogFrontendRssController->execute()
  2. blogFrontendRssAction->execute()
  3. blogFrontendActions->rssAction()

The system searches a class and a method in the specified order and executes the first variant found. The rules used for determination of the class name corresponding to the requested module and action name are described in greater detail in section "Naming rules and recommendations".

Passing parameters in the request URL

Request routing rules allow passing various variables via the request  URL to a controller.

In the above configuration file example, several url fields contain structures in square brackets; e.g., 'tag/[:tag]'. After the column character they contain the name of the parameter to which the value retrieved from the request URL will be assigned.

Parameters are passed via environment variables and are accessible in the controller PHP code by means of system class method waRequest::param(...). For the above configuration file example, provided above, a request sent to a URL of the form .../blog/tag/cloud will execute action tag in module post and will pass parameter name tag and value cloud to the action:

// Request to .../blog/tag/cloud
$tag = waRequest::param('tag'); // will return string 'cloud'

Routing parameter name in the configuration file may be accompanied by an additional indicator of the variable type in the form of prefix i or s (integer number or string respectively). In the above examples such an indicator is specified for the blog_post parameter: 'post/[i:id]'.

// Request to .../blog/post/32
$id = waRequest::param('id'); // will return an integer: 32

// Request to .../blog/post/bla
$id = waRequest::param('id'); // will return 0

Read more about class waRequest in section "Environment variables".