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:
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
www. Instead, it contains a
commands directory to store all console command class files.
The Common Directory ¶
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
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
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
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
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.
params.php) and the local configuration (e.g.
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
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
Because we store each application in a separate directory, if needed, we can deploy them to different servers.