We use this folder structure setup on Clevertech for our own projects and we thought it was worth sharing with the community.
Even though it looks complicated at the beginning, you will find that it is not that hard as it seems once you understand its structure. Yii's project structure wiki obviously inspired a lot of this setup, and you will find that some of the paragraphs here are taken from their wiki.
Hope you find it as useful as we do to develop your own projects.
YiiBoilerplate, aims to provide Yii developers an application folder structure with sufficient flexibility to satisfy development needs from simple to enterprise applications.
It may look a little bit too complex at first sight but, at Clevertech, we understand that needs may vary along the development life cycle of a product in order to fulfill customer's requirements and that commonly forces developers to modify the initial folder structure, thus making very hard for a new developer to jump in and 'understand' where everything is located.
In order to avoid such time consuming tasks, ease the life of our beloved developers and increase productivity, we make use of this folder structure template for our projects.
Below the directory structure we are using:
/ backend/ components/ config/ environments/ main-private.php * main-prod.php params-private.php * params-prod.php main-env.php * main-local.php * main.php params-env.php * params-local.php * params.php test.php controllers/ SiteController.php ... extensions/ behaviors/ validators/ lib/ models/ FormModel.php ... modules/ runtime/ * views/ layouts/ site/ widgets/ www/ assets/ * css/ images/ js/ themes/ index.php .htaccess common/ components/ config/ environments/ params-private.php * params-prod.php params-env.php * params-local.php * params.php data/ extensions/ behaviors/ validators/ lib/ Behat/ Pear/ Yii/ Zend/ messages/ models/ widgets/ console/ commands/ components/ config/ environments/ lib/ migrations/ models/ runtime/ * yiic.php frontend/ components/ config/ environments/ main-private.php * main-prod.php params-private.php * params-prod.php main-env.php * main-local.php main.php params-env.php * params-local.php * params.php test.php controllers/ extensions/ behaviors/ validators/ lib/ models/ modules/ runtime/ * views/ layouts/ site/ www/ assets/ * css/ files/ images/ js/ less/ index.php robots.txt .htaccess tests/ bootstrap/ FeatureContext.php YiiContext.php features/ Startup.feature behat.yml INSTALL.md README.md runbehat runpostdeploy yiic yiic.bat
When working in a team development environment, using any of the VCS (Version Control System) available (i.e. Git, SVN), the files and folders marked with an asterisk should not be included in the revision system.
At the top-most level, we have:
The whole application is divided into three applications: backend, fronted and console. Following the directory structure of the yii project site, with some twist on its configuration. The common folder is to store all files (extensions, components, behaviors, models, etc… ) that are shared among the mentioned applications.
The directory structure of each application is very similar. For example backend and frontend both share the same directory structure with a slight variation at the www folder of the frontend and the inclusion of bootstrap theme and extensions for the backend, to easy the task to create Administrative panels.
The shared folder structure is this one:
We have created extensions and widgets folders, that could had been obviously included in the components folder, in order to clearly differentiate the types of components that could exist into a Yii application and easy the task to find them. So, for example, developers won't search for a widget that renders a jQuery UI plugin within a folder that has application wide components, or helpers, or extensions, or…
The directory structure for console application differs from the others as it doesn't require controllers, views, widgets, and www. It has a commands directory to store all console command class files.
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 console.
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.
- source: Yii Framework Site
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.
The configuration for this boilerplate is not that complicated as it seems at first sight. As mentioned before, if our system has both backend and frontend applications and they both share the same DB configuration. We just need to configure one of the files on the config sub-directory under the common folder.
The files within the config folder of each application and common folder requires a bit of explanation. When working in a team environment, different developers may have different development environments. These environments are also often different from the production environment. This is why the configuration folders on each application contains a list of files that try to avoid interference among the different environments.
As you can see, the config folders include a set of files:
The configuration tree override in the following way:
local settings > environment specific > main configuration file
That means that local settings override environment specific and its result override main configuration file. And this is true for all configurations folders being the common configuration folder settings predominant over the application specific one:
common shared params > application params common shared config > application config
There is a slight difference between the ****-private.php*** and the ****-local.php** files. The first ones are automatically read with the runpostdeploy script and it could be settings that developers sitting on same machines in internal networks, and the latest is the programmer's configurations.
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 developer's working directory.
The project has a very useful script that automatically creates the required and not shared folders for a Yii application: the runtime and assets folders, extracts the configuration settings specified for a specific environment and copies them to the ****-env.php*** files and runs migrations when not on private environments -we believe that migrations should be always run manually by developers on their machines.
From the application's root folder, to run the script simply do:
./runpostdeploy environmentType migrations
./runpostdeploy privateto use ****-private.php*** configurations)
And that's it! You have now a solid structure with a ready to use Bootstrap like backend admin interface and a frontend with latest HTML5Boilerplate improvements.
well-built beautifully designed web applications