start-advanced.md 8.2 KB
Newer Older
1 2 3
Advanced application template
=============================

4
This template is for large projects developed in teams where the backend is divided from the frontend, application is deployed
5 6 7
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
### 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:

~~~
17
curl -sS http://getcomposer.org/installer | php
18 19 20 21 22
~~~

You can then install the application using the following command:

~~~
23
php composer.phar create-project --prefer-dist --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.
33 34 35
   ```
   php /path/to/yii-application/init
   ```
36 37 38 39
   Otherwise, in production execute `init` in non-interactive mode.
   ```
   php /path/to/yii-application/init --env=prod overwrite=n
   ```
40
2. Create a new database and adjust the `components.db` configuration in `common/config/main-local.php` accordingly.
41
3. Apply migrations with console command `yii migrate`.
42
4. Set document roots of your web server:
43

lancecoder committed
44 45
- 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
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
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.

72 73 74 75 76 77 78 79 80 81 82 83 84 85
Predefined path aliases
-----------------------

- @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.
- @web - base URL of currently running web application.
- @webroot - web root directory of currently running web application.

86 87 88 89 90 91 92 93 94
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.

95 96
frontend and backend are both web applications and both contain the `web` directory. That's the webroot you should point your
web server to.
97

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

100 101 102
Configuration and environments
------------------------------

103
There are multiple problems with a typical approach to configuration:
104

105
- Each team member has its own configuration options. Committing such config will affect other team members.
106 107
- 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.
108 109
- Defining all configuration options for each case is very repetitive and takes too much time to maintain.

110 111 112
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.
113

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

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

120 121
- `common/config/main.php`
- `common/config/main-local.php`
122 123 124 125 126 127 128 129 130 131 132
- `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.
133

134 135 136
Here's the full scheme:

![Advanced application configs](images/advanced-app-configs.png)
137 138 139 140

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

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

144
```json
145
{
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
    "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.4.0",
        "yiisoft/yii2": "*",
        "yiisoft/yii2-swiftmailer": "*",
        "yiisoft/yii2-bootstrap": "*",
        "yiisoft/yii2-debug": "*",
        "yiisoft/yii2-gii": "*"
    },
    "scripts": {
        "post-create-project-cmd": [
            "yii\\composer\\Installer::setPermission"
        ]
    },
    "extra": {
        "writable": [
            "backend/runtime",
            "backend/web/assets",

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

            "frontend/runtime",
            "frontend/web/assets"
        ]
    }
185 186 187 188 189 190
}
```

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

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

194
After your `composer.json` is changed you can run `php composer.phar update --prefer-dist`, wait till packages are downloaded and
195
installed and then just use them. Autoloading of classes will be handled automatically.
Alexander Makarov committed
196 197 198 199

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

200 201
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
202 203 204

```php
return [
205 206 207 208 209 210 211 212 213
    'components' => [
        'urlManager' => [
            // here is your normal backend url manager config
        ],
        'urlManagerFrontend' => [
            // here is your frontend URL manager config
        ],

    ],
Alexander Makarov committed
214 215 216
];
```

217
After it is done, you can get an URL pointing to frontend like the following:
Alexander Makarov committed
218 219 220 221

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