Merge branch 'master' of github.com:yiisoft/yii2

docs/guide/apps-advanced.md

+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.
+
+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:
+
+```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": {
+		"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](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.

docs/guide/apps-basic.md

+Basic application template
+==========================
+
+This template is a perfect fit for small projects or learning Yii2.
+
+The application has four pages: the homepage, the about page, the contact page and the login page.
+The contact page displays a contact form that users can fill in to submit their inquiries to the webmaster,
+and the login page allows users to be authenticated before accessing privileged contents.
+
+Directory structure
+-------------------
+
+The basic application does not divide application directories much. Here's the basic structure:
+
+- `commands` - console controllers.
+- `config` - configuration.
+- `controllers` - web controllers.
+- `models` - application models.
+- `runtime` - logs, states, file cache.
+- `views` - view templates.
+- `web` - webroot.
+
+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.
+- `codeception.yml` - Codeception config.
+- `composer.json` - Composer config described in detail below.
+- `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.
+
+
+### config
+
+This directory contains configuration files:
+
+- `AppAsset.php` - definition of application assets such as CSS, JavaScript etc. Check [Managing assets](assets.md) for
+  details.
+- `console.php` - console application configuration.
+- `params.php` - common application parameters.
+- `web.php` - web application configuration.
+- `web-test.php` - web application configuration used when running functional tests.
+
+All these files except `AppAsset.php` are returning arrays used to configure corresponding application properties. Check
+[Configuration](configuration.md) guide section for details.
+
+### views
+
+Views directory contains templates your application is using. In the basic template there are:
+
+```
+layouts
+	main.php
+site
+	about.php
+	contact.php
+	error.php
+	index.php
+	login.php
+```
+
+`layouts` contains HTML layouts i.e. page markup except content: doctype, head section, main menu, footer etc.
+The rest are typically controller views. By convention these are located in subdirectories matching controller id. For
+`SiteController` views are under `site`. Names of the views themselves are typically match controller action names.
+Partials are often named starting with underscore.
+
+### web
+
+Directory is a webroot. Typically a webserver is pointed into it.
+
+```
+assets
+css
+index.php
+index-test.php
+```
+
+`assets` contains published asset files such as CSS, JavaScript etc. Publishing process is automatic so you don't need
+to do anything with this directory other than making sure Yii has enough permissions to write to it.
+
+`css` contains plain CSS files and is useful for global CSS that isn't going to be compressed or merged by assets manager.
+
+`index.php` is the main web application bootstrap and is the central entry point for it. `index-test.php` is the entry
+point for functional testing.
+
+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:
+
+```javascript
+{
+	"name": "yiisoft/yii2-app-basic",
+	"description": "Yii 2 Basic Application Template",
+	"keywords": ["yii", "framework", "basic", "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": [
+			"runtime",
+			"web/assets"
+		],
+		"yii-install-executable": [
+			"yii"
+		]
+	}
+}
+```
+
+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.
\ No newline at end of file

docs/guide/bootstrap.md

-Bootstrap with Yii
-==================
-
-Yii provides a few ready-to-use application templates. Based on your needs, you may
-choose one of them to bootstrap your project.
-
-In the following, we describe how to get started with the "Yii 2 Basic Application Template".
-
-
-### 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 Bootstrap Application using the following command:
-
-~~~
-php composer.phar create-project --stability=dev yiisoft/yii2-app-basic yii-basic
-~~~
-
-Now you should be able to access the Bootstrap Application using the URL `http://localhost/yii-basic/web/`,
-assuming `yii-basic` is directly under the document root of your Web server.
-
-
-As you can see, the application has four pages: the homepage, the about page,
-the contact page and the login page. The contact page displays a contact
-form that users can fill in to submit their inquiries to the webmaster,
-and the login page allows users to be authenticated before accessing privileged contents.
-
-
-The following diagram shows the directory structure of this application.
-
-~~~
-yii-basic/
-   yii                    yii command line script for Unix/Linux
-   yii.bat                yii command line script for Windows
-   requirements.php       the requirement checker script
-   commands/              containing customized yii console commands
-   config/                containing configuration files
-      console.php         the console application configuration
-      main.php            the Web application configuration
-   controllers/           containing controller class files
-      SiteController.php  the default controller class
-   vendor/                containing third-party extensions and libraries
-   models/                containing model class files
-      User.php            the User model
-      LoginForm.php       the form model for 'login' action
-      ContactForm.php     the form model for 'contact' action
-   runtime/               containing temporarily generated files
-   views/                 containing controller view and layout files
-      layouts/            containing layout view files
-         main.php         the base layout shared by all pages
-      site/               containing view files for the 'site' controller
-         about.php        the view for the 'about' action
-         contact.php      the view for the 'contact' action
-         index.php        the view for the 'index' action
-         login.php        the view for the 'login' action
-   web/                   containing Web-accessible resources
-     index.php            Web application entry script file
-     assets/              containing published resource files
-     css/                 containing CSS files
-~~~
-
-
-TBD

docs/guide/index.md

@@ -7,9 +7,15 @@ Getting started
 ===============
 
 - [Installation](installation.md)
-- [Bootstrap with Yii](bootstrap.md)
 - [Configuration](configuration.md)
 
+Application templates
+=====================
+
+- [Basic](apps-basic.md)
+- [Advanced](apps-advanced.md)
+- [Creating your own application template](apps-own.md)
+
 Base concepts
 =============
 
@@ -57,13 +63,6 @@ Toolbox
 - [Error Handling](error.md)
 - [Logging](logging.md)
 
-Application templates
-=====================
-
-- [Basic](application-basic.md)
-- [Advanced](application-advanced.md)
-- [Creating your own application template](application-own.md)
-
 More
 ====
 
@@ -76,5 +75,6 @@ More
 - [Theming](theming.md)
 - [Console Application](console.md)
 - [Performance Tuning](performance.md)
+- [Managing assets](assets.md)
 - [Testing](testing.md)
 - [Upgrading from 1.1 to 2.0](upgrade-from-v1.md)

docs/guide/installation.md

@@ -4,7 +4,15 @@ Installation
 Installing via Composer
 -----------------------
 
-The recommended way of installing Yii is by using Composer package manager.
+The recommended way of installing Yii is by using [Composer](http://getcomposer.org/) package manager. If you do not
+have it, you may download it from [http://getcomposer.org/](http://getcomposer.org/) or run the following command:
+
+```
+curl -s http://getcomposer.org/installer | php
+```
+
+Yii provides a few ready-to-use application templates. Based on your needs, you may choose one of them to bootstrap
+your project.
 
 There are two application templates available:
 
@@ -12,7 +20,8 @@ There are two application templates available:
 - [advanced](https://github.com/yiisoft/yii2-app-advanced) that is a set of frontend, backend, console, common
  (shared code) and environments support.
 
-Please refer to installation instructions on these pages.
+Please refer to installation instructions on these pages. To read more about ideas behing these application templates and
+proposed usage refer to [basic application template](apps-basic.md) and [advanced application template](apps-advanced.md).
 
 Installing from zip
 -------------------