1. Overall Structure
2. Top-level Directories
3. Application Configurations
4. Path Alias
5. Deployment

In this article, we describe the directory structure used by yiiframework.com - the official Yii framework website. While this structure may look overly complicated for small projects or may not be optimal in some sense, we believe it is appropriate for medium or large projects in a team development environment. In fact, we have successfully used the similar structure in some other big projects.

Overall Structure ¶

Below is the directory structure we are using:

/
	backend/
	common/
		components/
		config/
			params.php
			params-local.php *
		lib/
			Pear/
			yii/
			Zend/
		migrations/
		models/
			Comment.php
			Extension.php
			...
	console/
		commands/
			SitemapCommand.php
			...
		config/
			main.php
			main-local.php *
			params.php
			params-local.php *
		runtime/
		yiic.php *
	frontend/
		components/
		config/
			main.php
			main-local.php *
			params.php
			params-local.php *
		controllers/
			SiteController.php
			...
		lib/
		models/	
			ContactForm.php
			SearchForm.php		
		runtime/
		views/
			layouts/
			site/
		www/
			assets/
			css/
			js/
			index.php *
	yiic
	yiic.bat

In a team development environment, we should have some source code revision system (e.g. SVN, GIT) to manage the above structure. File names annotated with an asterisk should NOT be put in the revision system, as we will explain shortly.

Top-level Directories ¶

At the top level, we have four directories:

• backend: the backend application which is mainly used site administrators to manage the whole system.
• frontend: the frontend application which provides the main interfaces to our target end users.
• console: the console application that consists of the console commands needed by the system.
• common: the directory whose content are shared among the above applications.

As we can see, we divide the whole system into three applications: backend, frontend and console. If needed, we can add more applications (e.g. api, to provide Web API service). We use common to store files that are shared among the applications.

Application Directories ¶

The directory structure of each application is very similar. For example, for frontend and backend, they both have these directories:

• components: contains components (e.g. helpers, widgets) that are only used by this application
• config: contains the configuration used by the application
• controllers: contains controller classes
• lib: contains third-party libraries that are only used by this application
• models: contains model classes that are specific for the application
• runtime: stores dynamically generated files
• views: stores controller actions view scripts
• www: the web root for this application

The directory structure for console is slightly different as it does not need controllers, views and www. Instead, it contains a commands directory to store all console command class files.

The Common Directory ¶

The common directory contains the files that are shared among applications. For example, every application may need to access the database using ActiveRecord. Therefore, we can store the AR model classes under the common directory. Similarly, if some helper or widget classes are used in more than one application, we should also put them under common to avoid duplication of code.

To facilitate the maintenance of code, we organize the common directory in a structure similar to that of an application. For example, we have components, 'models, lib`, etc.

As we will soon explain, applications may also share part of the configurations. Therefore, we also store the common configurations under the config directory in common.

When developing a large project with a long development cycle, we constantly need to adjust the database structure. For this reason, we also use the DB migration feature to keep track of database changes. We store all DB migrations under the migrations directory in common.

Application Configurations ¶

Applications of the same system usually share some common configurations, such as DB connection configuration, application parameters, etc. In order to eliminate duplication of code, we should extract these common configurations and store them in a central place. In our setting, we put them under the config directory in common.

When working in a team environment, different developers may have different development environments (e.g. operating system, directories, DB connections). These environments are also often different from the production environment. In order to avoid interference among developers, we divide the configurations into two parts: the base configuration (e.g. main.php, params.php) and the local configuration (e.g. main-local.php, params-local.php).

The base configuration should be put under version control, like regular source code, so that it can be shared by every developer.

The local configuration should NOT be put under version control and should only exist in each individual developer's working folder. A developer has full freedom to modify his local configuration.

In the application's bootstrap script index.php, we can merge the base and local configurations and then configure the application instance, like the following:

require('path/to/yii.php');
$local=require('path/to/main-local.php');
$base=require('path/to/main.php');
$config=CMap::mergeArray($base, $local);
Yii::createApplication($config)->run();

Path Alias ¶

To facilitate referencing files in different applications, we also declare a root path alias site which points to the root directory containing the four top directories. As a result, we can use site.frontend.models.ContactForm to reference the ContactForm class declared in the frontend application.

Deployment ¶

During development or after finishing a project, we need to deploy it to the production server. Instead of uploading files to the server using FTP or other similar services, we can use revision control system to do the deployment.

We can treat the production server as a special developer who has the production server as his development environment.

We first check out an initial copy or update an existing copy from the revision control system to the desired location on the production server.

We then create or modify the local configurations specific for the production server. For example, we may need to adjust the DB connection parameters. We may want to define YII_DEBUG to be false in index.php.

Because we store each application in a separate directory, if needed, we can deploy them to different servers.