How to Add a New Application in Yii2 Basic Template (Without Switching to the Advanced Template)

Yii2 offers two starter templates — basic and advanced. The advanced template supports frontend/backend apps out of the box. However, many developers start with the basic template for its simplicity. Over time, as the project grows, you may need to add separate apps like an admin panel, HR module, or reporting tool.

In such cases, you might consider migrating to the advanced template. But there's a more flexible and lightweight option: add a new application inside the basic template itself.

In this tutorial, I’ll explain how I added a new application (hrapp) to a Yii2 basic template project and ran it independently, without switching to the advanced template.

Folder Structure Overview

Once you’re done, your folder structure might look like this:

/your-project/
│
├── /config/
│   └── web.php
├── /vendor/
├── /web/
│   └── index.php          ← Main application (default)
├── /hrapp/
│   ├── /config/
│   │   └── main-local.php
│   └── /web/
│       └── index.php      ← New application (HR app)

Step 1: Add Aliases in the Main App

Edit your main app’s config/web.php and add an alias for the new app:

'aliases' => [
    '@app' => dirname(__DIR__),
    '@hrapp' => dirname(__DIR__) . '/hrapp',
],

This allows Yii to locate your second app and refer to it symbolically.

Step 2: Create the HR App Config

Inside the hrapp/config/ folder, create a file named web.php. This will serve as the configuration file for the second app. Make sure to reverse the alias logic here so that the @app points back to the root of the main project:

return [
    'id' => 'hrapp',
    'basePath' => dirname(__DIR__),
    'aliases' => [
        '@hrapp' => dirname(__DIR__),
        '@app' => dirname(__DIR__) . '/../',
    ],
    'components' => [
        'request' => [
            'cookieValidationKey' => 'your-secret-key',
        ],
        // Add other components like db, cache, urlManager, etc.
    ],
    'controllerNamespace' => 'hrapp\controllers',
];

main-local.php

<?php

$config =  (array_replace_recursive(
    require(dirname(__FILE__) . '/web.php'),
    array(
        'components' => [
            'db' => [
                'class' => 'yii\db\Connection',
                'dsn' => 'mysql:host=localhost;dbname=hr_app_db',
                'username' => 'root',
                'password' => '',
            ],
        ],
        'params' => [
            'baseurl' => 'http://hr.local',
        ],
    ),
));

return $config;

You can modify this config file further depending on your app’s needs.

Step 3: Create the HR App Entry Point

Now, create the entry script for your new app at hrapp/web/index.php:

<?php

defined('YII_DEBUG') or define('YII_DEBUG', true);
defined('YII_ENV') or define('YII_ENV', 'dev');

require __DIR__ . '/../../vendor/autoload.php';
require __DIR__ . '/../../vendor/yiisoft/yii2/Yii.php';

$config = require __DIR__ . '/../config/main-local.php';


(new yii\web\Application($config))->run();

Make sure the path to your vendor and Yii.php file is correct. You may be sharing a common vendor directory between all apps.

Step 4: Access the New App

If you’re running this locally or on a server, you can access the HR app directly by visiting:

http://yourdomain.com/hrapp/web/

You can also configure a separate virtual host for it:

ServerName hrapp.local
DocumentRoot /path-to-project/hrapp/web

Now your second app is isolated and runs independently of the default Yii app.

Why This Approach Works

This setup allows you to:

• Keep using the basic template
• Avoid migration hassles to the advanced template
• Create isolated apps/modules with separate configs and controllers
• Share the same core codebase and vendor directory

This approach is modular and practical for growing applications that don't want the complexity of the advanced template.

Optional: Shared Configuration

You can further refactor your code by placing shared config (such as DB or components) inside a common/config folder and including it in both apps like this:

$config = yii\helpers\ArrayHelper::merge(
    require __DIR__ . '/../../common/config/main.php',
    require __DIR__ . '/../config/main-local.php'
);

This helps reduce duplication and keeps your apps consistent.

Conclusion

You don’t need to move to the advanced template just to support multiple apps in Yii2. With a few configuration tweaks and folder separation, you can easily scale your basic template project into a multi-app architecture.

This method gives you flexibility without the overhead of a complex setup. It’s ideal for small teams or developers who prefer simplicity with scalability.