tutorial-advanced-app.md 9.75 KB
Newer Older
Qiang Xue committed
1
Advanced Application Template
2 3
=============================

4
> Note: This section is under development.
Qiang Xue committed
5

6
This template is for large projects developed in teams where the backend is divided from the frontend, application is deployed
7 8 9
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.

Qiang Xue committed
10 11 12 13 14 15 16
The following table compares the difference between the advanced and the basic application templates:


| Feature  |  Basic  |  Advanced |
|---|:---:|:---:|
| Project structure |  ✓  |  ✓  |
| Site controller |  ✓  |  ✓  |
17 18
| User login/logout |   ✓  |  ✓  |
| Forms  |   ✓  |  ✓  |
Qiang Xue committed
19 20 21 22 23
| DB connection  |   ✓  |  ✓  |
| Console command  |   ✓  |  ✓  |
| Asset bundle  |   ✓  |  ✓  |
| Codeception tests  |   ✓  |  ✓  |
| Twitter Bootstrap  |  ✓   |  ✓  |
24 25 26
| Front- and back-end apps  |    |  ✓  |
| Ready to use User model |    |  ✓  |
| User signup and password restore  |     |  ✓  |
Qiang Xue committed
27 28


Alexander Makarov committed
29 30 31
Installation
------------

32 33
### Install via Composer

34 35
If you do not have [Composer](http://getcomposer.org/), follow the instructions in the
[Installing Yii](start-installation.md#installing-via-composer) section to install it.
36

37
With Composer installed, you can then install the application using the following commands:
38

Qiang Xue committed
39
    composer global require "fxp/composer-asset-plugin:1.0.0-beta4"
germanliu committed
40
    composer create-project --prefer-dist yiisoft/yii2-app-advanced yii-application
41

42 43 44 45
The first command installs the [composer asset plugin](https://github.com/francoispluchino/composer-asset-plugin/)
which allows managing bower and npm package dependencies through Composer. You only need to run this command
once for all. The second command installs the advanced application in a directory named `yii-application`.
You can choose a different directory name if you want.
46 47 48 49 50 51 52 53

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.
Alexander Makarov committed
54 55 56 57 58 59 60 61

    ```
    php /path/to/yii-application/init
    ```

    Otherwise, in production execute `init` in non-interactive mode.

    ```
62
    php /path/to/yii-application/init --env=Production --overwrite=All
Alexander Makarov committed
63 64
    ```

65
2. Create a new database and adjust the `components.db` configuration in `common/config/main-local.php` accordingly.
66
3. Apply migrations with console command `yii migrate`.
67
4. Set document roots of your web server:
68

lancecoder committed
69 70
- 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
71

72 73
To login into the application, you need to first sign up, with any of your email address, username and password. Then, you can login into the application with same email address and password at any time.

74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
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.
89 90
- `composer.json` - Composer config described in "Configuring Composer" below.
- `init` - initialization script described in "Configuration and environments" below.
91 92 93 94 95 96 97 98
- `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.

99 100 101
Predefined path aliases
-----------------------

102 103 104 105 106 107 108 109
- `@yii` - framework directory.
- `@app` - base path of currently running application.
- `@common` - common directory.
- `@frontend` - frontend web application directory.
- `@backend` - backend web application directory.
- `@console` - console directory.
- `@runtime` - runtime directory of currently running web application.
- `@vendor` - Composer vendor directory.
110 111
- `@bower` - vendor directory that contains the [bower packages](http://bower.io/).
- `@npm` - vendor directory that contains [npm packages](https://www.npmjs.org/).
112 113 114 115
- `@web` - base URL of currently running web application.
- `@webroot` - web root directory of currently running web application.

The aliases specific to the directory structure of the advanced application
116
(`@common`,  `@frontend`, `@backend`, and `@console`) are defined in `common/config/bootstrap.php`.
117

118

119 120 121 122 123 124 125 126 127
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.

128 129
frontend and backend are both web applications and both contain the `web` directory. That's the webroot you should point your
web server to.
130

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

133 134 135
Configuration and environments
------------------------------

136
There are multiple problems with a typical approach to configuration:
137

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

143 144 145
In order to solve these issues Yii introduces a simple environments concept. Each environment is represented
by a set of files under the `environments` directory. The `init` command is used to switch between these. What it really does is
copy everything from the environment directory over to the root directory where all applications are.
146

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

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

153 154
- `common/config/main.php`
- `common/config/main-local.php`
155 156 157 158 159 160 161 162 163 164 165
- `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.
166

167 168 169
Here's the full scheme:

![Advanced application configs](images/advanced-app-configs.png)
170 171 172 173

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

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

177
```json
178
{
179 180
    "name": "yiisoft/yii2-app-advanced",
    "description": "Yii 2 Advanced Application Template",
181
    "keywords": ["yii2", "framework", "advanced", "application template"],
182 183 184 185 186 187 188 189 190 191 192 193 194 195 196
    "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.4.0",
        "yiisoft/yii2": "*",
        "yiisoft/yii2-bootstrap": "*",
197 198 199 200
        "yiisoft/yii2-swiftmailer": "*"
    },
    "require-dev": {
        "yiisoft/yii2-codeception": "*",
201
        "yiisoft/yii2-debug": "*",
202 203
        "yiisoft/yii2-gii": "*",
        "yiisoft/yii2-faker": "*"
204
    },
205 206
    "config": {
        "process-timeout": 1800
207 208
    },
    "extra": {
209 210 211 212
        "asset-installer-paths": {
            "npm-asset-library": "vendor/npm",
            "bower-asset-library": "vendor/bower"
        }
213
    }
214 215 216 217 218 219
}
```

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

220
Now the interesting part. You can add more packages your application needs to the `require` section.
221
All these packages are coming from [packagist.org](https://packagist.org/) so feel free to browse the website for useful code.
222

223
After your `composer.json` is changed you can run `composer update --prefer-dist`, wait till packages are downloaded and
224
installed and then just use them. Autoloading of classes will be handled automatically.
Alexander Makarov committed
225 226 227 228

Creating links from backend to frontend
---------------------------------------

229 230
Often it's required to create links from the backend application to the frontend application. Since the frontend application may
contain its own URL manager rules you need to duplicate that for the backend application by naming it differently:
Alexander Makarov committed
231 232 233

```php
return [
234 235 236 237 238 239 240 241 242
    'components' => [
        'urlManager' => [
            // here is your normal backend url manager config
        ],
        'urlManagerFrontend' => [
            // here is your frontend URL manager config
        ],

    ],
Alexander Makarov committed
243 244 245
];
```

246
After it is done, you can get an URL pointing to frontend like the following:
Alexander Makarov committed
247 248 249 250

```php
echo Yii::$app->urlManagerFrontend->createUrl(...);
```