Advanced application template

This template is for large projects developed in teams where backend is divided from frontend, application is deployed to multiple servers etc. This application template also goes a bit further regarding features and provides essential database, signup and password restore out of the box.

Installation

Install via Composer

If you do not have Composer, you may download it from http://getcomposer.org/ or run the following command on Linux/Unix/MacOS:

curl -s http://getcomposer.org/installer | php

You can then install the application using the following command:

php composer.phar create-project --stability=dev yiisoft/yii2-app-advanced /path/to/yii-application

Getting started

After you install the application, you have to conduct the following steps to initialize the installed application. You only need to do these once for all.

Execute the init command and select dev as environment.

php /path/to/yii-application/init

Create a new database. It is assumed that MySQL InnoDB is used. If not, adjust console/migrations/m130524_201442_init.php.
In common/config/params.php set your database details in components.db values.
Set document roots of your Web server:

for frontend /path/to/yii-application/frontend/web/ and using the URL http://frontend/
for backend /path/to/yii-application/backend/web/ and using the URL http://backend/

Directory structure

The root directory contains the following subdirectories:

backend - backend web application.
common - files common to all applications.
console - console application.
environments - environment configs.
frontend - frontend web application.

Root directory contains a set of files.

.gitignore contains a list of directories ignored by git version system. If you need something never get to your source code repository, add it there.
composer.json - Composer config described in detail below.
init - initialization script described in "Composer config described in detail below".
init.bat - same for Windows.
LICENSE.md - license info. Put your project license there. Especially when opensourcing.
README.md - basic info about installing template. Consider replacing it with information about your project and its installation.
requirements.php - Yii requirements checker.
yii - console application bootstrap.
yii.bat - same for Windows.

Applications

There are three applications in advanced template: frontend, backend and console. Frontend is typically what is presented to end user, the project itself. Backend is admin panel, analytics and such functionality. Console is typically used for cron jobs and low-level server management. Also it's used during application deployment and handles migrations and assets.

There's also a common directory that contains files used by more than one application. For example, User model.

frontend and backend are both web applications and both contain web directory. That's the webroot you should point your webserver to.

Each application has its own namespace and alias corresponding to its name. Same applies to common directory.

Configuration and environments

There are multiple problems with straightforward approach to configuration:

Each team member has its own configuration options. Commiting such config will affect other team members.
Production database password and API keys should not end up in repository.
There are multiple servers: development, testing, production. Each should have its own configuration.
Defining all configuration options for each case is very repetitive and takes too much time to maintain.

In order to solve these issues Yii introduces environments concept that is very simple. Each environment is represented by a set of files under environments directory. init command is used to switch between these. What is really does is just copying everything from environment directory over the root directory where all applications are.

Typically environment contains application bootstrap files such as index.php and config files postfixed with -local.php. These are added to .gitignore and never added to source code repository.

In order to avoid duplication configurations are overrding each other. For example, frontend reads configuration in the following order:

frontend/config/main.php
frontend/config/main-local.php

Parameters are read in the following order:

common/config/params.php
common/config/params-local.php
frontend/config/params.php
frontend/config/params-local.php

The later config file overrides the former.

Another difference is that most application component configurations are moved to params. Since params are read from common as well it allows you to specify database connection in one file and it will be then used for all applications.

Configuring Composer

After application template is installed it's a good idea to adjust defaul composer.json that can be found in the root directory:

{
	"name": "yiisoft/yii2-app-advanced",
	"description": "Yii 2 Advanced Application Template",
	"keywords": ["yii", "framework", "advanced", "application template"],
	"homepage": "http://www.yiiframework.com/",
	"type": "project",
	"license": "BSD-3-Clause",
	"support": {
		"issues": "https://github.com/yiisoft/yii2/issues?state=open",
		"forum": "http://www.yiiframework.com/forum/",
		"wiki": "http://www.yiiframework.com/wiki/",
		"irc": "irc://irc.freenode.net/yii",
		"source": "https://github.com/yiisoft/yii2"
	},
	"minimum-stability": "dev",
	"require": {
		"php": ">=5.3.0",
		"yiisoft/yii2": "dev-master",
		"yiisoft/yii2-composer": "dev-master"
	},
	"scripts": {
		"post-create-project-cmd": [
			"yii\\composer\\InstallHandler::setPermissions"
		]
	},
	"extra": {
		"yii-install-writable": [
			"backend/runtime",
			"backend/web/assets",

			"console/runtime",
			"console/migrations",

			"frontend/runtime",
			"frontend/web/assets"
		]
	}
}

First we're updating basic information. Change name, description, keywords, homepage and support to match your project.

Now the interesting part. You can add more packages your application needs to require section. For example, to use markdown helper you need to add michelf/php-markdown. All these packages are coming from packagist.org so feel free to browse the website for useful code.

After your composer.json is changed you can run php composer.phar update, wait till packages are downloaded and installed and then just use them. Autoloading of classes will be handled automatically.

6.7 KiB Raw Blame History