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
[ 'components' => [ 'urlManager' => [ 'routeParam' => 'icecream' ] ] ]
Such fiddling is irrelevant in most cases, though, because we have two other properties,
enablePrettyUrlproperty effectively removes the
?r=part from the URLs acceptable by the application. What was accessible by
index.php?r=module/controller/actionwill 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.
showScriptNameproperty, 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
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.rulessetting of the Yii application configuration
- Custom rule classes referenced inside the same setting