How to set the default controller in yii2

How to set the default controller in yii2

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

How to set the default controller in yii2

When you deploy a Yii 2 application, the framework defaults to a routing behavior where you must explicitly specify the controller and action path, such as user/index. This is evident when accessing the root URL of your virtual server; it will return a 404 or display an error because no route matches an empty string. To make UserController with the index action load automatically at the domain root, you need to configure the application's default controller setting.

In Yii 2, this configuration resides in the config/main.php file. The framework looks for a property named defaultController within the main config array. By setting this property, you instruct the router to redirect any request to the specified controller if no other route matches.

Here is how you implement this:

return [
    'controller' => 'user', // Set this to the desired default controller name
    // ... other configuration
];

You can place this setting in either config/main.php or config/web.php, depending on your application structure. If using web.php, ensure the key is nested correctly under the main configuration array passed to Yii::createWebApplication(). The value should be the controller name without the "Controller" suffix, so if your class is named UserController, the string value should simply be 'user'.

Once configured, a request to http://basic.com will internally resolve to the UserController and its default action. By convention, Yii 2 assumes the default action is index if none is specified in the URL segment. Therefore, accessing http://basic.com/user or just http://basic.com will both trigger the same route after this configuration change.

Handling Multiple Controllers

Setting a global default controller is useful for single-page applications or sites with a specific landing page logic. However, it can introduce friction if you have other controllers that need their own unique root paths. For instance, if you also want http://basic.com/admin to load the AdminController, you cannot rely solely on a single global default.

In such scenarios, defining a global default is still valid for the main user area, but you must explicitly define routes for other areas in your config/web.php. You can use the rules array to map specific paths to their respective controllers:

'rules' => [
    '<c:(user|admin)>/<a:\w+>'=>'<c>/<a>', // Specific routes for user and admin
    '<anything:\w+>'=>'<controller>/<action>', // Catch-all for remaining requests
],

This approach allows you to keep defaultController set to 'user' for the base URL while ensuring that /admin is handled separately. If you do not define rules or a default controller, Yii 2 will attempt to match the path literally, resulting in a 404 error for the root URL.

Security Considerations

While setting a default controller simplifies navigation, it is important to ensure that the default action does not expose sensitive data prematurely. The index action in many controllers is designed to list items or show a dashboard. If your UserController::actionIndex() expects parameters that are missing when accessed via the root URL, you may encounter an error.

You should verify that your controller's index action handles the case where no explicit action parameter is provided gracefully. Additionally, ensure that the default controller does not bypass authentication checks if it is intended to be public. If your application requires login before viewing any user content, consider making the root URL redirect to the login page instead of loading the UserController directly.

Conclusion on Configuration

Configuring the default controller in Yii 2 is a straightforward process involving a single configuration entry. By setting the controller property in your main config file, you eliminate the need for users to type /user to access your primary landing page. This change aligns the URL structure with the actual application state without requiring complex routing rules, provided you do not have conflicting path requirements for other parts of your site.

Our network