Yii 1.1: YiiBoilerplate - Setup a professional project structure in seconds

81 followers

YiiBoilerplate

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.

Overview

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.

Overall Structure

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.

Top Level Directories

At the top-most level, we have:

  • backend: the backend application which will be mainly used by site administrators to manage the whole system (avoiding admin modules at frontend application to avoid confusion)
  • console: the console application that is compound of the console commands required for the system.
  • frontend: the frontend application that is the main interface for end users. On a website development, this would be what the site users would see.
  • common: the directory whose content is shared among all the above applications.
  • test: the folder where we include all of our BDD system tests.

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.

Application Directories

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:

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

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

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

 

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.

How to configure the application

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:

  • environments/params-private.php: This is to have the application parameters required for the developer on its development environment.
  • environments/params-prod.php: This is to have the application parameters required for the application on production
  • environments/main-private.php: The application configuration settings required for the developer on its development environment.
  • environments/main-prod.php: The application configuration settings required for the application on production
  • main-env.php: This file will be override with the environment specific application configuration selected by the runpostDeploy script (as we are going to explain after)
  • main-local.php: This is the application configuration options for the developer*
  • params-env.php: This will be override with the environment specific parameters selected by the runpostdeploy script
  • params-local.php: The application parameters for the developer*
  • params.php: The application parameters
  • test.php: Test application configuration options

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 runpostdeploy script

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

  • environmentType (required): can be "any" of the ones you configure on the environments folders (i.e. ./runpostdeploy private to use ****-private.php*** configurations)
  • migrations (optional): could be "migrate"" or "no-migrate".
    • migrate: will run migrations
    • no-migrate: will not run migrations (on private wont run them anyway)

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.

Resources and Download

Get the most up to date version from the Github repository!

====

Clevertech
well-built beautifully designed web applications
www.clevertech.biz

Total 20 comments

#13983 report it
hemc at 2013/07/10 02:22pm
Re:Performance issue

I have removed bootstrap from preload, and now it's performance is much better.

#13917 report it
Fsciuti at 2013/07/05 01:18pm
PHPUnit Problems

Hi! I have the same problem:

"I'm trying to run PHPUnit tests on a project created with the boilerplate but getting errors. I'm assuming this has something to do with the different folder structure, because regular yiic-generated projects run tests just fine.

Any pointers for this?"

Thanks!

#13786 report it
Tibor Katelbach at 2013/06/26 04:23am
maybe due to using less

isn't the overhead caused by activated less compilation ? is there a way stop it when no changing were applied to css ? is this still a project to follow or is there something new to wait for ?

#13137 report it
Hesam at 2013/05/07 09:42am
Re:Performance issue

I don't know if the developer support this section or not, he is working on a new project called YiiWheels. You may disable the debug mode in index.php found in frontend/www. That might help specially if you're using the bootstrap extension.

#13136 report it
hemc at 2013/05/07 09:19am
Performance issue

I have setup boilerplate for a big project and i realized that boilerplate is very slow. So, what can i do for performance boosting ? Does anyone facing the same performance issue.

#13088 report it
Hesam at 2013/05/03 11:22am
Zend Lucene

Hi, I was using Zend Lucene and then I updated my folder structure to boilerplate. I realized that two folders were totally missing in Boilerplate original Zend/Search folder. Just want to tell the others if they face the same problem, they have to update at least that folder and replace all require_one in all php files in that folder.

#13072 report it
hemc at 2013/05/02 01:05am
@leo4all

You need to understand that front end and back end are separate hence user authenticate is also separate. IN case of rights, i have implemented it in backend and working fine.If you want to implement rights to backend and frontend do it separately. I am not sure if you can implement it in common section.

#13069 report it
leo4all at 2013/05/01 11:26am
Rights and User Ext

I have Install Rights and User Extensions, Two questions. First, let say if I logged in from the frontend as admin and then goes to backend. it redirect me to login screen again in the backend what can be the issue here.

Second, the rights extension, when I Generate items for controller actions, it only display controllers in the backend side, and doesn't have any ideas of the controllers in the frontend area. (now when the permission are apply in filter it will have no idea of this permission for the frontend section??)

Sorry my english or the question are bad formulate.

#12770 report it
hemc at 2013/04/11 05:24am
Yii upgrade to 1.1.13

If i just replace yii to new version 1.1.13. will it create some problem to compatibility to Yii Bootstrap?

#12685 report it
Win Naung at 2013/04/05 05:54am
Cannot find the Yiic

When I run the command "runpostdeploy private migrate" in Windows command prompt, it shows error. "... Could not open the input file: "C:\root folder\common\lib/../../yiic".

The script can create directories. But when the script run the command "php 'C:\rood folder\common\lib/../../yiic' migrate --interactive=0, I encountered the above error.

Please suggest me how I can solve this issue.

#12651 report it
urgent at 2013/04/04 12:33am
Test Config

I am trying to use the behat tests with Yii's built in CDbTestCase

In tests/bootstrap/FeatureContext.php, there is this comment.

"And your test config will be in /common/config/test.php file."

Should I create this file by copying the one from either frontend or backend app? It looks like it will need to be changed as basePath will not work.

I would like to run tests on both frontend and backend apps though, hopefully using one behat command for ease of use in a CI server. Is it possible or will I have to switch between config files?

#12153 report it
Amr Bedair at 2013/03/01 02:14pm
yii 1.1.13, zend 2 migration

are your planing to migrate up to the latest yii 1.1.13 , zend 2.x, and YiiBootstrap 2.0.3 ... and when?

Thanks for the great effort

#11732 report it
Mohsin Ali at 2013/01/30 07:56am
How To Login Into Backend Yiiboilerplate

I have installed yiiboilerplate. I am on login screen of backend but I don't know the username / password?

#11725 report it
Hesam at 2013/01/29 04:50pm
Backend about.php

Hi Antonio, In your backend application: you may add 'page' action to SiteController, since the latest version is asking the user to login in order to see the static about page.

#11366 report it
yasen at 2013/01/09 02:56pm
Forum Thread

@Rodrigo make sure in your apache config you have: AllowOverride All

@Toni, should we make a forum thread for questions and answers as the comments here aren't meant for questions I believe...

Edit: Here's the forum thread for YiiBooster

#11109 report it
语过添情 at 2012/12/17 10:57am
安装yii-user需要注意:

比如说yii-user安装在common/modules/,在backend使用yii-user时, backend/config/main.php 以及 console/config/main.php 需要在下面添加一条:

'modules' => array(
  'user' => array(
    # 添加下面这条,不然会报错。
    'class'=>'common.modules.user.UserModule',
    ...
  ),
)

另外修改:modules/user/controllers/ProfileFieldController.php 把:

Yii::getPathOfAlias('application.modules.user.views.asset');

修改为:

Yii::getPathOfAlias('common.modules.user.views.asset');

还有:

Yii::getPathOfAlias('application.modules.user.components');

修改为:

Yii::getPathOfAlias('common.modules.user.components');

祝你好运!

#11077 report it
Rodrigo at 2012/12/14 12:28pm
URL rules not working

Hi,

I've cloned github repo inside my webroot dir (apache mod_rewrite enabled), Set RewriteBase to /YiiBoilerplate/backend/www (backend's .htaccess) Browsed http://localhost/YiiBoilerplate/backend/www and when i click on links about, contact or login i get a 404 error

http://localhost/YiiBoilerplate/backend/www/site/page/?view=about http://localhost/YiiBoilerplate/backend/www/site/contact/ http://localhost/YiiBoilerplate/backend/www/site/login/

What I'm missing?

Regards, Rodrigo

#10993 report it
Antonio Ramirez at 2012/12/09 04:33am
@thiagovidal

Isn't it here? github repository user schema

I know that at the migration we shouldn't make use of models, that will be changed.

#10982 report it
thiagovidal at 2012/12/07 07:38pm
User Table Schema

Hey Antonio. Nice job. This is what I was looking for to setup a new project. I'm searching on the code, here and google for schema of the user table with admin credentials. Can you help me?

#10689 report it
Antonio Ramirez at 2012/11/15 09:14am
@Ivica

The reason why I put themes in the backend is because is normally there that we change the styling of our admin panel and the frontend is normally used to have the frontend design that could be anything totally outside from theming Yii...

Leave a comment

Please to leave your comment.

Write new article