In this Tutorial, we will explore how the Yii 2 routing system works, that is, how the framework responds to different URL routes requested from it.

We’ll start with the description of the process that the Yii application performs to determine the controller action to execute in response to client requests. Then, we will implement a small feature, which will demonstrate how we can control our routes using just the application configuration.

And lastly, we’ll implement one particularly interesting feature that will require our own custom rule class and show the considerations while doing so.

Yii 2 routing 102

As we already know, everything in Yii 2 starts with the entry-point script, which in our example application is web/index.php. This script should be the only PHP script in the directory published by the web server.

As everything comes to this script, , Getting Started, discussing the installation of the framework) look as follows:


So, any request is being processed by accessing the index.php file, and passing it the further route inside the application as the GET parameter named r. This name is configurable in the \yii\web\UrlManager::$routeParam property, so the following configuration snippet will set the name of the route parameter to icecream:

    'components' => [
        'urlManager' => [
            'routeParam' => 'icecream'

Such fiddling is irrelevant in most cases, though, because we have two other properties, UrlManager: enablePrettyUrl and showScriptName

  • The enablePrettyUrl property effectively removes the ?r= part from the URLs acceptable by the application. What was accessible by index.php?r=module/controller/action will be accessible by just index.php/module/controller/action. But in addition to that, it enables the support to define custom rules of parsing and generating routes. Basically, it completely changes the way the Yii application handles requests.
  • The showScriptName property, when set to false, will prohibit the URL manager from adding the script name to the URLs it generates. The actual name of the entry-point script is irrelevant; it’s inferred from the current $_SERVER settings automatically.

Practically speaking, you will almost always use the following combinations of the parameters:

        'urlManager' => [
            'enablePrettyUrl' => true,
            'showScriptName' => false,

The only downside of this approach is that you have to configure your web server to send all requests to your entry point, like the following Apache rewrite directive:

RewriteRule . index.php

Note that the enablePrettyUrl modes are incompatible. If you are using pretty URLs, you cannot request your application using the ?r=:route notation and vice versa.

Getting the actual route from the request string is just the first step in the Yii 2 routing system.



This string allows the framework to guess which controller action it should execute. If there is no moduleid, then the application itself is considered as a target module.

When we have enablePrettyUrl set to true, though, we are able to define special URL rules to parse client requests to the application. In fact, we are able to use arbitrary strings as routes in our system.


There are three ways to control routes, which are as follows:

  • Names of modules, controllers, and actions
  • Custom rule definitions inside the components.urlManager.rules setting of the Yii application configuration
  • Custom rule classes referenced inside the same setting