apps-advanced.md 6.72 KB
Newer Older
1 2 3
Advanced application template
=============================

4 5 6 7
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.

Alexander Makarov committed
8 9 10
Installation
------------

11 12 13 14 15 16 17 18 19 20 21 22
### Install via Composer

If you do not have [Composer](http://getcomposer.org/), you may download it from
[http://getcomposer.org/](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:

~~~
lancecoder committed
23
php composer.phar create-project --stability=dev yiisoft/yii2-app-advanced /path/to/yii-application
24 25 26 27 28 29 30 31 32
~~~

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.

1. Execute the `init` command and select `dev` as environment.
lancecoder committed
33 34 35
---
php /path/to/yii-application/init
---
36 37 38
2. Create a new database. It is assumed that MySQL InnoDB is used. If not, adjust `console/migrations/m130524_201442_init.php`.
3. In `common/config/params.php` set your database details in `components.db` values.

lancecoder committed
39
4. Set document roots of your Web server:
40

lancecoder committed
41 42
- 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/`
Alexander Makarov committed
43

44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
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.

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

83 84 85
Configuration and environments
------------------------------

86 87
There are multiple problems with straightforward approach to configuration:

88
- Each team member has its own configuration options. Committing such config will affect other team members.
89 90 91 92 93 94 95 96
- 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.

Luciano Baraglia committed
97
Typically environment contains application bootstrap files such as `index.php` and config files suffixed with
98 99
`-local.php`. These are added to `.gitignore` and never added to source code repository.

Carsten Brandt committed
100
In order to avoid duplication configurations are overriding each other. For example, frontend reads configuration in the
101 102 103 104 105 106 107 108 109 110 111 112 113
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.
114

115 116
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.
117 118 119 120

Configuring Composer
--------------------

Luciano Baraglia committed
121
After application template is installed it's a good idea to adjust default `composer.json` that can be found in the root
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140
directory:

```javascript
{
	"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": {
141
		"php": ">=5.4.0",
142 143 144 145 146
		"yiisoft/yii2": "dev-master",
		"yiisoft/yii2-composer": "dev-master"
	},
	"scripts": {
		"post-create-project-cmd": [
Qiang Xue committed
147
			"yii\\composer\\Installer::setPermission"
148 149 150
		]
	},
	"extra": {
Qiang Xue committed
151
		"writable": [
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174
			"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](https://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.