4. Directory Structure

The directory structure is quite different between basic and advanced templates. However, upon examination you will see there are also many similarities. The advanced template just provides more functionality.

4.1 Basic Template Directory Structure

• assets

Yii2 does a lot of asset management and caching. You create asset bundles that are used to include style sheets and Javascript files. Part of the advantage is that dependencies are handled and the scripts are properly included at the correct place.

There is a second assets folder under web. This folder is used by Yii as a cache for the assets. You need not concern yourself with this folder. If you are using git as version control repository, you will notice .gitignore is in that second assets folder. Nothing in that folder should be committed to the repository.

This folder needs to be writable by the web server. If you update JavaScript files or CSS files, you may need to delete all the folders in this directory. These can be safely deleted at any time. They are auto-generated by Yii as cache files.

• commands

The commands directory allows you to create Yii management scripts that run under command line. You execute these commands by navigating to the Yii root folder in command line terminal and typing php yii or just ./yii. If you type either of those by themselves in a command line environment, you will get a list of commands that are available by default.

In the basic template, there is one example included that you can access through command line like this: php yii hello

That will output 'Hello World' to your terminal.

• config

This folder holds the configuration files that include things like connecting Yii with your database, setting up e-mail sending, reformatting URLs and setting globally available parameter values.

• controllers

'C' of MVC. Controllers are the heart of Yii. Controllers are the traffic directors of an MVC framework. When you make a web request to a Yii powered site, the controller is what processes that request.

• mail

The mail folder contains the templates that Yii uses to construct an e-mail message.

• models

'M' of MVC. The models folder is where all the database functionality goes. If you need to query the database or perform any other database manipulation, the code will go in the models folder.

• runtime

The runtime folder is used by Yii when processing web requests. It needs to be writable and should be excluded from any Git repository (you will see a .gitignore file in this directory). You can safely ignore this directory.

• tests

The tests folder is set up to facilitate functional testing using Codeception.

• vendor

This directory is where the Yii source files reside. It is also where any additional third party modules that you install will be included. It is generally a very bad idea to alter the code in the vendor directory. The reason being that when you run any upgrades, the customized code you created will be overwritten.

The upgrade process is very easy using Composer. In command line terminal while in the Yii directory enter the following:

composer require yiisoft/yii2 2.0.6

(2.0.6 is the current version as of this writing.)

To update all third party plugins installed via Composer, execute the following command:

composer update

• views

'V' of MVC. The views folder holds the pages that are displayed upon a web request. These files contain the HTML markup that renders the pages that display the queried data.

• web

This is the document root directory that the web server points to. The primary function is index.php, which launches the Yii processes when called. Note that in this file, you can turn on or off the Yii debugging code. This enables the debug bar viewable at the bottom of the page, as mentioned in section 3.7.3.

You can set the Yii environment to 'dev' or 'prod' in the index.php file as well.

This folder is where you would put any files, images or other assets that you want to be accessible from the web. Only files in this folder can be accessed. You may want to have the following subdirectories:

• css

Containing all external style sheets.

• js

Containing all external Javascript files.

• images

All images to be used in any views.

There is one other subdirectory that you will find under web: assets. Like runtime, this directory is for use by Yii when responding to web requests. It needs to be writable by Yii and you can safely ignore it. This directory should also be excluded from any Git repo (hence the .gitignore file).

4.2 Advanced Template Directory Structure

• backend

As mentioned, with the advanced template, you actually have two Yii installs. The backend directory is a complete Yii structure, similar to what you will find in the Basic Template. You will find the following subdirectories:

• assets
• config
• controllers
• models
• runtime
• views
• web

Each of these directories offers the same functionality as the corresponding directories as explained in the Basic Template above.

One item to make note of here though is the config directory. Any configurations included in this config directory will apply only to web requests invoking the backend.

• common

The purpose of the common directory is to have it accessed by both backend and frontend. You will see the following subdirectories:

• config

Config files in this directory will apply to both backend and frontend.

• mail

Functions same as the mail found in the Basic Template described above.

• models

If you are using both backend and frontend, this is an important directory. The models directory in common allows you to access the same database functions from backend and frontend. If you are pulling the same data in particular instances, it makes sense to have just one model set up for that.

• widgets

The widgets directory is a handy place to put snippets of code that you want to access anywhere, frontend or backend. By default, there is one widget already included that you will surely make use of: Alert.php

A nice feature of Yii is the flash messaging. You can set a message that will be displayed on the next page loaded. You may have an alert that says there was an error submitting some info or a message saying info was successfully saved. These messages can be displayed simply using the following:

<?php Alert::begin(); ?>

• console

The console directory provides similar functionality to the command directory in the Basic Template, with some added features.

As with the command directory, you can execute scripts from the command line. The scripts that will be executed are put in the controllers subdirectory. Here is an example of the same console file that will output "hello world" when executing the following on command line: php yii hello

<?php

namespace console\controllers;

use yii\console\Controller;

class HelloController extends Controller
{
    public function actionIndex($message = 'hello world')
    {
        echo $message . "\n";
    }
}

In addition to the controller subdirectory, you have the following:

• config

Set up specific config settings that apply only to using the console in command line terminal

• migrations

Migrations is a powerful feature of Yii that enhances it portability. You can put full database schemas into the migrations folder and it will create the database tables for you as needed by executing the following command:

php yii migrate

You can even set the migrations up so that they can easily be reverted if need be.

• models

Database functions specifically for command line functions.

• runtime

This directory is for Yii internal use and can be ignored.

• environments

The environments directory has two subdirectories:

• dev
• prod

You can think of the environments as templates that can be applied by executing a command in terminal environment.

Both these subdirectories have the following additional subdirectories:

• backend
• common
• console
• frontend

If you set up Yii using the advanced template above, you made use of the environment function when you typed the following in command line terminal:

php init

and selected Development or Production.

When you run the init command and select one of the above, it overwrites the various corresponding files with the template files for dev or prod.

• frontend

The directory structure and functionality of the frontend directory is identical to the backend.

• tests

The tests folder is set up to facilitate functional testing using Codeception.

• vendor

Again, vendor is where all the source files for Yii reside. Refer to the Basic Template explanation above for details.