. Alternatively you can use the syntax that can be recognized by the
-PHP [date()](http://php.net/manual/en/function.date.php) function using a string that is prefixed with `php:`.
-
-```php
-// ICU format
-echo Yii::$app->formatter->asDate('now', 'yyyy-MM-dd'); // 2014-10-06
-// PHP date()-format
-echo Yii::$app->formatter->asDate('now', 'php:Y-m-d'); // 2014-10-06
-```
-
-### Time zones
-
-When formatting date and time values, Yii will convert them to the [[yii\i18n\Formatter::timeZone|configured time zone]].
-Therefore the input value is assumed to be in UTC unless a time zone is explicitly given. For this reason
-it is recommended to store all date and time values in UTC, preferably as a UNIX timestamp, which is always UTC by definition.
-If the input value is in a time zone different from UTC, the time zone has to be stated explicitly like in the following example:
-
-```php
-// assuming Yii::$app->timeZone = 'Europe/Berlin';
-echo Yii::$app->formatter->asTime(1412599260); // 14:41:00
-echo Yii::$app->formatter->asTime('2014-10-06 12:41:00'); // 14:41:00
-echo Yii::$app->formatter->asTime('2014-10-06 14:41:00 CEST'); // 14:41:00
-```
-
-Since version 2.0.1 it is also possible to configure the time zone that is assumed for timestamps that do not include a time zone
-identifier like the second example in the code above. You can set [[yii\i18n\Formatter::defaultTimeZone]] to the time zone you use for data storage.
-
-> Note: As time zones are subject to rules made by the governments around the world and may change frequently, it is
-> likely that you do not have the latest information in the time zone database installed on your system.
-> You may refer to the [ICU manual](http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data)
-> for details on updating the time zone database.
-> See also: [Setting up your PHP environment for internationalization](tutorial-i18n.md#setup-environment).
-
-
-Formatting Numbers
-------------------
-
-For formatting numeric values the formatter class provides the following methods:
-
-- [[yii\i18n\Formatter::asInteger()|integer]] - the value is formatted as an integer e.g. `42`.
-- [[yii\i18n\Formatter::asDecimal()|decimal]] - the value is formatted as a decimal number considering decimal and thousand
- separators e.g. `2,542.123` or `2.542,123`.
-- [[yii\i18n\Formatter::asPercent()|percent]] - the value is formatted as a percent number e.g. `42%`.
-- [[yii\i18n\Formatter::asScientific()|scientific]] - the value is formatted as a number in scientific format e.g. `4.2E4`.
-- [[yii\i18n\Formatter::asCurrency()|currency]] - the value is formatted as a currency value e.g. `£420.00`.
- Note that for this function to work properly, the locale needs to include a country part e.g. `en_GB` or `en_US` because language only
- would be ambiguous in this case.
-- [[yii\i18n\Formatter::asSize()|size]] - the value that is a number of bytes is formatted as a human readable size e.g. `410 kibibytes`.
-- [[yii\i18n\Formatter::asShortSize()|shortSize]] - is the short version of [[yii\i18n\Formatter::asSize()|size]], e.g. `410 KiB`.
-
-The format for number formatting can be adjusted using the [[yii\i18n\Formatter::decimalSeparator|decimalSeparator]] and
-[[yii\i18n\Formatter::thousandSeparator|thousandSeparator]] which are set by default according to the locale.
-
-For more advanced configuration, [[yii\i18n\Formatter::numberFormatterOptions]] and [[yii\i18n\Formatter::numberFormatterTextOptions]]
-can be used to configure the internally used [NumberFormatter class](http://php.net/manual/en/class.numberformatter.php)
-
-For example, to adjust the maximum and minimum value of fraction digits, you can configure [[yii\i18n\Formatter::numberFormatterOptions]] property like the following:
-
-```php
-'numberFormatterOptions' => [
- NumberFormatter::MIN_FRACTION_DIGITS => 0,
- NumberFormatter::MAX_FRACTION_DIGITS => 2,
-]
-```
-
-Other formatters
-----------------
-
-In addition to date, time and number formatting, Yii provides a set of other useful formatters for different situations:
-
-- [[yii\i18n\Formatter::asRaw()|raw]] - the value is outputted as is, this is a pseudo-formatter that has no effect except that
- `null` values will be formatted using [[nullDisplay]].
-- [[yii\i18n\Formatter::asText()|text]] - the value is HTML-encoded.
- This is the default format used by the [GridView DataColumn](output-data-widgets.md#data-column).
-- [[yii\i18n\Formatter::asNtext()|ntext]] - the value is formatted as an HTML-encoded plain text with newlines converted
- into line breaks.
-- [[yii\i18n\Formatter::asParagraphs()|paragraphs]] - the value is formatted as HTML-encoded text paragraphs wrapped
- into `` tags.
-- [[yii\i18n\Formatter::asHtml()|html]] - the value is purified using [[HtmlPurifier]] to avoid XSS attacks. You can
- pass additional options such as `['html', ['Attr.AllowedFrameTargets' => ['_blank']]]`.
-- [[yii\i18n\Formatter::asEmail()|email]] - the value is formatted as a `mailto`-link.
-- [[yii\i18n\Formatter::asImage()|image]] - the value is formatted as an image tag.
-- [[yii\i18n\Formatter::asUrl()|url]] - the value is formatted as a hyperlink.
-- [[yii\i18n\Formatter::asBoolean()|boolean]] - the value is formatted as a boolean. By default `true` is rendered
- as `Yes` and `false` as `No`, translated to the current application language. You can adjust this by configuring
- the [[yii\i18n\Formatter::booleanFormat]] property.
-
-`null`-values
--------------
-
-For values that are `null` in PHP, the formatter class will print a placeholder instead of an empty string which
-defaults to `(not set)` translated to the current application language. You can configure the
-[[yii\i18n\Formatter::nullDisplay|nullDisplay]] property to set a custom placeholder.
-If you do not want special handling for `null` values, you can set [[yii\i18n\Formatter::nullDisplay|nullDisplay]] to `null`.
diff --git a/docs/guide/output-formatting.md b/docs/guide/output-formatting.md
index fd4af44ab5..92e73489db 100644
--- a/docs/guide/output-formatting.md
+++ b/docs/guide/output-formatting.md
@@ -1,3 +1,4 @@
+<<<<<<< HEAD
Data Formatter
==============
@@ -106,14 +107,111 @@ Additionally you can specify custom formats using the syntax defined by the
[ICU Project](http://site.icu-project.org/) which is described in the ICU manual under the following URL:
. Alternatively you can use the syntax that can be recognized by the
PHP [date()](http://php.net/manual/en/function.date.php) function using a string that is prefixed with `php:`.
+=======
+Data Formatting
+===============
+
+To display data in a more readable format for users, you may format them using the `formatter` [application component](structure-application-components.md).
+By default the formatter is implemented by [[yii\i18n\Formatter]] which provides a set of methods to format data as
+date/time, numbers, currencies, and other commonly used formats. You can use the formatter like the following,
+
+```php
+$formatter = \Yii::$app->formatter;
+
+// output: January 1, 2014
+echo $formatter->asDate('2014-01-01', 'long');
+
+// output: 12.50%
+echo $formatter->asPercent(0.125, 2);
+
+// output: cebe@example.com
+echo $formatter->asEmail('cebe@example.com');
+
+// output: Yes
+echo $formatter->asBoolean(true);
+// it also handles display of null values:
+
+// output: (Not set)
+echo $formatter->asDate(null);
+```
+
+As you can see, all these methods are named as `asXyz()`, where `Xyz` stands for a supported format. Alternatively,
+you may format data using the generic method [[yii\i18n\Formatter::format()|format()]], which allows you to control
+the desired format programmatically and is commonly used by widgets like [[yii\grid\GridView]] and [[yii\widgets\DetailView]].
+For example,
+
+```php
+// output: January 1, 2014
+echo Yii::$app->formatter->format('2014-01-01', 'date');
+
+// you can also use an array to specify parameters for the format method:
+// `2` is the value for the $decimals parameter of the asPercent()-method.
+// output: 12.50%
+echo Yii::$app->formatter->format(0.125, ['percent', 2]);
+```
+
+> Note: The formatter component is designed to format values to be displayed for the end user. If you want
+> to convert user input into machine readable format, or just format a date in a machine readable format,
+> the formatter is not the right tool for that.
+> To convert user input for date and number values you may use [[yii\validators\DateValidator]] and [[yii\validators\NumberValidator]]
+> respectively. For simple conversion between machine readable date and time formats,
+> the PHP [date()](http://php.net/manual/en/function.date.php)-function is enough.
+
+## Configuring Formatter
+
+You may customize the formatting rules by configuring the `formatter` component in the [application configuration](concept-configurations.md#application-configurations).
+For example,
+
+```php
+return [
+ 'components' => [
+ 'formatter' => [
+ 'dateFormat' => 'dd.MM.yyyy',
+ 'decimalSeparator' => ',',
+ 'thousandSeparator' => ' ',
+ 'currencyCode' => 'EUR',
+ ],
+ ],
+];
+```
+
+Please refer to [[yii\i18n\Formatter]] for the properties that may be configured.
+
+
+## Formatting Date and Time Values
+
+The formatter supports the following output formats that are related with date and time:
+
+- [[yii\i18n\Formatter::asDate()|date]]: the value is formatted as a date, e.g. `January 01, 2014`.
+- [[yii\i18n\Formatter::asTime()|time]]: the value is formatted as a time, e.g. `14:23`.
+- [[yii\i18n\Formatter::asDatetime()|datetime]]: the value is formatted as date and time, e.g. `January 01, 2014 14:23`.
+- [[yii\i18n\Formatter::asTimestamp()|timestamp]]: the value is formatted as a [unix timestamp](http://en.wikipedia.org/wiki/Unix_time), e.g. `1412609982`.
+- [[yii\i18n\Formatter::asRelativeTime()|relativeTime]]: the value is formatted as the time interval between a date
+ and now in human readable form e.g. `1 hour ago`.
+- [[yii\i18n\Formatter::asDuration()|duration]]: the value is formatted as a duration in human readable format. e.g. `1 day, 2 minutes`.
+
+The default date and time formats used for the [[yii\i18n\Formatter::asDate()|date]], [[yii\i18n\Formatter::asTime()|time]],
+and [[yii\i18n\Formatter::asDatetime()|datetime]] methods can be customized globally by configuring
+[[yii\i18n\Formatter::dateFormat|dateFormat]], [[yii\i18n\Formatter::timeFormat|timeFormat]], and
+[[yii\i18n\Formatter::datetimeFormat|datetimeFormat]].
+
+You can specify date and time formats using the [ICU syntax](http://userguide.icu-project.org/formatparse/datetime).
+You can also use the [PHP date() syntax](http://php.net/manual/en/function.date.php) with a prefix `php:` to differentiate
+it from ICU syntax. For example,
+>>>>>>> master
```php
// ICU format
echo Yii::$app->formatter->asDate('now', 'yyyy-MM-dd'); // 2014-10-06
+<<<<<<< HEAD
+=======
+
+>>>>>>> master
// PHP date()-format
echo Yii::$app->formatter->asDate('now', 'php:Y-m-d'); // 2014-10-06
```
+<<<<<<< HEAD
### Time zones
When formatting date and time values, Yii will convert them to the [[yii\i18n\Formatter::timeZone|configured time zone]].
@@ -161,6 +259,71 @@ For more advanced configuration, [[yii\i18n\Formatter::numberFormatterOptions]]
can be used to configure the internally used [NumberFormatter class](http://php.net/manual/en/class.numberformatter.php)
For example, to adjust the maximum and minimum value of fraction digits, you can configure [[yii\i18n\Formatter::numberFormatterOptions]] property like the following:
+=======
+When working with applications that need to support multiple languages, you often need to specify different date
+and time formats for different locales. To simplify this task, you may use format shortcuts (e.g. `long`, `short`), instead.
+The formatter will turn a format shortcut into an appropriate format according to the currently active [[yii\i18n\Formatter::locale|locale]].
+The following format shortcuts are supported (the examples assume `en_GB` is the active locale):
+
+- `short`: will output `06/10/2014` for date and `15:58` for time;
+- `medium`: will output `6 Oct 2014` and `15:58:42`;
+- `long`: will output `6 October 2014` and `15:58:42 GMT`;
+- `full`: will output `Monday, 6 October 2014` and `15:58:42 GMT`.
+
+Since version 2.0.7 it is also possible to format dates in different calendar systems.
+Please refer to the API documentation of the formatters [[yii\i18n\Formatter::$calendar|$calendar]]-property on how to set a different calendar.
+
+
+### Time Zones
+
+When formatting date and time values, Yii will convert them to the target [[yii\i18n\Formatter::timeZone|time zone]].
+The value being formatted is assumed to be in UTC, unless a time zone is explicitly given or you have configured
+[[yii\i18n\Formatter::defaultTimeZone]].
+
+In the following examples, we assume the target [[yii\i18n\Formatter::timeZone|time zone]] is set as `Europe/Berlin`.
+
+```php
+// formatting a UNIX timestamp as a time
+echo Yii::$app->formatter->asTime(1412599260); // 14:41:00
+
+// formatting a datetime string (in UTC) as a time
+echo Yii::$app->formatter->asTime('2014-10-06 12:41:00'); // 14:41:00
+
+// formatting a datetime string (in CEST) as a time
+echo Yii::$app->formatter->asTime('2014-10-06 14:41:00 CEST'); // 14:41:00
+```
+
+> Note: As time zones are subject to rules made by the governments around the world and may change frequently, it is
+> likely that you do not have the latest information in the time zone database installed on your system.
+> You may refer to the [ICU manual](http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data)
+> for details on updating the time zone database. Please also read
+> [Setting up your PHP environment for internationalization](tutorial-i18n.md#setup-environment).
+
+
+## Formatting Numbers
+
+The formatter supports the following output formats that are related with numbers:
+
+- [[yii\i18n\Formatter::asInteger()|integer]]: the value is formatted as an integer e.g. `42`.
+- [[yii\i18n\Formatter::asDecimal()|decimal]]: the value is formatted as a decimal number considering decimal and thousand
+ separators e.g. `2,542.123` or `2.542,123`.
+- [[yii\i18n\Formatter::asPercent()|percent]]: the value is formatted as a percent number e.g. `42%`.
+- [[yii\i18n\Formatter::asScientific()|scientific]]: the value is formatted as a number in scientific format e.g. `4.2E4`.
+- [[yii\i18n\Formatter::asCurrency()|currency]]: the value is formatted as a currency value e.g. `£420.00`.
+ Note that for this function to work properly, the locale needs to include a country part e.g. `en_GB` or `en_US` because language only
+ would be ambiguous in this case.
+- [[yii\i18n\Formatter::asSize()|size]]: the value that is a number of bytes is formatted as a human readable size e.g. `410 kibibytes`.
+- [[yii\i18n\Formatter::asShortSize()|shortSize]]: is the short version of [[yii\i18n\Formatter::asSize()|size]], e.g. `410 KiB`.
+
+The format for number formatting can be adjusted using the [[yii\i18n\Formatter::decimalSeparator|decimalSeparator]] and
+[[yii\i18n\Formatter::thousandSeparator|thousandSeparator]], both of which take default values according to the
+active [[yii\i18n\Formatter::locale|locale]].
+
+For more advanced configuration, [[yii\i18n\Formatter::numberFormatterOptions]] and [[yii\i18n\Formatter::numberFormatterTextOptions]]
+can be used to configure the [NumberFormatter class](http://php.net/manual/en/class.numberformatter.php) used internally
+to implement the formatter. For example, to adjust the maximum and minimum value of fraction digits, you can configure
+the [[yii\i18n\Formatter::numberFormatterOptions]] property like the following:
+>>>>>>> master
```php
'numberFormatterOptions' => [
@@ -169,6 +332,7 @@ For example, to adjust the maximum and minimum value of fraction digits, you can
]
```
+<<<<<<< HEAD
Other formatters
----------------
@@ -198,3 +362,64 @@ For values that are `null` in PHP, the formatter class will print a placeholder
defaults to `(not set)` translated to the current application language. You can configure the
[[yii\i18n\Formatter::nullDisplay|nullDisplay]] property to set a custom placeholder.
If you do not want special handling for `null` values, you can set [[yii\i18n\Formatter::nullDisplay|nullDisplay]] to `null`.
+=======
+
+## Other Formats
+
+Besides date/time and number formats, Yii also supports other commonly used formats, including
+
+- [[yii\i18n\Formatter::asRaw()|raw]]: the value is outputted as is, this is a pseudo-formatter that has no effect except that
+ `null` values will be formatted using [[nullDisplay]].
+- [[yii\i18n\Formatter::asText()|text]]: the value is HTML-encoded.
+ This is the default format used by the [GridView DataColumn](output-data-widgets.md#data-column).
+- [[yii\i18n\Formatter::asNtext()|ntext]]: the value is formatted as an HTML-encoded plain text with newlines converted
+ into line breaks.
+- [[yii\i18n\Formatter::asParagraphs()|paragraphs]]: the value is formatted as HTML-encoded text paragraphs wrapped
+ into `` tags.
+- [[yii\i18n\Formatter::asHtml()|html]]: the value is purified using [[HtmlPurifier]] to avoid XSS attacks. You can
+ pass additional options such as `['html', ['Attr.AllowedFrameTargets' => ['_blank']]]`.
+- [[yii\i18n\Formatter::asEmail()|email]]: the value is formatted as a `mailto`-link.
+- [[yii\i18n\Formatter::asImage()|image]]: the value is formatted as an image tag.
+- [[yii\i18n\Formatter::asUrl()|url]]: the value is formatted as a hyperlink.
+- [[yii\i18n\Formatter::asBoolean()|boolean]]: the value is formatted as a boolean. By default `true` is rendered
+ as `Yes` and `false` as `No`, translated to the current application language. You can adjust this by configuring
+ the [[yii\i18n\Formatter::booleanFormat]] property.
+
+
+## Null Values
+
+Null values are specially formatted. Instead of displaying an empty string, the formatter will convert it into a
+preset string which defaults to `(not set)` translated into the current application language. You can configure the
+[[yii\i18n\Formatter::nullDisplay|nullDisplay]] property to customize this string.
+
+
+## Localizing Data Format
+
+As aforementioned, the formatter may use the currently active [[yii\i18n\Formatter::locale|locale]] to determine how
+to format a value that is suitable in the target country/region. For example, the same date value may be formatted
+differently for different locales:
+
+```php
+Yii::$app->formatter->locale = 'en-US';
+echo Yii::$app->formatter->asDate('2014-01-01'); // output: January 1, 2014
+
+Yii::$app->formatter->locale = 'de-DE';
+echo Yii::$app->formatter->asDate('2014-01-01'); // output: 1. Januar 2014
+
+Yii::$app->formatter->locale = 'ru-RU';
+echo Yii::$app->formatter->asDate('2014-01-01'); // output: 1 января 2014 г.
+```
+
+By default, the currently active [[yii\i18n\Formatter::locale|locale]] is determined by the value of
+[[yii\base\Application::language]]. You may override it by setting the [[yii\i18n\Formatter::locale]] property explicitly.
+
+> Note: The Yii formatter relies on the [PHP intl extension](http://php.net/manual/en/book.intl.php) to support
+> localized data formatting. Because different versions of the ICU library compiled with PHP may cause different
+> formatting results, it is recommended that you use the same ICU version for all your environments. For more details,
+> please refer to [Setting up your PHP environment for internationalization](tutorial-i18n.md#setup-environment).
+>
+> If the intl extension is not installed, the data will not be localized.
+>
+> Note that for date values that are before year 1901 or after 2038, they will not be localized on 32-bit systems, even
+> if the intl extension is installed. This is because in this case ICU is using 32-bit UNIX timestamps to date values.
+>>>>>>> master
diff --git a/docs/guide/output-pagination.md b/docs/guide/output-pagination.md
index f4cf209953..8670a63800 100644
--- a/docs/guide/output-pagination.md
+++ b/docs/guide/output-pagination.md
@@ -1,6 +1,7 @@
Pagination
==========
+<<<<<<< HEAD
<<<<<<< HEAD
When there's too much data to be displayed on a single page at once it's often divided into
parts each containing some data items and displayed one part at a time. Such parts are called
@@ -11,39 +12,59 @@ pagination is already sorted out for you automatically. If not, you need to crea
object, fill it with data such as [[\yii\data\Pagination::$totalCount|total item count]],
[[\yii\data\Pagination::$pageSize|page size]] and [[\yii\data\Pagination::$page|current page]], apply
it to the query and then feed it to [[\yii\widgets\LinkPager|link pager]].
+=======
+When there are too much data to be displayed on a single page, a common strategy is to display them in multiple
+pages and on each page only display a small portion of the data. This strategy is known as *pagination*.
+>>>>>>> master
+Yii uses a [[yii\data\Pagination]] object to represent the information about a pagination scheme. In particular,
-First of all in controller action we're creating pagination object and filling it with data:
+* [[yii\data\Pagination::$totalCount|total count]] specifies the total number of data items. Note that this
+ is usually much more than the number of data items needed to display on a single page.
+* [[yii\data\Pagination::$pageSize|page size]] specifies how many data items each page contains. The default
+ value is 20.
+* [[yii\data\Pagination::$page|current page]] gives the current page number (zero-based). The default value
+ value is 0, meaning the first page.
+
+With a fully specified [[yii\data\Pagination]] object, you can retrieve and display data partially. For example,
+if you are fetching data from a database, you can specify the `OFFSET` and `LIMIT` clause of the DB query with
+the corresponding values provided by the pagination. Below is an example,
```php
-function actionIndex()
-{
- $query = Article::find()->where(['status' => 1]);
- $countQuery = clone $query;
- $pages = new Pagination(['totalCount' => $countQuery->count()]);
- $models = $query->offset($pages->offset)
- ->limit($pages->limit)
- ->all();
+use yii\data\Pagination;
- return $this->render('index', [
- 'models' => $models,
- 'pages' => $pages,
- ]);
-}
+// build a DB query to get all articles with status = 1
+$query = Article::find()->where(['status' => 1]);
+
+// get the total number of articles (but do not fetch the article data yet)
+$count = $query->count();
+
+// create a pagination object with the total count
+$pagination = new Pagination(['totalCount' => $count]);
+
+// limit the query using the pagination and retrieve the articles
+$articles = $query->offset($pagination->offset)
+ ->limit($pagination->limit)
+ ->all();
```
-Then in a view we're outputting models for the current page and passing pagination object to the link pager:
+Which page of articles will be returned in the above example? It depends on whether a query parameter named `page`
+is given. By default, the pagination will attempt to set the [[yii\data\Pagination::$page|current page]] to be
+the value of the `page` parameter. If the parameter is not provided, then it will default to 0.
+
+To facilitate building the UI element that supports pagination, Yii provides the [[yii\widgets\LinkPager]] widget
+that displays a list of page buttons upon which users can click to indicate which page of data should be displayed.
+The widget takes a pagination object so that it knows what is the current page and how many page buttons should
+be displayed. For example,
```php
-foreach ($models as $model) {
- // display $model here
-}
+use yii\widgets\LinkPager;
-// display pagination
echo LinkPager::widget([
- 'pagination' => $pages,
+ 'pagination' => $pagination,
]);
```
+<<<<<<< HEAD
=======
When there are too much data to be displayed on a single page, a common strategy is to display them in multiple
pages and on each page only display a small portion of the data. This strategy is known as *pagination*.
@@ -95,6 +116,8 @@ echo LinkPager::widget([
'pagination' => $pagination,
]);
```
+=======
+>>>>>>> master
If you want to build UI element manually, you may use [[yii\data\Pagination::createUrl()]] to create URLs that
would lead to different pages. The method requires a page parameter and will create a properly formatted URL
@@ -105,13 +128,23 @@ containing the page parameter. For example,
// If you do not specify this, the currently requested route will be used
$pagination->route = 'article/index';
+<<<<<<< HEAD
// displays: /index.php?r=article/index&page=100
echo $pagination->createUrl(100);
// displays: /index.php?r=article/index&page=101
+=======
+// displays: /index.php?r=article%2Findex&page=100
+echo $pagination->createUrl(100);
+
+// displays: /index.php?r=article%2Findex&page=101
+>>>>>>> master
echo $pagination->createUrl(101);
```
> Tip: You can customize the name of the `page` query parameter by configuring the
[[yii\data\Pagination::pageParam|pageParam]] property when creating the pagination object.
+<<<<<<< HEAD
>>>>>>> yiichina/master
+=======
+>>>>>>> master
diff --git a/docs/guide/output-sorting.md b/docs/guide/output-sorting.md
index 6bf4fa142b..ad072e666d 100644
--- a/docs/guide/output-sorting.md
+++ b/docs/guide/output-sorting.md
@@ -1,52 +1,98 @@
Sorting
=======
+<<<<<<< HEAD
<<<<<<< HEAD
Sometimes the data that is to be displayed should be sorted according to one or several attributes. If you are using
a [data provider](output-data-providers.md) with one of the [data widgets](output-data-widgets.md), sorting is
handled for you automatically. If not, you should create a [[yii\data\Sort]] instance, configure it and
apply it to the query. It can also be passed to the view, where it can be used to create links to sort by certain attributes.
+=======
+When displaying multiple rows of data, it is often needed that the data be sorted according to some columns
+specified by end users. Yii uses a [[yii\data\Sort]] object to represent the information about a sorting schema.
+In particular,
+>>>>>>> master
-A typical usage example is as follows,
+* [[yii\data\Sort::$attributes|attributes]] specifies the *attributes* by which the data can be sorted.
+ An attribute can be as simple as a [model attribute](structure-models.md#attributes). It can also be a composite
+ one by combining multiple model attributes or DB columns. More details will be given in the following.
+* [[yii\data\Sort::$attributeOrders|attributeOrders]] gives the currently requested ordering directions for
+ each attribute.
+* [[yii\data\Sort::$orders|orders]] gives the ordering directions in terms of the low-level columns.
+
+To use [[yii\data\Sort]], first declare which attributes can be sorted. Then retrieve the currently requested
+ordering information from [[yii\data\Sort::$attributeOrders|attributeOrders]] or [[yii\data\Sort::$orders|orders]]
+and use them to customize the data query. For example,
```php
-function actionIndex()
-{
- $sort = new Sort([
- 'attributes' => [
- 'age',
- 'name' => [
- 'asc' => ['first_name' => SORT_ASC, 'last_name' => SORT_ASC],
- 'desc' => ['first_name' => SORT_DESC, 'last_name' => SORT_DESC],
- 'default' => SORT_DESC,
- 'label' => 'Name',
- ],
+use yii\data\Sort;
+
+$sort = new Sort([
+ 'attributes' => [
+ 'age',
+ 'name' => [
+ 'asc' => ['first_name' => SORT_ASC, 'last_name' => SORT_ASC],
+ 'desc' => ['first_name' => SORT_DESC, 'last_name' => SORT_DESC],
+ 'default' => SORT_DESC,
+ 'label' => 'Name',
],
- ]);
+ ],
+]);
- $models = Article::find()
- ->where(['status' => 1])
- ->orderBy($sort->orders)
- ->all();
-
- return $this->render('index', [
- 'models' => $models,
- 'sort' => $sort,
- ]);
-}
+$articles = Article::find()
+ ->where(['status' => 1])
+ ->orderBy($sort->orders)
+ ->all();
```
-In the view:
+In the above example, two attributes are declared for the [[yii\data\Sort|Sort]] object: `age` and `name`.
+
+The `age` attribute is a *simple* attribute corresponding to the `age` attribute of the `Article` Active Record class.
+It is equivalent to the following declaration:
```php
-// display links leading to sort actions
+'age' => [
+ 'asc' => ['age' => SORT_ASC],
+ 'desc' => ['age' => SORT_DESC],
+ 'default' => SORT_ASC,
+ 'label' => Inflector::camel2words('age'),
+]
+```
+
+The `name` attribute is a *composite* attribute defined by `first_name` and `last_name` of `Article`. It is declared
+using the following array structure:
+
+- The `asc` and `desc` elements specify how to sort by the attribute in ascending and descending directions, respectively.
+ Their values represent the actual columns and the directions by which the data should be sorted by. You can specify
+ one or multiple columns to indicate simple ordering or composite ordering.
+- The `default` element specifies the direction by which the attribute should be sorted when initially requested.
+ It defaults to ascending order, meaning if it is not sorted before and you request to sort by this attribute,
+ the data will be sorted by this attribute in ascending order.
+- The `label` element specifies what label should be used when calling [[yii\data\Sort::link()]] to create a sort link.
+ If not set, [[yii\helpers\Inflector::camel2words()]] will be called to generate a label from the attribute name.
+ Note that it will not be HTML-encoded.
+
+> Info: You can directly feed the value of [[yii\data\Sort::$orders|orders]] to the database query to build
+ its `ORDER BY` clause. Do not use [[yii\data\Sort::$attributeOrders|attributeOrders]] because some of the
+ attributes may be composite and cannot be recognized by the database query.
+
+You can call [[yii\data\Sort::link()]] to generate a hyperlink upon which end users can click to request sorting
+the data by the specified attribute. You may also call [[yii\data\Sort::createUrl()]] to create a sortable URL.
+For example,
+
+```php
+// specifies the route that the URL to be created should use
+// If you do not specify this, the currently requested route will be used
+$sort->route = 'article/index';
+
+// display links leading to sort by name and age, respectively
echo $sort->link('name') . ' | ' . $sort->link('age');
-foreach ($models as $model) {
- // display $model here
-}
+// displays: /index.php?r=article%2Findex&sort=age
+echo $sort->createUrl('age');
```
+<<<<<<< HEAD
In the above, we declare two attributes that support sorting: `name` and `age`.
We pass the sort information to the Article query so that the query results are
sorted by the orders specified by the Sort object. In the view, we show two hyperlinks
@@ -143,3 +189,8 @@ echo $sort->createUrl('age');
You may specify a default ordering via [[yii\data\Sort::defaultOrder]] when the query parameter is not present.
You may also customize the name of the query parameter by configuring the [[yii\data\Sort::sortParam|sortParam]] property.
>>>>>>> yiichina/master
+=======
+[[yii\data\Sort]] checks the `sort` query parameter to determine which attributes are being requested for sorting.
+You may specify a default ordering via [[yii\data\Sort::defaultOrder]] when the query parameter is not present.
+You may also customize the name of the query parameter by configuring the [[yii\data\Sort::sortParam|sortParam]] property.
+>>>>>>> master
diff --git a/docs/guide/output-theming.md b/docs/guide/output-theming.md
index 675b40d100..701181888a 100644
--- a/docs/guide/output-theming.md
+++ b/docs/guide/output-theming.md
@@ -1,6 +1,7 @@
Theming
=======
+<<<<<<< HEAD
<<<<<<< HEAD
> Note: This section is under development.
@@ -16,80 +17,93 @@ Configuring a theme
Theme configuration is specified via the `view` component of the application. In order to set up a theme to work with basic
application views, the following should be in your application config file:
+=======
+Theming is a way to replace a set of [views](structure-views.md) with another without the need of touching
+the original view rendering code. You can use theming to systematically change the look and feel of an application.
+
+To use theming, you should configure the [[yii\base\View::theme|theme]] property of the `view` application component.
+The property configures a [[yii\base\Theme]] object which governs how view files are being replaced. You should
+mainly specify the following properties of [[yii\base\Theme]]:
+
+- [[yii\base\Theme::basePath]]: specifies the base directory that contains the themed resources (CSS, JS, images, etc.)
+- [[yii\base\Theme::baseUrl]]: specifies the base URL of the themed resources.
+- [[yii\base\Theme::pathMap]]: specifies the replacement rules of view files. More details will be given in the following
+ subsections.
+
+For example, if you call `$this->render('about')` in `SiteController`, you will be rendering the view file
+`@app/views/site/about.php`. However, if you enable theming in the following application configuration,
+the view file `@app/themes/basic/site/about.php` will be rendered, instead.
+>>>>>>> master
```php
-'components' => [
- 'view' => [
- 'theme' => [
- 'pathMap' => ['@app/views' => '@app/themes/basic'],
- 'baseUrl' => '@web/themes/basic',
- ],
- ],
-],
-```
-
-In the above, `pathMap` defines a map of original paths to themed paths while `baseUrl` defines the base URL for
-resources referenced by theme files.
-
-In our case `pathMap` is `['@app/views' => '@app/themes/basic']`. That means that every view in `@app/views` will be
-first searched under `@app/themes/basic` and if a view exists in the theme directory it will be used instead of the
-original view.
-
-For example, with a configuration above a themed version of a view file `@app/views/site/index.php` will be
-`@app/themes/basic/site/index.php`. It basically replaces `@app/views` in `@app/views/site/index.php` with
-`@app/themes/basic`.
-
-In order to configure theme runtime you can use the following code before rendering a view. Typically it will be
-placed in controller:
-
-```php
-$this->getView()->theme = Yii::createObject([
- 'class' => '\yii\base\Theme',
- 'pathMap' => ['@app/views' => '@app/themes/basic'],
- 'baseUrl' => '@web/themes/basic',
-]);
-```
-
-### Theming modules
-
-In order to theme modules, `pathMap` may look like the following:
-
-```php
-'components' => [
- 'view' => [
- 'theme' => [
- 'pathMap' => [
- '@app/views' => '@app/themes/basic',
- '@app/modules' => '@app/themes/basic/modules', // <-- !!!
+return [
+ 'components' => [
+ 'view' => [
+ 'theme' => [
+ 'basePath' => '@app/themes/basic',
+ 'baseUrl' => '@web/themes/basic',
+ 'pathMap' => [
+ '@app/views' => '@app/themes/basic',
+ ],
],
],
],
-],
+];
```
-It will allow you to theme `@app/modules/blog/views/comment/index.php` with `@app/themes/basic/modules/blog/views/comment/index.php`.
+> Info: Path aliases are supported by themes. When doing view replacement, path aliases will be turned into
+ the actual file paths or URLs.
-### Theming widgets
-
-In order to theme a widget view located at `@app/widgets/currency/views/index.php`, you need the following configuration for
-the view component theme:
+You can access the [[yii\base\Theme]] object through the [[yii\base\View::theme]] property. For example,
+in a view file, you can write the following code because `$this` refers to the view object:
```php
-'components' => [
- 'view' => [
- 'theme' => [
- 'pathMap' => ['@app/widgets' => '@app/themes/basic/widgets'],
- ],
- ],
+$theme = $this->theme;
+
+// returns: $theme->baseUrl . '/img/logo.gif'
+$url = $theme->getUrl('img/logo.gif');
+
+// returns: $theme->basePath . '/img/logo.gif'
+$file = $theme->getPath('img/logo.gif');
+```
+
+The [[yii\base\Theme::pathMap]] property governs how view files should be replaced. It takes an array of
+key-value pairs, where the keys are the original view paths to be replaced and the values are the corresponding
+themed view paths. The replacement is based on partial match: if a view path starts with any key in
+the [[yii\base\Theme::pathMap|pathMap]] array, that matching part will be replaced with the corresponding array value.
+Using the above configuration example, because `@app/views/site/about.php` partially matches the key
+`@app/views`, it will be replaced as `@app/themes/basic/site/about.php`.
+
+
+## Theming Modules
+
+In order to theme modules, [[yii\base\Theme::pathMap]] can be configured like the following:
+
+```php
+'pathMap' => [
+ '@app/views' => '@app/themes/basic',
+ '@app/modules' => '@app/themes/basic/modules', // <-- !!!
],
```
-With the configuration above you can create a themed version of the `@app/widgets/currency/index.php` view in
-`@app/themes/basic/widgets/currency/index.php`.
+It will allow you to theme `@app/modules/blog/views/comment/index.php` into `@app/themes/basic/modules/blog/views/comment/index.php`.
-Using multiple paths
---------------------
+## Theming Widgets
+
+In order to theme widgets, you can configure [[yii\base\Theme::pathMap]] in the following way:
+
+```php
+'pathMap' => [
+ '@app/views' => '@app/themes/basic',
+ '@app/widgets' => '@app/themes/basic/widgets', // <-- !!!
+],
+```
+
+This will allow you to theme `@app/widgets/currency/views/index.php` into `@app/themes/basic/widgets/currency/index.php`.
+
+
+<<<<<<< HEAD
It is possible to map a single path to multiple theme paths. For example,
=======
Theming is a way to replace a set of [views](structure-views.md) with another without the need of touching
@@ -176,12 +190,17 @@ In order to theme widgets, you can configure [[yii\base\Theme::pathMap]] in the
This will allow you to theme `@app/widgets/currency/views/index.php` into `@app/themes/basic/widgets/currency/index.php`.
+=======
+>>>>>>> master
## Theme Inheritance
Sometimes you may want to define a basic theme which contains a basic look and feel of the application, and then
based on the current holiday, you may want to vary the look and feel slightly. You can achieve this goal using
theme inheritance which is done by mapping a single view path to multiple targets. For example,
+<<<<<<< HEAD
>>>>>>> yiichina/master
+=======
+>>>>>>> master
```php
'pathMap' => [
@@ -192,14 +211,20 @@ theme inheritance which is done by mapping a single view path to multiple target
]
```
+<<<<<<< HEAD
<<<<<<< HEAD
In this case, first the view will be searched for in `@app/themes/christmas/site/index.php` then if it's not found it will check
`@app/themes/basic/site/index.php`. If there's no view there as well, then the application view will be used.
This ability is especially useful if you want to temporarily or conditionally override some views.
=======
+=======
+>>>>>>> master
In this case, the view `@app/views/site/index.php` would be themed as either `@app/themes/christmas/site/index.php`
or `@app/themes/basic/site/index.php`, depending on which themed file exists. If both themed files exist, the first
one will take precedence. In practice, you would keep most themed view files in `@app/themes/basic` and customize
some of them in `@app/themes/christmas`.
+<<<<<<< HEAD
>>>>>>> yiichina/master
+=======
+>>>>>>> master
diff --git a/docs/guide/rest-authentication.md b/docs/guide/rest-authentication.md
index 6145f21748..4e6b083e83 100644
--- a/docs/guide/rest-authentication.md
+++ b/docs/guide/rest-authentication.md
@@ -25,11 +25,15 @@ Yii supports all of the above authentication methods. You can also easily create
To enable authentication for your APIs, do the following steps:
+<<<<<<< HEAD
<<<<<<< HEAD
1. Configure the `user` application component:
=======
1. Configure the `user` [application component](structure-application-components.md):
>>>>>>> yiichina/master
+=======
+1. Configure the `user` [application component](structure-application-components.md):
+>>>>>>> master
- Set the [[yii\web\User::enableSession|enableSession]] property to be `false`.
- Set the [[yii\web\User::loginUrl|loginUrl]] property to be `null` to show a HTTP 403 error instead of redirecting to the login page.
2. Specify which authentication methods you plan to use by configuring the `authenticator` behavior
@@ -41,15 +45,16 @@ is false, the user authentication status will NOT be persisted across requests u
will be performed for every request, which is accomplished by Step 2 and 3.
> Tip: You may configure [[yii\web\User::enableSession|enableSession]] of the `user` application component
- in application configurations if you are developing RESTful APIs in terms of an application. If you develop
- RESTful APIs as a module, you may put the following line in the module's `init()` method, like the following:
+> in application configurations if you are developing RESTful APIs in terms of an application. If you develop
+> RESTful APIs as a module, you may put the following line in the module's `init()` method, like the following:
+>
> ```php
-public function init()
-{
- parent::init();
- \Yii::$app->user->enableSession = false;
-}
-```
+> public function init()
+> {
+> parent::init();
+> \Yii::$app->user->enableSession = false;
+> }
+> ```
For example, to use HTTP Basic Auth, you may configure the `authenticator` behavior as follows,
@@ -126,5 +131,5 @@ action for the requested resource. This process is called *authorization* which
the [Authorization section](security-authorization.md).
If your controllers extend from [[yii\rest\ActiveController]], you may override
-the [[yii\rest\Controller::checkAccess()|checkAccess()]] method to perform authorization check. The method
+the [[yii\rest\ActiveController::checkAccess()|checkAccess()]] method to perform authorization check. The method
will be called by the built-in actions provided by [[yii\rest\ActiveController]].
diff --git a/docs/guide/rest-controllers.md b/docs/guide/rest-controllers.md
index 518e041931..52d1673d98 100644
--- a/docs/guide/rest-controllers.md
+++ b/docs/guide/rest-controllers.md
@@ -22,7 +22,7 @@ will be described in detail in the next few sections:
[[yii\rest\ActiveController]] in addition provides the following features:
* A set of commonly needed actions: `index`, `view`, `create`, `update`, `delete`, `options`;
-* User authorization in regarding to the requested action and resource.
+* User authorization in regard to the requested action and resource.
## Creating Controller Classes
@@ -53,7 +53,7 @@ In particular, the following filters will be executed in the order they are list
* [[yii\filters\ContentNegotiator|contentNegotiator]]: supports content negotiation, to be explained in
the [Response Formatting](rest-response-formatting.md) section;
* [[yii\filters\VerbFilter|verbFilter]]: supports HTTP method validation;
-* [[yii\filters\AuthMethod|authenticator]]: supports user authentication, to be explained in
+* [[yii\filters\auth\AuthMethod|authenticator]]: supports user authentication, to be explained in
the [Authentication](rest-authentication.md) section;
* [[yii\filters\RateLimiter|rateLimiter]]: supports rate limiting, to be explained in
the [Rate Limiting](rest-rate-limiting.md) section.
@@ -79,7 +79,7 @@ public function behaviors()
## Extending `ActiveController`
If your controller class extends from [[yii\rest\ActiveController]], you should set
-its [[yii\rest\ActiveController::modelClass||modelClass]] property to be the name of the resource class
+its [[yii\rest\ActiveController::modelClass|modelClass]] property to be the name of the resource class
that you plan to serve through this controller. The class must extend from [[yii\db\ActiveRecord]].
diff --git a/docs/guide/rest-error-handling.md b/docs/guide/rest-error-handling.md
index 9618c588e1..b984536dc2 100644
--- a/docs/guide/rest-error-handling.md
+++ b/docs/guide/rest-error-handling.md
@@ -77,11 +77,15 @@ return [
'class' => 'yii\web\Response',
'on beforeSend' => function ($event) {
$response = $event->sender;
+<<<<<<< HEAD
<<<<<<< HEAD
if ($response->data !== null && !empty(Yii::$app->request->get('suppress_response_code'))) {
=======
if ($response->data !== null && Yii::$app->request->get('suppress_response_code')) {
>>>>>>> yiichina/master
+=======
+ if ($response->data !== null && Yii::$app->request->get('suppress_response_code')) {
+>>>>>>> master
$response->data = [
'success' => $response->isSuccessful,
'data' => $response->data,
diff --git a/docs/guide/rest-quick-start.md b/docs/guide/rest-quick-start.md
index 5e1f835833..3387f71c61 100644
--- a/docs/guide/rest-quick-start.md
+++ b/docs/guide/rest-quick-start.md
@@ -20,19 +20,27 @@ In the following, we use an example to illustrate how you can build a set of RES
Assume you want to expose the user data via RESTful APIs. The user data are stored in the `user` DB table,
<<<<<<< HEAD
+<<<<<<< HEAD
and you have already created the [[yii\db\ActiveRecord|ActiveRecord]] class `app\models\User` to access the user data.
=======
and you have already created the [active record](db-active-record.md) class `app\models\User` to access the user data.
>>>>>>> yiichina/master
+=======
+and you have already created the [active record](db-active-record.md) class `app\models\User` to access the user data.
+>>>>>>> master
## Creating a Controller
+<<<<<<< HEAD
<<<<<<< HEAD
First, create a controller class `app\controllers\UserController` as follows,
=======
First, create a [controller](structure-controllers.md) class `app\controllers\UserController` as follows,
>>>>>>> yiichina/master
+=======
+First, create a [controller](structure-controllers.md) class `app\controllers\UserController` as follows,
+>>>>>>> master
```php
namespace app\controllers;
@@ -45,6 +53,7 @@ class UserController extends ActiveController
}
```
+<<<<<<< HEAD
<<<<<<< HEAD
The controller class extends from [[yii\rest\ActiveController]]. By specifying [[yii\rest\ActiveController::modelClass|modelClass]]
as `app\models\User`, the controller knows what model can be used for fetching and manipulating data.
@@ -53,6 +62,11 @@ The controller class extends from [[yii\rest\ActiveController]], which implement
By specifying [[yii\rest\ActiveController::modelClass|modelClass]]
as `app\models\User`, the controller knows which model can be used for fetching and manipulating data.
>>>>>>> yiichina/master
+=======
+The controller class extends from [[yii\rest\ActiveController]], which implements a common set of RESTful actions.
+By specifying [[yii\rest\ActiveController::modelClass|modelClass]]
+as `app\models\User`, the controller knows which model can be used for fetching and manipulating data.
+>>>>>>> master
## Configuring URL Rules
@@ -78,10 +92,14 @@ can be accessed and manipulated with pretty URLs and meaningful HTTP verbs.
To let the API accept input data in JSON format, configure the [[yii\web\Request::$parsers|parsers]] property of
<<<<<<< HEAD
+<<<<<<< HEAD
the `request` application component to use the [[yii\web\JsonParser]] for JSON input:
=======
the `request` [application component](structure-application-components.md) to use the [[yii\web\JsonParser]] for JSON input:
>>>>>>> yiichina/master
+=======
+the `request` [application component](structure-application-components.md) to use the [[yii\web\JsonParser]] for JSON input:
+>>>>>>> master
```php
'request' => [
@@ -202,7 +220,7 @@ For example, the URL `http://localhost/users?fields=id,email` will only return t
> Info: You may have noticed that the result of `http://localhost/users` includes some sensitive fields,
> such as `password_hash`, `auth_key`. You certainly do not want these to appear in your API result.
-> You can and should filter out these fields as described in the [Response Formatting](rest-response-formatting.md) section.
+> You can and should filter out these fields as described in the [Resources](rest-resources.md) section.
## Summary
diff --git a/docs/guide/rest-rate-limiting.md b/docs/guide/rest-rate-limiting.md
index b3f1671643..f076645a61 100644
--- a/docs/guide/rest-rate-limiting.md
+++ b/docs/guide/rest-rate-limiting.md
@@ -13,10 +13,32 @@ This interface requires implementation of three methods:
when the rate limit was last checked.
* `saveAllowance()`: saves both the number of remaining requests allowed and the current UNIX timestamp.
-You may want to use two columns in the user table to record the allowance and timestamp information. With those defined, then `loadAllowance()` and `saveAllowance()` can be implemented to read and save the values
+You may want to use two columns in the user table to record the allowance and timestamp information. With those defined,
+then `loadAllowance()` and `saveAllowance()` can be implemented to read and save the values
of the two columns corresponding to the current authenticated user. To improve performance, you may also
consider storing these pieces of information in a cache or NoSQL storage.
+Implementation in the `User` model could look like the following:
+
+```php
+public function getRateLimit($request, $action)
+{
+ return [$this->rateLimit, 1]; // $rateLimit requests per second
+}
+
+public function loadAllowance($request, $action)
+{
+ return [$this->allowance, $this->allowance_updated_at];
+}
+
+public function saveAllowance($request, $action, $allowance, $timestamp)
+{
+ $this->allowance = $allowance;
+ $this->allowance_updated_at = $timestamp;
+ $this->save();
+}
+```
+
Once the identity class implements the required interface, Yii will automatically use [[yii\filters\RateLimiter]]
configured as an action filter for [[yii\rest\Controller]] to perform rate limiting check. The rate limiter
will throw a [[yii\web\TooManyRequestsHttpException]] when the rate limit is exceeded.
diff --git a/docs/guide/rest-response-formatting.md b/docs/guide/rest-response-formatting.md
index db58b35511..b99f1bd085 100644
--- a/docs/guide/rest-response-formatting.md
+++ b/docs/guide/rest-response-formatting.md
@@ -10,12 +10,17 @@ with response formatting:
This is done by [[yii\rest\Serializer]].
3. Convert arrays into a string in the format as determined by the content negotiation step. This is
done by [[yii\web\ResponseFormatterInterface|response formatters]] registered with
+<<<<<<< HEAD
<<<<<<< HEAD
the [[yii\web\Response::formatters|response]] application component.
=======
the [[yii\web\Response::formatters|formatters]] property of the
`response` [application component](structure-application-components.md).
>>>>>>> yiichina/master
+=======
+ the [[yii\web\Response::formatters|formatters]] property of the
+ `response` [application component](structure-application-components.md).
+>>>>>>> master
## Content Negotiation
diff --git a/docs/guide/rest-routing.md b/docs/guide/rest-routing.md
index fba6cd6971..c631864306 100644
--- a/docs/guide/rest-routing.md
+++ b/docs/guide/rest-routing.md
@@ -7,12 +7,17 @@ With resource and controller classes ready, you can access the resources using t
In practice, you usually want to enable pretty URLs and take advantage of HTTP verbs.
For example, a request `POST /users` would mean accessing the `user/create` action.
<<<<<<< HEAD
+<<<<<<< HEAD
This can be done easily by configuring the `urlManager` application component in the application
configuration like the following:
=======
This can be done easily by configuring the `urlManager` [application component](structure-application-components.md)
in the application configuration like the following:
>>>>>>> yiichina/master
+=======
+This can be done easily by configuring the `urlManager` [application component](structure-application-components.md)
+in the application configuration like the following:
+>>>>>>> master
```php
'urlManager' => [
diff --git a/docs/guide/runtime-handling-errors.md b/docs/guide/runtime-handling-errors.md
index f8ca55f03a..7bd0bef6f1 100644
--- a/docs/guide/runtime-handling-errors.md
+++ b/docs/guide/runtime-handling-errors.md
@@ -3,10 +3,14 @@ Handling Errors
Yii includes a built-in [[yii\web\ErrorHandler|error handler]] which makes error handling a much more pleasant
<<<<<<< HEAD
+<<<<<<< HEAD
experience than before. In particular, the Yii error handler does the followings to improve error handling:
=======
experience than before. In particular, the Yii error handler does the following to improve error handling:
>>>>>>> yiichina/master
+=======
+experience than before. In particular, the Yii error handler does the following to improve error handling:
+>>>>>>> master
* All non-fatal PHP errors (e.g. warnings, notices) are converted into catchable exceptions.
* Exceptions and fatal PHP errors are displayed with detailed call stack information and source code lines
@@ -148,13 +152,23 @@ the following variables if the error action is defined as [[yii\web\ErrorAction]
* `exception`: the exception object through which you can retrieve more useful information, such as HTTP status code,
error code, error call stack, etc.
+<<<<<<< HEAD
<<<<<<< HEAD
> Info: If you are using the [basic application template](start-installation.md) or the [advanced application template](tutorial-advanced-app.md),
=======
> Info: If you are using the [basic project template](start-installation.md) or the [advanced project template](https://github.com/yiisoft/yii2-app-advanced/blob/master/docs/guide/README.md),
>>>>>>> yiichina/master
+=======
+> Info: If you are using the [basic project template](start-installation.md) or the [advanced project template](https://github.com/yiisoft/yii2-app-advanced/blob/master/docs/guide/README.md),
+>>>>>>> master
the error action and the error view are already defined for you.
+> Note: If you need to redirect in an error handler, do it the following way:
+> ```php
+> Yii::$app->getResponse()->redirect($url)->send();
+> return;
+> ```
+
### Customizing Error Response Format
diff --git a/docs/guide/runtime-overview.md b/docs/guide/runtime-overview.md
index ca6d84964f..b886f140f1 100644
--- a/docs/guide/runtime-overview.md
+++ b/docs/guide/runtime-overview.md
@@ -10,10 +10,10 @@ Each time when a Yii application handles a request, it undergoes a similar workf
the [request](runtime-requests.md) application component.
4. The application creates a [controller](structure-controllers.md) instance to handle the request.
5. The controller creates an [action](structure-controllers.md) instance and performs the filters for the action.
-6. If any filter fails, the action is cancelled.
+6. If any [filter](structure-filters.md) fails, the action is cancelled.
7. If all filters pass, the action is executed.
-8. The action loads a data model, possibly from a database.
-9. The action renders a view, providing it with the data model.
+8. The action loads a data [model](structure-models.md), possibly from a database.
+9. The action renders a [view](structure-views.md), providing it with the data model.
10. The rendered result is returned to the [response](runtime-responses.md) application component.
11. The response component sends the rendered result to the user's browser.
diff --git a/docs/guide/runtime-requests.md b/docs/guide/runtime-requests.md
index ef98c1f4fa..6a877c21b4 100644
--- a/docs/guide/runtime-requests.md
+++ b/docs/guide/runtime-requests.md
@@ -66,10 +66,10 @@ For example,
```php
$request = Yii::$app->request;
-if ($request->isAjax) { // the request is an AJAX request }
-if ($request->isGet) { // the request method is GET }
-if ($request->isPost) { // the request method is POST }
-if ($request->isPut) { // the request method is PUT }
+if ($request->isAjax) { /* the request is an AJAX request */ }
+if ($request->isGet) { /* the request method is GET */ }
+if ($request->isPost) { /* the request method is POST */ }
+if ($request->isPut) { /* the request method is PUT */ }
```
## Request URLs
@@ -105,7 +105,7 @@ $headers = Yii::$app->request->headers;
// returns the Accept header value
$accept = $headers->get('Accept');
-if ($headers->has('User-Agent')) { // there is User-Agent header }
+if ($headers->has('User-Agent')) { /* there is User-Agent header */ }
```
The `request` component also provides support for quickly accessing some commonly used headers, including:
diff --git a/docs/guide/runtime-routing.md b/docs/guide/runtime-routing.md
index 417b2b313e..785590994d 100644
--- a/docs/guide/runtime-routing.md
+++ b/docs/guide/runtime-routing.md
@@ -11,10 +11,14 @@ back into the original route and query parameters.
The central piece responsible for routing and URL creation is the [[yii\web\UrlManager|URL manager]],
<<<<<<< HEAD
+<<<<<<< HEAD
which is registered as the `urlManager` application component. The [[yii\web\UrlManager|URL manager]]
=======
which is registered as the `urlManager` [application component](structure-application-components.md). The [[yii\web\UrlManager|URL manager]]
>>>>>>> yiichina/master
+=======
+which is registered as the `urlManager` [application component](structure-application-components.md). The [[yii\web\UrlManager|URL manager]]
+>>>>>>> master
provides the [[yii\web\UrlManager::parseRequest()|parseRequest()]] method to parse an incoming request into
a route and the associated query parameters and the [[yii\web\UrlManager::createUrl()|createUrl()]] method to
create a URL from a given route and its associated query parameters.
@@ -34,7 +38,7 @@ Depending on the `urlManager` configuration, the created URL may look like one o
And if the created URL is requested later, it will still be parsed back into the original route and query parameter value.
```
-/index.php?r=post/view&id=100
+/index.php?r=post%2Fview&id=100
/index.php/post/100
/posts/100
```
@@ -62,7 +66,7 @@ property of the [[yii\web\UrlManager|URL manager]] without changing any other ap
## Routing
Routing involves two steps. In the first step, the incoming request is parsed into a route and the associated
-query parameters. In the second step, a [controller action](structure-controllers.md) corresponding to the parsed route
+query parameters. In the second step, a [controller action](structure-controllers.md#actions) corresponding to the parsed route
is created to handle the request.
When using the default URL format, parsing a request into a route is as simple as getting the value of a `GET`
@@ -85,11 +89,11 @@ controller and action:
3. Check if the ID refers to a module listed in the [[yii\base\Module::modules|modules]] property of
the current module. If so, a module is created according to the configuration found in the module list,
and Step 2 will be taken to handle the next part of the route under the context of the newly created module.
-4. Treat the ID as a controller ID and create a controller object. Do the next step with the rest part of
+4. Treat the ID as a [controller ID](structure-controllers.md#controller-ids) and create a controller object. Do the next step with the rest part of
the route.
5. The controller looks for the current ID in its [[yii\base\Controller::actions()|action map]]. If found,
it creates an action according to the configuration found in the map. Otherwise, the controller will
- attempt to create an inline action which is defined by an action method corresponding to the current ID.
+ attempt to create an inline action which is defined by an action method corresponding to the current [action ID](structure-controllers.md#action-ids).
Among the above steps, if any error occurs, a [[yii\web\NotFoundHttpException]] will be thrown, indicating
the failure of the routing process.
@@ -128,6 +132,8 @@ With the above configuration, the `site/offline` action will be used to handle a
The `catchAll` property should take an array whose first element specifies a route, and
the rest of the elements (name-value pairs) specify the parameters to be [bound to the action](structure-controllers.md#action-parameters).
+> Info: Debug panel on development environment will not work when this property is enabled
+
## Creating URLs
@@ -137,19 +143,19 @@ their associated query parameters. For example,
```php
use yii\helpers\Url;
-// creates a URL to a route: /index.php?r=post/index
+// creates a URL to a route: /index.php?r=post%2Findex
echo Url::to(['post/index']);
-// creates a URL to a route with parameters: /index.php?r=post/view&id=100
+// creates a URL to a route with parameters: /index.php?r=post%2Fview&id=100
echo Url::to(['post/view', 'id' => 100]);
-// creates an anchored URL: /index.php?r=post/view&id=100#content
+// creates an anchored URL: /index.php?r=post%2Fview&id=100#content
echo Url::to(['post/view', 'id' => 100, '#' => 'content']);
-// creates an absolute URL: http://www.example.com/index.php?r=post/index
+// creates an absolute URL: http://www.example.com/index.php?r=post%2Findex
echo Url::to(['post/index'], true);
-// creates an absolute URL using the https scheme: https://www.example.com/index.php?r=post/index
+// creates an absolute URL using the https scheme: https://www.example.com/index.php?r=post%2Findex
echo Url::to(['post/index'], 'https');
```
@@ -174,19 +180,19 @@ For example, assume the current module is `admin` and the current controller is
```php
use yii\helpers\Url;
-// currently requested route: /index.php?r=admin/post/index
+// currently requested route: /index.php?r=admin%2Fpost%2Findex
echo Url::to(['']);
-// a relative route with action ID only: /index.php?r=admin/post/index
+// a relative route with action ID only: /index.php?r=admin%2Fpost%2Findex
echo Url::to(['index']);
-// a relative route: /index.php?r=admin/post/index
+// a relative route: /index.php?r=admin%2Fpost%2Findex
echo Url::to(['post/index']);
-// an absolute route: /index.php?r=post/index
+// an absolute route: /index.php?r=post%2Findex
echo Url::to(['/post/index']);
-// /index.php?r=post/index assume the alias "@posts" is defined as "/post/index"
+// /index.php?r=post%2Findex assume the alias "@posts" is defined as "/post/index"
echo Url::to(['@posts']);
```
@@ -201,7 +207,7 @@ Instead of passing an array as its first parameter, you should pass a string in
```php
use yii\helpers\Url;
-// currently requested URL: /index.php?r=admin/post/index
+// currently requested URL: /index.php?r=admin%2Fpost%2Findex
echo Url::to();
// an aliased URL: http://example.com
@@ -218,7 +224,7 @@ methods. For example,
```php
use yii\helpers\Url;
-// home page URL: /index.php?r=site/index
+// home page URL: /index.php?r=site%2Findex
echo Url::home();
// the base URL, useful if the application is deployed in a sub-folder of the Web root
diff --git a/docs/guide/runtime-sessions-cookies.md b/docs/guide/runtime-sessions-cookies.md
index d5fab498f8..abaedfb83b 100644
--- a/docs/guide/runtime-sessions-cookies.md
+++ b/docs/guide/runtime-sessions-cookies.md
@@ -230,8 +230,11 @@ $alerts = $session->getFlash('alerts');
find sometimes you are getting an array while sometimes you are getting a string, depending on the order of
the invocation of these two methods.
+<<<<<<< HEAD
<<<<<<< HEAD
=======
+=======
+>>>>>>> master
> Tip: For displaying Flash messages you can use [[yii\bootstrap\Alert|bootstrap Alert]] widget in the following way:
>
> ```php
@@ -241,7 +244,10 @@ $alerts = $session->getFlash('alerts');
> ]);
> ```
+<<<<<<< HEAD
>>>>>>> yiichina/master
+=======
+>>>>>>> master
## Cookies
@@ -250,6 +256,8 @@ maintain a collection of cookies via the property named `cookies`. The cookie co
the cookies submitted in a request, while the cookie collection in the latter represents the cookies that are to
be sent to the user.
+The part of the application dealing with request and response directly is controller. Therefore, cookies should be
+read and sent in controller.
### Reading Cookies
diff --git a/docs/guide/security-auth-clients.md b/docs/guide/security-auth-clients.md
deleted file mode 100644
index a1802cdcbd..0000000000
--- a/docs/guide/security-auth-clients.md
+++ /dev/null
@@ -1,384 +0,0 @@
-Auth Clients
-============
-
-Yii provides official extension that lets you authenticate and/or authorize using external services via consuming
-[OpenID](http://openid.net/), [OAuth](http://oauth.net/) or [OAuth2](http://oauth.net/2/).
-
-Installing extension
---------------------
-
-In order to install extension use Composer. Either run
-
-```
-composer require --prefer-dist yiisoft/yii2-authclient "*"
-```
-
-or add
-
-```json
-"yiisoft/yii2-authclient": "*"
-```
-to the `require` section of your composer.json.
-
-Configuring clients
--------------------
-
-After extension is installed you need to setup auth client collection application component:
-
-```php
-'components' => [
- 'authClientCollection' => [
- 'class' => 'yii\authclient\Collection',
- 'clients' => [
- 'google' => [
- 'class' => 'yii\authclient\clients\GoogleOpenId'
- ],
- 'facebook' => [
- 'class' => 'yii\authclient\clients\Facebook',
- 'clientId' => 'facebook_client_id',
- 'clientSecret' => 'facebook_client_secret',
- ],
- // etc.
- ],
- ]
- ...
-]
-```
-
-Out of the box the following clients are provided:
-
-- [[\yii\authclient\clients\Facebook|Facebook]].
-- [[yii\authclient\clients\GitHub|GitHub]].
-- Google (via [[yii\authclient\clients\GoogleOpenId|OpenID]] and [[yii\authclient\clients\GoogleOAuth|OAuth]]).
-- [[yii\authclient\clients\LinkedIn|LinkedIn]].
-- [[yii\authclient\clients\Live|Microsoft Live]].
-- [[yii\authclient\clients\Twitter|Twitter]].
-- [[yii\authclient\clients\VKontakte|VKontakte]].
-- Yandex (via [[yii\authclient\clients\YandexOpenId|OpenID]] and [[yii\authclient\clients\YandexOAuth|OAuth]]).
-
-Configuration for each client is a bit different. For OAuth it's required to get client ID and secret key from
-the service you're going to use. For OpenID it works out of the box in most cases.
-
-Storing authorization data
---------------------------
-
-In order to recognize the user authenticated via external service we need to store ID provided on first authentication
-and then check against it on subsequent authentications. It's not a good idea to limit login options to external
-services only since these may fail and there won't be a way for the user to log in. Instead it's better to provide
-both external authentication and good old login and password.
-
-If we're storing user information in a database the schema could be the following:
-
-```sql
-CREATE TABLE user (
- id int(11) NOT NULL AUTO_INCREMENT PRIMARY KEY,
- username varchar(255) NOT NULL,
- auth_key varchar(32) NOT NULL,
- password_hash varchar(255) NOT NULL,
- password_reset_token varchar(255),
- email varchar(255) NOT NULL,
- status smallint(6) NOT NULL DEFAULT 10,
- created_at int(11) NOT NULL,
- updated_at int(11) NOT NULL
-);
-
-CREATE TABLE auth (
- id int(11) NOT NULL AUTO_INCREMENT PRIMARY KEY,
- user_id int(11) NOT NULL,
- source string(255) NOT NULL,
- source_id string(255) NOT NULL
-);
-
-ALTER TABLE auth ADD CONSTRAINT fk-auth-user_id-user-id
-FOREIGN KEY user_id REFERENCES user(id);
-```
-
-In the SQL above `user` is a standard table that is used in advanced application template to store user
-info. Each user can authenticate using multiple external services therefore each `user` record can relate to
-multiple `auth` records. In the `auth` table `source` is the name of the auth provider used and `source_id` is
-unique user identificator that is provided by external service after successful login.
-
-Using tables created above we can generate `Auth` model. No further adjustments needed.
-
-
-Adding action to controller
----------------------------
-
-Next step is to add [[yii\authclient\AuthAction]] to a web controller. Typically `SiteController`:
-
-```php
-class SiteController extends Controller
-{
- public function actions()
- {
- return [
- 'auth' => [
- 'class' => 'yii\authclient\AuthAction',
- 'successCallback' => [$this, 'onAuthSuccess'],
- ],
- ];
- }
-
- public function onAuthSuccess($client)
- {
- $attributes = $client->getUserAttributes();
-
- /** @var Auth $auth */
- $auth = Auth::find()->where([
- 'source' => $client->getId(),
- 'source_id' => $attributes['id'],
- ])->one();
-
- if (Yii::$app->user->isGuest) {
- if ($auth) { // login
- $user = $auth->user;
- Yii::$app->user->login($user);
- } else { // signup
- if (isset($attributes['email']) && isset($attributes['username']) && User::find()->where(['email' => $attributes['email']])->exists()) {
- Yii::$app->getSession()->setFlash('error', [
- Yii::t('app', "User with the same email as in {client} account already exists but isn't linked to it. Login using email first to link it.", ['client' => $client->getTitle()]),
- ]);
- } else {
- $password = Yii::$app->security->generateRandomString(6);
- $user = new User([
- 'username' => $attributes['login'],
- 'email' => $attributes['email'],
- 'password' => $password,
- ]);
- $user->generateAuthKey();
- $user->generatePasswordResetToken();
- $transaction = $user->getDb()->beginTransaction();
- if ($user->save()) {
- $auth = new Auth([
- 'user_id' => $user->id,
- 'source' => $client->getId(),
- 'source_id' => (string)$attributes['id'],
- ]);
- if ($auth->save()) {
- $transaction->commit();
- Yii::$app->user->login($user);
- } else {
- print_r($auth->getErrors());
- }
- } else {
- print_r($user->getErrors());
- }
- }
- }
- } else { // user already logged in
- if (!$auth) { // add auth provider
- $auth = new Auth([
- 'user_id' => Yii::$app->user->id,
- 'source' => $client->getId(),
- 'source_id' => $attributes['id'],
- ]);
- $auth->save();
- }
- }
- }
-}
-```
-
-`successCallback` method is called when user was successfully authenticated via external service. Via `$client` instance
-we can retrieve information received. In our case we'd like to:
-
-- If user is guest and record found in auth then log this user in.
-- If user is guest and record not found in auth then create new user and make a record in auth table. Then log in.
-- If user is logged in and record not found in auth then try connecting additional account (save its data into auth table).
-
-Although, all clients are different they shares same basic interface [[yii\authclient\ClientInterface]],
-which governs common API.
-
-Each client has some descriptive data, which can be used for different purposes:
-
-- `id` - unique client id, which separates it from other clients, it could be used in URLs, logs etc.
-- `name` - external auth provider name, which this client is match too. Different auth clients
- can share the same name, if they refer to the same external auth provider.
- For example: clients for Google OpenID and Google OAuth have same name "google".
- This attribute can be used inside the database, CSS styles and so on.
-- `title` - user friendly name for the external auth provider, it is used to present auth client
- at the view layer.
-
-Each auth client has different auth flow, but all of them supports `getUserAttributes()` method,
-which can be invoked if authentication was successful.
-
-This method allows you to get information about external user account, such as ID, email address,
-full name, preferred language etc. Note that for each provider fields available may vary in both existence and
-names.
-
-Defining list of attributes, which external auth provider should return, depends on client type:
-
-- [[yii\authclient\OpenId]]: combination of `requiredAttributes` and `optionalAttributes`.
-- [[yii\authclient\OAuth1]] and [[yii\authclient\OAuth2]]: field `scope`, note that different
- providers use different formats for the scope.
-
-### Getting additional data via extra API calls
-
-Both [[yii\authclient\OAuth1]] and [[yii\authclient\OAuth2]] provide method `api()`, which
-can be used to access external auth provider REST API. However this method is very basic and
-it may be not enough to access full external API functionality. This method is mainly used to
-fetch the external user account data.
-
-To use API calls, you need to setup [[yii\authclient\BaseOAuth::apiBaseUrl]] according to the
-API specification. Then you can call [[yii\authclient\BaseOAuth::api()]] method:
-
-```php
-use yii\authclient\OAuth2;
-
-$client = new OAuth2;
-
-// ...
-
-$client->apiBaseUrl = 'https://www.googleapis.com/oauth2/v1';
-$userInfo = $client->api('userinfo', 'GET');
-```
-
-Adding widget to login view
----------------------------
-
-There's ready to use [[yii\authclient\widgets\AuthChoice]] widget to use in views:
-
-```php
- ['site/auth'],
- 'popupMode' => false,
-]) ?>
-```
-
-Creating your own auth clients
-------------------------------
-
-You may create your own auth client for any external auth provider, which supports
-OpenId or OAuth protocol. To do so, first of all, you need to find out which protocol is
-supported by the external auth provider, this will give you the name of the base class
-for your extension:
-
- - For OAuth 2 use [[yii\authclient\OAuth2]].
- - For OAuth 1/1.0a use [[yii\authclient\OAuth1]].
- - For OpenID use [[yii\authclient\OpenId]].
-
-At this stage you can determine auth client default name, title and view options, declaring
-corresponding methods:
-
-```php
-use yii\authclient\OAuth2;
-
-class MyAuthClient extends OAuth2
-{
- protected function defaultName()
- {
- return 'my_auth_client';
- }
-
- protected function defaultTitle()
- {
- return 'My Auth Client';
- }
-
- protected function defaultViewOptions()
- {
- return [
- 'popupWidth' => 800,
- 'popupHeight' => 500,
- ];
- }
-}
-```
-
-Depending on actual base class, you will need to redeclare different fields and methods.
-
-### [[yii\authclient\OpenId]]
-
-All you need is to specify auth URL, by redeclaring `authUrl` field.
-You may also setup default required and/or optional attributes.
-For example:
-
-```php
-use yii\authclient\OpenId;
-
-class MyAuthClient extends OpenId
-{
- public $authUrl = 'https://www.my.com/openid/';
-
- public $requiredAttributes = [
- 'contact/email',
- ];
-
- public $optionalAttributes = [
- 'namePerson/first',
- 'namePerson/last',
- ];
-}
-```
-
-### [[yii\authclient\OAuth2]]
-
-You will need to specify:
-
-- Auth URL by redeclaring `authUrl` field.
-- Token request URL by redeclaring `tokenUrl` field.
-- API base URL by redeclaring `apiBaseUrl` field.
-- User attribute fetching strategy by redeclaring `initUserAttributes()` method.
-
-For example:
-
-```php
-use yii\authclient\OAuth2;
-
-class MyAuthClient extends OAuth2
-{
- public $authUrl = 'https://www.my.com/oauth2/auth';
-
- public $tokenUrl = 'https://www.my.com/oauth2/token';
-
- public $apiBaseUrl = 'https://www.my.com/apis/oauth2/v1';
-
- protected function initUserAttributes()
- {
- return $this->api('userinfo', 'GET');
- }
-}
-```
-
-You may also specify default auth scopes.
-
-> Note: Some OAuth providers may not follow OAuth standards clearly, introducing
- differences, and may require additional efforts to implement clients for.
-
-### [[yii\authclient\OAuth1]]
-
-You will need to specify:
-
-- Auth URL by redeclaring `authUrl` field.
-- Request token URL by redeclaring `requestTokenUrl` field.
-- Access token URL by redeclaring `accessTokenUrl` field.
-- API base URL by redeclaring `apiBaseUrl` field.
-- User attribute fetching strategy by redeclaring `initUserAttributes()` method.
-
-For example:
-
-```php
-use yii\authclient\OAuth1;
-
-class MyAuthClient extends OAuth1
-{
- public $authUrl = 'https://www.my.com/oauth/auth';
-
- public $requestTokenUrl = 'https://www.my.com/oauth/request_token';
-
- public $accessTokenUrl = 'https://www.my.com/oauth/access_token';
-
- public $apiBaseUrl = 'https://www.my.com/apis/oauth/v1';
-
- protected function initUserAttributes()
- {
- return $this->api('userinfo', 'GET');
- }
-}
-```
-
-You may also specify default auth scopes.
-
-> Note: Some OAuth providers may not follow OAuth standards clearly, introducing
- differences, and may require additional efforts to implement clients for.
-
diff --git a/docs/guide/security-authentication.md b/docs/guide/security-authentication.md
index 449d7a6415..8be7fc0b2e 100644
--- a/docs/guide/security-authentication.md
+++ b/docs/guide/security-authentication.md
@@ -1,19 +1,74 @@
Authentication
==============
+<<<<<<< HEAD
<<<<<<< HEAD
> Note: This section is under development.
+=======
+Authentication is the process of verifying the identity of a user. It usually uses an identifier
+(e.g. a username or an email address) and a secret token (e.g. a password or an access token) to judge
+if the user is the one whom he claims as. Authentication is the basis of the login feature.
+>>>>>>> master
-Authentication is the act of verifying who a user is, and is the basis of the login process. Typically, authentication uses the combination of an identifier--a username or email address--and a password. The user submits these values through a form, and the application then compares the submitted information against that previously stored (e.g., upon registration).
+Yii provides an authentication framework which wires up various components to support login. To use this framework,
+you mainly need to do the following work:
+
+* Configure the [[yii\web\User|user]] application component;
+* Create a class that implements the [[yii\web\IdentityInterface]] interface.
-In Yii, this entire process is performed semi-automatically, leaving the developer to merely implement [[yii\web\IdentityInterface]], the most important class in the authentication system. Typically, implementation of `IdentityInterface` is accomplished using the `User` model.
-You can find a fully featured example of authentication in the
-[advanced application template](tutorial-advanced-app.md). Below, only the interface methods are listed:
+## Configuring [[yii\web\User]]
+
+The [[yii\web\User|user]] application component manages the user authentication status. It requires you to
+specify an [[yii\web\User::identityClass|identity class]] which contains the actual authentication logic.
+In the following application configuration, the [[yii\web\User::identityClass|identity class]] for
+[[yii\web\User|user]] is configured to be `app\models\User` whose implementation is explained in
+the next subsection:
+
+```php
+return [
+ 'components' => [
+ 'user' => [
+ 'identityClass' => 'app\models\User',
+ ],
+ ],
+];
+```
+
+
+## Implementing [[yii\web\IdentityInterface]]
+
+The [[yii\web\User::identityClass|identity class]] must implement the [[yii\web\IdentityInterface]] which contains
+the following methods:
+
+* [[yii\web\IdentityInterface::findIdentity()|findIdentity()]]: it looks for an instance of the identity
+ class using the specified user ID. This method is used when you need to maintain the login status via session.
+* [[yii\web\IdentityInterface::findIdentityByAccessToken()|findIdentityByAccessToken()]]: it looks for
+ an instance of the identity class using the specified access token. This method is used when you need
+ to authenticate a user by a single secret token (e.g. in a stateless RESTful application).
+* [[yii\web\IdentityInterface::getId()|getId()]]: it returns the ID of the user represented by this identity instance.
+* [[yii\web\IdentityInterface::getAuthKey()|getAuthKey()]]: it returns a key used to verify cookie-based login.
+ The key is stored in the login cookie and will be later compared with the server-side version to make
+ sure the login cookie is valid.
+* [[yii\web\IdentityInterface::validateAuthKey()|validateAuthKey()]]: it implements the logic for verifying
+ the cookie-based login key.
+
+If a particular method is not needed, you may implement it with an empty body. For example, if your application
+is a pure stateless RESTful application, you would only need to implement [[yii\web\IdentityInterface::findIdentityByAccessToken()|findIdentityByAccessToken()]]
+and [[yii\web\IdentityInterface::getId()|getId()]] while leaving all other methods with an empty body.
+
+In the following example, an [[yii\web\User::identityClass|identity class]] is implemented as
+an [Active Record](db-active-record.md) class associated with the `user` database table.
```php
+>>>>>> master
public static function tableName()
{
return 'user';
}
+<<<<<<< HEAD
>>>>>>> yiichina/master
+=======
+>>>>>>> master
/**
* Finds an identity by the given ID.
@@ -133,26 +193,38 @@ class User extends ActiveRecord implements IdentityInterface
}
```
+<<<<<<< HEAD
<<<<<<< HEAD
Two of the outlined methods are simple: `findIdentity` is provided with an ID value and returns a model instance
associated with that ID. The `getId` method returns the ID itself. Two of the other methods – `getAuthKey` and
`validateAuthKey` – are used to provide extra security to the "remember me" cookie. The `getAuthKey` method should
return a string that is unique for each user. You can reliably create a unique string using
`Yii::$app->getSecurity()->generateRandomString()`. It's a good idea to also save this as part of the user's record:
+=======
+As explained previously, you only need to implement `getAuthKey()` and `validateAuthKey()` if your application
+uses cookie-based login feature. In this case, you may use the following code to generate an auth key for each
+user and store it in the `user` table:
+>>>>>>> master
```php
-public function beforeSave($insert)
+class User extends ActiveRecord implements IdentityInterface
{
- if (parent::beforeSave($insert)) {
- if ($this->isNewRecord) {
- $this->auth_key = Yii::$app->getSecurity()->generateRandomString();
+ ......
+
+ public function beforeSave($insert)
+ {
+ if (parent::beforeSave($insert)) {
+ if ($this->isNewRecord) {
+ $this->auth_key = \Yii::$app->security->generateRandomString();
+ }
+ return true;
}
- return true;
+ return false;
}
- return false;
}
```
+<<<<<<< HEAD
The `validateAuthKey` method just needs to compare the `$authKey` variable, passed as a parameter (itself retrieved from a cookie), with the value fetched from the database.
=======
As explained previously, you only need to implement `getAuthKey()` and `validateAuthKey()` if your application
@@ -177,6 +249,8 @@ class User extends ActiveRecord implements IdentityInterface
}
```
+=======
+>>>>>>> master
> Note: Do not confuse the `User` identity class with [[yii\web\User]]. The former is the class implementing
the authentication logic. It is often implemented as an [Active Record](db-active-record.md) class associated
with some persistent storage for storing the user credential information. The latter is an application component
@@ -251,4 +325,7 @@ The [[yii\web\User]] class raises a few events during the login and logout proce
You may respond to these events to implement features such as login audit, online user statistics. For example,
in the handler for [[yii\web\User::EVENT_AFTER_LOGIN|EVENT_AFTER_LOGIN]], you may record the login time and IP
address in the `user` table.
+<<<<<<< HEAD
>>>>>>> yiichina/master
+=======
+>>>>>>> master
diff --git a/docs/guide/security-authorization.md b/docs/guide/security-authorization.md
index e52f103b06..99aaeeb227 100644
--- a/docs/guide/security-authorization.md
+++ b/docs/guide/security-authorization.md
@@ -1,23 +1,22 @@
Authorization
=============
-> Note: This section is under development.
-
Authorization is the process of verifying that a user has enough permission to do something. Yii provides two authorization
methods: Access Control Filter (ACF) and Role-Based Access Control (RBAC).
-Access Control Filter
----------------------
+## Access Control Filter
-Access Control Filter (ACF) is a simple authorization method that is best used by applications that only need some
-simple access control. As its name indicates, ACF is an action filter that can be attached to a controller or a module
-as a behavior. ACF will check a set of [[yii\filters\AccessControl::rules|access rules]] to make sure the current user
-can access the requested action.
+Access Control Filter (ACF) is a simple authorization method implemented as [[yii\filters\AccessControl]] which
+is best used by applications that only need some simple access control. As its name indicates, ACF is
+an action [filter](structure-filters.md) that can be used in a controller or a module. While a user is requesting
+to execute an action, ACF will check a list of [[yii\filters\AccessControl::rules|access rules]]
+to determine if the user is allowed to access the requested action.
-The code below shows how to use ACF which is implemented as [[yii\filters\AccessControl]]:
+The code below shows how to use ACF in the `site` controller:
```php
+use yii\web\Controller;
use yii\filters\AccessControl;
class SiteController extends Controller
@@ -48,32 +47,39 @@ class SiteController extends Controller
```
In the code above ACF is attached to the `site` controller as a behavior. This is the typical way of using an action
-filter. The `only` option specifies that the ACF should only be applied to `login`, `logout` and `signup` actions.
-The `rules` option specifies the [[yii\filters\AccessRule|access rules]], which reads as follows:
+filter. The `only` option specifies that the ACF should only be applied to the `login`, `logout` and `signup` actions.
+All other actions in the `site` controller are not subject to the access control. The `rules` option lists
+the [[yii\filters\AccessRule|access rules]], which reads as follows:
-- Allow all guest (not yet authenticated) users to access 'login' and 'signup' actions. The `roles` option
- contains a question mark `?` which is a special token recognized as "guests".
-- Allow authenticated users to access 'logout' action. The `@` character is another special token recognized as
- authenticated users.
+- Allow all guest (not yet authenticated) users to access the `login` and `signup` actions. The `roles` option
+ contains a question mark `?` which is a special token representing "guest users".
+- Allow authenticated users to access the `logout` action. The `@` character is another special token representing
+ "authenticated users".
-When ACF performs authorization check, it will examine the rules one by one from top to bottom until it finds
-a match. The `allow` value of the matching rule will then be used to judge if the user is authorized. If none
-of the rules matches, it means the user is NOT authorized and ACF will stop further action execution.
+ACF performs the authorization check by examining the access rules one by one from top to bottom until it finds
+a rule that matches the current execution context. The `allow` value of the matching rule will then be used to
+judge if the user is authorized or not. If none of the rules matches, it means the user is NOT authorized,
+and ACF will stop further action execution.
+<<<<<<< HEAD
<<<<<<< HEAD
By default, ACF does only of the followings when it determines a user is not authorized to access the current action:
=======
By default, ACF does only the following when it determines a user is not authorized to access the current action:
>>>>>>> yiichina/master
+=======
+When ACF determines a user is not authorized to access the current action, it takes the following measure by default:
+>>>>>>> master
-* If the user is a guest, it will call [[yii\web\User::loginRequired()]], which may redirect the browser to the login page.
+* If the user is a guest, it will call [[yii\web\User::loginRequired()]] to redirect the user browser to the login page.
* If the user is already authenticated, it will throw a [[yii\web\ForbiddenHttpException]].
-You may customize this behavior by configuring the [[yii\filters\AccessControl::denyCallback]] property:
+You may customize this behavior by configuring the [[yii\filters\AccessControl::denyCallback]] property like the following:
```php
[
'class' => AccessControl::className(),
+ ...
'denyCallback' => function ($rule, $action) {
throw new \Exception('You are not allowed to access this page');
}
@@ -90,8 +96,8 @@ be an array of action IDs. The comparison is case-sensitive. If this option is e
it means the rule applies to all actions.
* [[yii\filters\AccessRule::controllers|controllers]]: specifies which controllers this rule
-matches. This should be an array of controller IDs. The comparison is case-sensitive. If this option is
-empty or not set, it means the rule applies to all controllers.
+matches. This should be an array of controller IDs. Each controller ID is prefixed with the module ID (if any).
+The comparison is case-sensitive. If this option is empty or not set, it means the rule applies to all controllers.
* [[yii\filters\AccessRule::roles|roles]]: specifies which user roles that this rule matches.
Two special roles are recognized, and they are checked via [[yii\web\User::isGuest]]:
@@ -99,8 +105,8 @@ empty or not set, it means the rule applies to all controllers.
- `?`: matches a guest user (not authenticated yet)
- `@`: matches an authenticated user
- Using other role names requires RBAC (to be described in the next section), and [[yii\web\User::can()]] will be called.
- If this option is empty or not set, it means this rule applies to all roles.
+ Using other role names will trigger the invocation of [[yii\web\User::can()]], which requires enabling RBAC
+ (to be described in the next subsection). If this option is empty or not set, it means this rule applies to all roles.
* [[yii\filters\AccessRule::ips|ips]]: specifies which [[yii\web\Request::userIP|client IP addresses]] this rule matches.
An IP address can contain the wildcard `*` at the end so that it matches IP addresses with the same prefix.
@@ -152,8 +158,7 @@ class SiteController extends Controller
```
-Role based access control (RBAC)
---------------------------------
+## Role Based Access Control (RBAC)
Role-Based Access Control (RBAC) provides a simple yet powerful centralized access control. Please refer to
the [Wikipedia](http://en.wikipedia.org/wiki/Role-based_access_control) for details about comparing RBAC
@@ -168,7 +173,7 @@ part is to use the authorization data to perform access check in places where it
To facilitate our description next, we will first introduce some basic RBAC concepts.
-### Basic Concepts
+### Basic Concepts
A role represents a collection of *permissions* (e.g. creating posts, updating posts). A role may be assigned
to one or multiple users. To check if a user has a specified permission, we may check if the user is assigned
@@ -184,7 +189,7 @@ and a permission may consist of other permissions. Yii implements a *partial ord
more special *tree* hierarchy. While a role can contain a permission, it is not true vice versa.
-### Configuring RBAC Manager
+### Configuring RBAC
Before we set off to define authorization data and perform access checking, we need to configure the
[[yii\base\Application::authManager|authManager]] application component. Yii provides two types of authorization managers:
@@ -192,7 +197,8 @@ Before we set off to define authorization data and perform access checking, we n
data, while the latter stores authorization data in a database. You may consider using the former if your application
does not require very dynamic role and permission management.
-#### configuring authManager with `PhpManager`
+
+#### Using `PhpManager`
The following code shows how to configure the `authManager` in the application configuration using the [[yii\rbac\PhpManager]] class:
@@ -210,10 +216,11 @@ return [
The `authManager` can now be accessed via `\Yii::$app->authManager`.
-> Tip: By default, [[yii\rbac\PhpManager]] stores RBAC data in files under `@app/rbac/` directory. Make sure the directory
- and all the files in it are writable by the Web server process if permissions hierarchy needs to be changed online.
+By default, [[yii\rbac\PhpManager]] stores RBAC data in files under `@app/rbac` directory. Make sure the directory
+and all the files in it are writable by the Web server process if permissions hierarchy needs to be changed online.
-#### configuring authManager with `DbManager`
+
+#### Using `DbManager`
The following code shows how to configure the `authManager` in the application configuration using the [[yii\rbac\DbManager]] class:
@@ -228,6 +235,9 @@ return [
],
];
```
+> Note: If you are using yii2-basic-app template, there is a `config/console.php` configuration file where the
+ `authManager` needs to be declared additionally to `config/web.php`.
+> In case of yii2-advanced-app the `authManager` should be declared only once in `common/config/main.php`.
`DbManager` uses four database tables to store its data:
@@ -242,7 +252,8 @@ Before you can go on you need to create those tables in the database. To do this
The `authManager` can now be accessed via `\Yii::$app->authManager`.
-### Building Authorization Data
+
+### Building Authorization Data
Building authorization data is all about the following tasks:
@@ -300,6 +311,9 @@ class RbacController extends Controller
}
```
+> Note: If you are using advanced template, you need to put your `RbacController` inside `console/controllers` directory
+ and change namespace to `console/controllers`.
+
After executing the command with `yii rbac/init` we'll get the following hierarchy:
@@ -308,10 +322,14 @@ Author can create post, admin can update post and do everything author can.
If your application allows user signup you need to assign roles to these new users once. For example, in order for all
<<<<<<< HEAD
+<<<<<<< HEAD
signed up users to become authors in your advanced application template you need to modify `frontend\models\SignupForm::signup()`
=======
signed up users to become authors in your advanced project template you need to modify `frontend\models\SignupForm::signup()`
>>>>>>> yiichina/master
+=======
+signed up users to become authors in your advanced project template you need to modify `frontend\models\SignupForm::signup()`
+>>>>>>> master
as follows:
```php
@@ -341,7 +359,7 @@ For applications that require complex access control with dynamically updated au
(i.e. admin panel) may need to be developed using APIs offered by `authManager`.
-### Using Rules
+### Using Rules
As aforementioned, rules add additional constraint to roles and permissions. A rule is a class extending
from [[yii\rbac\Rule]]. It must implement the [[yii\rbac\Rule::execute()|execute()]] method. In the hierarchy we've
@@ -395,11 +413,12 @@ $auth->addChild($updateOwnPost, $updatePost);
$auth->addChild($author, $updateOwnPost);
```
-Now we've got the following hierarchy:
+Now we have got the following hierarchy:
-### Access Check
+
+### Access Check
With the authorization data ready, access check is as simple as a call to the [[yii\rbac\ManagerInterface::checkAccess()]]
method. Because most access check is about the current user, for convenience Yii provides a shortcut method
@@ -411,11 +430,11 @@ if (\Yii::$app->user->can('createPost')) {
}
```
-If the current user is Jane with ID=1 we're starting at `createPost` and trying to get to `Jane`:
+If the current user is Jane with `ID=1` we are starting at `createPost` and trying to get to `Jane`:
-In order to check if user can update post we need to pass an extra parameter that is required by the `AuthorRule` described before:
+In order to check if a user can update a post, we need to pass an extra parameter that is required by `AuthorRule` described before:
```php
if (\Yii::$app->user->can('updatePost', ['post' => $post])) {
@@ -423,20 +442,21 @@ if (\Yii::$app->user->can('updatePost', ['post' => $post])) {
}
```
-Here's what happens if current user is John:
+Here is what happens if the current user is John:
-We're starting with the `updatePost` and going through `updateOwnPost`. In order to pass it `AuthorRule` should return
-`true` from its `execute` method. The method receives its `$params` from `can` method call so the value is
-`['post' => $post]`. If everything is OK we're getting to `author` that is assigned to John.
+We are starting with the `updatePost` and going through `updateOwnPost`. In order to pass the access check, `AuthorRule`
+should return `true` from its `execute()` method. The method receives its `$params` from the `can()` method call so the value is
+`['post' => $post]`. If everything is fine, we will get to `author` which is assigned to John.
-In case of Jane it is a bit simpler since she's an admin:
+In case of Jane it is a bit simpler since she is an admin:
-### Using Default Roles
+
+### Using Default Roles
A default role is a role that is *implicitly* assigned to *all* users. The call to [[yii\rbac\ManagerInterface::assign()]]
is not needed, and the authorization data does not contain its assignment information.
diff --git a/docs/guide/security-best-practices.md b/docs/guide/security-best-practices.md
index 8081b5e617..87a3231272 100644
--- a/docs/guide/security-best-practices.md
+++ b/docs/guide/security-best-practices.md
@@ -139,16 +139,52 @@ from a user browser are made by the user himself. It could be false.
For example, `an.example.com` website has `/logout` URL that, when accessed using a simple GET, logs user out. As long
as it's requested by the user itself everything is OK but one day bad guys are somehow posting
`
` on a forum user visits frequently. Browser doesn't make any difference between
-requesting an image or requesting a page so when user opens a page with such `img` tag he's being logged out from
-`an.example.com`.
+requesting an image or requesting a page so when user opens a page with such `img` tag, the browser will send the GET request to that URL, and the user will be logged out from `an.example.com`.
-That's the basic idea. One can say that logging user out is nothing serious. Well, sending POST isn't much trickier.
+That's the basic idea. One can say that logging user out is nothing serious, but bad guys can do much more, using this idea. Imagine that some website has an URL `http://an.example.com/purse/transfer?to=anotherUser&amout=2000`. Accessing it using GET request, causes transfer of $2000 from authorized user account to user `anotherUser`. We know, that browser will always send GET request to load an image, so we can modify code to accept only POST requests on that URL. Unfortunately, this will not save us, because an attacker can put some JavaScript code instead of `![]()
` tag, which allows to send POST requests on that URL.
In order to avoid CSRF you should always:
1. Follow HTTP specification i.e. GET should not change application state.
2. Keep Yii CSRF protection enabled.
+Sometimes you need to disable CSRF validation per controller and/or action. It could be achieved by setting its property:
+
+```php
+namespace app\controllers;
+
+use yii\web\Controller;
+
+class SiteController extends Controller
+{
+ public $enableCsrfValidation = false;
+
+ public function actionIndex()
+ {
+ // CSRF validation will not be applied to this and other actions
+ }
+
+}
+```
+
+To disable CSRF validation per custom actions you can do:
+
+```php
+namespace app\controllers;
+
+use yii\web\Controller;
+
+class SiteController extends Controller
+{
+ public function beforeAction($action)
+ {
+ // ...set `$this->enableCsrfValidation` here based on some conditions...
+ // call parent method that will check CSRF if such property is true.
+ return parent::beforeAction($action);
+ }
+}
+```
+
Avoiding file exposure
----------------------
@@ -171,3 +207,17 @@ simply rewrite code with what's generated by Gii.
Debug toolbar should be avoided at production unless really necessary. It exposes all the application and config
details possible. If you absolutely need it check twice that access is properly restricted to your IP only.
+
+Using secure connection over TLS
+--------------------------------
+
+Yii provides features that rely on cookies and/or PHP sessions. These can be vulnerable in case your connection is
+compromised. The risk is reduced if the app uses secure connection via TLS.
+
+Please refer to your webserver documentation for instructions on how to configure it. You may also check example configs
+provided by H5BP project:
+
+- [Nginx](https://github.com/h5bp/server-configs-nginx)
+- [Apache](https://github.com/h5bp/server-configs-apache).
+- [IIS](https://github.com/h5bp/server-configs-iis).
+- [Lighttpd](https://github.com/h5bp/server-configs-lighttpd).
diff --git a/docs/guide/security-cryptography.md b/docs/guide/security-cryptography.md
new file mode 100644
index 0000000000..b5818f9bfb
--- /dev/null
+++ b/docs/guide/security-cryptography.md
@@ -0,0 +1,66 @@
+Cryptography
+============
+
+In this section we'll review the following security aspects:
+
+- Generating random data
+- Encryption and Decryption
+- Confirming Data Integrity
+
+Generating Pseudorandom Data
+----------------------------
+
+Pseudorandom data is useful in many situations. For example when resetting a password via email you need to generate a
+token, save it to the database, and send it via email to end user which in turn will allow them to prove ownership of
+that account. It is very important that this token be unique and hard to guess, else there is a possibility that attacker
+can predict the token's value and reset the user's password.
+
+Yii security helper makes generating pseudorandom data simple:
+
+
+```php
+$key = Yii::$app->getSecurity()->generateRandomString();
+```
+
+Encryption and Decryption
+-------------------------
+
+Yii provides convenient helper functions that allow you to encrypt/decrypt data using a secret key. The data is passed through the encryption function so that only the person which has the secret key will be able to decrypt it.
+For example, we need to store some information in our database but we need to make sure only the user who has the secret key can view it (even if the application database is compromised):
+
+
+```php
+// $data and $secretKey are obtained from the form
+$encryptedData = Yii::$app->getSecurity()->encryptByPassword($data, $secretKey);
+// store $encryptedData to database
+```
+
+Subsequently when user wants to read the data:
+
+```php
+// $secretKey is obtained from user input, $encryptedData is from the database
+$data = Yii::$app->getSecurity()->decryptByPassword($encryptedData, $secretKey);
+```
+
+It's also possible to use key instead of password via [[\yii\base\Security::encryptByKey()]] and
+[[\yii\base\Security::decryptByKey()]].
+
+Confirming Data Integrity
+-------------------------
+
+There are situations in which you need to verify that your data hasn't been tampered with by a third party or even corrupted in some way. Yii provides an easy way to confirm data integrity in the form of two helper functions.
+
+Prefix the data with a hash generated from the secret key and data
+
+
+```php
+// $secretKey our application or user secret, $genuineData obtained from a reliable source
+$data = Yii::$app->getSecurity()->hashData($genuineData, $secretKey);
+```
+
+Checks if the data integrity has been compromised
+
+```php
+// $secretKey our application or user secret, $data obtained from an unreliable source
+$data = Yii::$app->getSecurity()->validateData($data, $secretKey);
+```
diff --git a/docs/guide/security-overview.md b/docs/guide/security-overview.md
new file mode 100644
index 0000000000..7903a10ac9
--- /dev/null
+++ b/docs/guide/security-overview.md
@@ -0,0 +1,14 @@
+Security
+========
+
+Good security is vital to the health and success of any application. Unfortunately, many developers cut corners when it
+comes to security, either due to a lack of understanding or because implementation is too much of a hurdle. To make your
+Yii powered application as secure as possible, Yii has included several excellent and easy to use security features.
+
+* [Authentication](security-authentication.md)
+* [Authorization](security-authorization.md)
+* [Working with Passwords](security-passwords.md)
+* [Cryptography](security-cryptography.md)
+* [Views security](structure-views.md#security)
+* [Auth Clients](https://github.com/yiisoft/yii2-authclient/blob/master/docs/guide/README.md)
+* [Best Practices](security-best-practices.md)
diff --git a/docs/guide/security-passwords.md b/docs/guide/security-passwords.md
index 26b246a206..4bc424a6e5 100644
--- a/docs/guide/security-passwords.md
+++ b/docs/guide/security-passwords.md
@@ -1,12 +1,20 @@
<<<<<<< HEAD
+<<<<<<< HEAD
Security
=======
Working with Passwords
>>>>>>> yiichina/master
========
+=======
+Working with Passwords
+======================
+>>>>>>> master
-> Note: This section is under development.
+Most developers know that passwords cannot be stored in plain text, but many developers believe it's still safe to hash
+passwords using `md5` or `sha1`. There was a time when using the aforementioned hashing algorithms was sufficient,
+but modern hardware makes it possible to reverse such hashes and even stronger ones very quickly using brute force attacks.
+<<<<<<< HEAD
Good security is vital to the health and success of any application. Unfortunately, many developers cut corners when it comes to security, either due to a lack of understanding or because implementation is too much of a hurdle. To make your Yii powered application as secure as possible, Yii has included several excellent and easy to use security features.
@@ -20,6 +28,12 @@ Hashing and Verifying Passwords
Most developers know that passwords cannot be stored in plain text, but many developers believe it's still safe to hash passwords using `md5` or `sha1`. There was a time when using the aforementioned hashing algorithms was sufficient, but modern hardware makes it possible to reverse such hashes very quickly using brute force attacks.
In order to provide increased security for user passwords, even in the worst case scenario (your application is breached), you need to use a hashing algorithm that is resilient against brute force attacks. The best current choice is `bcrypt`. In PHP, you can create a `bcrypt` hash using the [crypt function](http://php.net/manual/en/function.crypt.php). Yii provides two helper functions which make using `crypt` to securely generate and verify hashes easier.
+=======
+In order to provide increased security for user passwords, even in the worst case scenario (your application is breached),
+you need to use a hashing algorithm that is resilient against brute force attacks. The best current choice is `bcrypt`.
+In PHP, you can create a `bcrypt` hash using the [crypt function](http://php.net/manual/en/function.crypt.php). Yii provides
+two helper functions which make using `crypt` to securely generate and verify hashes easier.
+>>>>>>> master
When a user provides a password for the first time (e.g., upon registration), the password needs to be hashed:
@@ -40,6 +54,7 @@ if (Yii::$app->getSecurity()->validatePassword($password, $hash)) {
// wrong password
}
```
+<<<<<<< HEAD
<<<<<<< HEAD
Generating Pseudorandom data
@@ -158,3 +173,5 @@ See also
- [Views security](structure-views.md#security)
+=======
+>>>>>>> master
diff --git a/docs/guide/start-databases.md b/docs/guide/start-databases.md
index 57c301b2a7..7d74ff6202 100644
--- a/docs/guide/start-databases.md
+++ b/docs/guide/start-databases.md
@@ -8,10 +8,10 @@ and create a [view](structure-views.md).
Through this tutorial, you will learn how to:
-* Configure a DB connection
-* Define an Active Record class
-* Query data using the Active Record class
-* Display data in a view in a paginated fashion
+* configure a DB connection,
+* define an Active Record class,
+* query data using the Active Record class,
+* display data in a view in a paginated fashion.
Note that in order to finish this section, you should have basic knowledge and experience using databases.
In particular, you should know how to create a database, and how to execute SQL statements using a DB client tool.
@@ -32,16 +32,16 @@ CREATE TABLE `country` (
`population` INT(11) NOT NULL DEFAULT '0'
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
-INSERT INTO `country` VALUES ('AU','Australia',18886000);
-INSERT INTO `country` VALUES ('BR','Brazil',170115000);
-INSERT INTO `country` VALUES ('CA','Canada',1147000);
-INSERT INTO `country` VALUES ('CN','China',1277558000);
-INSERT INTO `country` VALUES ('DE','Germany',82164700);
-INSERT INTO `country` VALUES ('FR','France',59225700);
-INSERT INTO `country` VALUES ('GB','United Kingdom',59623400);
-INSERT INTO `country` VALUES ('IN','India',1013662000);
-INSERT INTO `country` VALUES ('RU','Russia',146934000);
-INSERT INTO `country` VALUES ('US','United States',278357000);
+INSERT INTO `country` VALUES ('AU','Australia',24016400);
+INSERT INTO `country` VALUES ('BR','Brazil',205722000);
+INSERT INTO `country` VALUES ('CA','Canada',35985751);
+INSERT INTO `country` VALUES ('CN','China',1375210000);
+INSERT INTO `country` VALUES ('DE','Germany',81459000);
+INSERT INTO `country` VALUES ('FR','France',64513242);
+INSERT INTO `country` VALUES ('GB','United Kingdom',65097000);
+INSERT INTO `country` VALUES ('IN','India',1285400000);
+INSERT INTO `country` VALUES ('RU','Russia',146519759);
+INSERT INTO `country` VALUES ('US','United States',322976000);
```
At this point, you have a database named `yii2basic`, and within it a `country` table with three columns, containing ten rows of data.
@@ -78,6 +78,12 @@ The DB connection configured above can be accessed in the application code via t
which specifies how the [application](structure-applications.md) instance should be initialized.
For more information, please refer to the [Configurations](concept-configurations.md) section.
+If you need to work with databases support for which isn't bundled with Yii, check the following extensions:
+
+- [Informix](https://github.com/edgardmessias/yii2-informix)
+- [IBM DB2](https://github.com/edgardmessias/yii2-ibm-db2)
+- [Firebird](https://github.com/edgardmessias/yii2-firebird)
+
Creating an Active Record
-------------------------
@@ -219,7 +225,7 @@ Trying it Out
To see how all of the above code works, use your browser to access the following URL:
```
-http://hostname/index.php?r=country/index
+http://hostname/index.php?r=country%2Findex
```
@@ -229,7 +235,7 @@ If you click on the button "2", you will see the page display another five count
Observe more carefully and you will find that the URL in the browser also changes to
```
-http://hostname/index.php?r=country/index&page=2
+http://hostname/index.php?r=country%2Findex&page=2
```
Behind the scenes, [[yii\data\Pagination|Pagination]] is providing all of the necessary functionality to paginate a data set:
@@ -251,7 +257,7 @@ Summary
In this section, you learned how to work with a database. You also learned how to fetch and display
data in pages with the help of [[yii\data\Pagination]] and [[yii\widgets\LinkPager]].
-In the next section, you will learn how to use the powerful code generation tool, called [Gii](tool-gii.md),
+In the next section, you will learn how to use the powerful code generation tool, called [Gii](https://github.com/yiisoft/yii2-gii/blob/master/docs/guide/README.md),
to help you rapidly implement some commonly required features, such as the Create-Read-Update-Delete (CRUD)
operations for working with the data in a database table. As a matter of fact, the code you have just written can all
be automatically generated in Yii using the Gii tool.
diff --git a/docs/guide/start-forms.md b/docs/guide/start-forms.md
index 7b6e946007..bb56456320 100644
--- a/docs/guide/start-forms.md
+++ b/docs/guide/start-forms.md
@@ -10,9 +10,9 @@ two [views](structure-views.md), you will also create a [model](structure-models
Through this tutorial, you will learn how to:
-* Create a [model](structure-models.md) to represent the data entered by a user through a form
-* Declare rules to validate the data entered
-* Build an HTML form in a [view](structure-views.md)
+* create a [model](structure-models.md) to represent the data entered by a user through a form,
+* declare rules to validate the data entered,
+* build an HTML form in a [view](structure-views.md).
Creating a Model
@@ -27,10 +27,14 @@ section for more details about the class file naming convention.
namespace app\models;
+<<<<<<< HEAD
<<<<<<< HEAD
=======
use Yii;
>>>>>>> yiichina/master
+=======
+use Yii;
+>>>>>>> master
use yii\base\Model;
class EntryForm extends Model
@@ -190,7 +194,7 @@ Trying it Out
To see how it works, use your browser to access the following URL:
```
-http://hostname/index.php?r=site/entry
+http://hostname/index.php?r=site%2Fentry
```
You will see a page displaying a form with two input fields. In front of each input field, a label indicates what data is to be entered. If you click the submit button without
@@ -239,7 +243,7 @@ the following code:
Summary
-------
-In this section of the guide, you have touched every part in the MVC design pattern. You have learned how
+In this section of the guide, you have touched every part in the MVC architectural pattern. You have learned how
to create a model class to represent the user data and validate said data.
You have also learned how to get data from users and how to display data back in the browser. This is a task that
diff --git a/docs/guide/start-gii.md b/docs/guide/start-gii.md
index b65cd13ddf..81337c6614 100644
--- a/docs/guide/start-gii.md
+++ b/docs/guide/start-gii.md
@@ -1,25 +1,29 @@
Generating Code with Gii
========================
-This section will describe how to use [Gii](tool-gii.md) to automatically generate code
+This section will describe how to use [Gii](https://github.com/yiisoft/yii2-gii/blob/master/docs/guide/README.md) to automatically generate code
that implements some common Web site features. Using Gii to auto-generate code is simply a matter of entering the right information per the instructions shown on the Gii Web pages.
Through this tutorial, you will learn how to:
-* Enable Gii in your application
-* Use Gii to generate an Active Record class
-* Use Gii to generate the code implementing the CRUD operations for a DB table
-* Customize the code generated by Gii
+* enable Gii in your application,
+* use Gii to generate an Active Record class,
+* use Gii to generate the code implementing the CRUD operations for a DB table,
+* customize the code generated by Gii.
Starting Gii
------------
+<<<<<<< HEAD
<<<<<<< HEAD
[Gii](tool-gii.md) is provided in Yii as a [module](structure-modules.md). You can enable Gii
=======
[Gii](https://github.com/yiisoft/yii2-gii/blob/master/docs/guide/README.md) is provided in Yii as a [module](structure-modules.md). You can enable Gii
>>>>>>> yiichina/master
+=======
+[Gii](https://github.com/yiisoft/yii2-gii/blob/master/docs/guide/README.md) is provided in Yii as a [module](structure-modules.md). You can enable Gii
+>>>>>>> master
by configuring it in the [[yii\base\Application::modules|modules]] property of the application. Depending upon how you created your application, you may find the following code is already provided in the `config/web.php` configuration file:
```php
@@ -27,7 +31,9 @@ $config = [ ... ];
if (YII_ENV_DEV) {
$config['bootstrap'][] = 'gii';
- $config['modules']['gii'] = 'yii\gii\Module';
+ $config['modules']['gii'] = [
+ 'class' => 'yii\gii\Module',
+ ];
}
```
@@ -109,7 +115,7 @@ Trying it Out
To see how it works, use your browser to access the following URL:
```
-http://hostname/index.php?r=country/index
+http://hostname/index.php?r=country%2Findex
```
You will see a data grid showing the countries from the database table. You may sort the grid,
@@ -131,7 +137,7 @@ or to customize them:
> Info: Gii is designed to be a highly customizable and extensible code generation tool. Using it wisely
can greatly accelerate your application development speed. For more details, please refer to
- the [Gii](tool-gii.md) section.
+ the [Gii](https://github.com/yiisoft/yii2-gii/blob/master/docs/guide/README.md) section.
Summary
diff --git a/docs/guide/start-hello.md b/docs/guide/start-hello.md
index 8767b6d0a1..c812001341 100644
--- a/docs/guide/start-hello.md
+++ b/docs/guide/start-hello.md
@@ -10,7 +10,7 @@ a [view](structure-views.md):
Through this tutorial, you will learn three things:
-1. How to create an [action](structure-controllers.md) to respond to requests,
+1. how to create an [action](structure-controllers.md#creating-actions) to respond to requests,
2. how to create a [view](structure-views.md) to compose the response's content, and
3. how an application dispatches requests to [actions](structure-controllers.md#creating-actions).
@@ -102,7 +102,7 @@ Trying it Out
After creating the action and the view, you may access the new page by accessing the following URL:
```
-http://hostname/index.php?r=site/say&message=Hello+World
+http://hostname/index.php?r=site%2Fsay&message=Hello+World
```
@@ -134,7 +134,7 @@ the `SiteController::actionSay()` method will be called to handle the request.
Summary
-------
-In this section, you have touched the controller and view parts of the MVC design pattern.
+In this section, you have touched the controller and view parts of the MVC architectural pattern.
You created an action as part of a controller to handle a specific request. And you also created a view
to compose the response's content. In this simple example, no model was involved as the only data used was the `message` parameter.
diff --git a/docs/guide/start-installation.md b/docs/guide/start-installation.md
index faad367ad7..1bd9928381 100644
--- a/docs/guide/start-installation.md
+++ b/docs/guide/start-installation.md
@@ -1,19 +1,24 @@
Installing Yii
==============
+<<<<<<< HEAD
<<<<<<< HEAD
You can install Yii in two ways, using the [Composer](http://getcomposer.org/) package manager or by downloading an archive file.
+=======
+You can install Yii in two ways, using the [Composer](https://getcomposer.org/) package manager or by downloading an archive file.
+>>>>>>> master
The former is the preferred way, as it allows you to install new [extensions](structure-extensions.md) or update Yii by simply running a single command.
-Standard installations of Yii result in both the framework and an application template being downloaded and installed.
-An application template is a working Yii application implementing some basic features, such as login, contact form, etc.
+Standard installations of Yii result in both the framework and a project template being downloaded and installed.
+A project template is a working Yii project implementing some basic features, such as login, contact form, etc.
Its code is organized in a recommended way. Therefore, it can serve as a good starting point for your projects.
-In this and the next few sections, we will describe how to install Yii with the so-called *Basic Application Template* and
+In this and the next few sections, we will describe how to install Yii with the so-called *Basic Project Template* and
how to implement new features on top of this template. Yii also provides another template called
-the [Advanced Application Template](tutorial-advanced-app.md) which is better used in a team development environment
+the [Advanced Project Template](https://github.com/yiisoft/yii2-app-advanced/blob/master/docs/guide/README.md) which is better used in a team development environment
to develop applications with multiple tiers.
+<<<<<<< HEAD
> Info: The Basic Application Template is suitable for developing 90 percent of Web applications. It differs
from the Advanced Application Template mainly in how their code is organized. If you are new to Yii, we strongly
recommend you stick to the Basic Application Template for its simplicity yet sufficient functionalities.
@@ -34,6 +39,11 @@ to develop applications with multiple tiers.
from the Advanced Project Template mainly in how their code is organized. If you are new to Yii, we strongly
recommend you stick to the Basic Project Template for its simplicity yet sufficient functionalities.
>>>>>>> yiichina/master
+=======
+> Info: The Basic Project Template is suitable for developing 90 percent of Web applications. It differs
+ from the Advanced Project Template mainly in how their code is organized. If you are new to Yii, we strongly
+ recommend you stick to the Basic Project Template for its simplicity yet sufficient functionalities.
+>>>>>>> master
Installing via Composer
@@ -42,12 +52,19 @@ Installing via Composer
If you do not already have Composer installed, you may do so by following the instructions at
[getcomposer.org](https://getcomposer.org/download/). On Linux and Mac OS X, you'll run the following commands:
+<<<<<<< HEAD
<<<<<<< HEAD
curl -s http://getcomposer.org/installer | php
=======
curl -sSS https://getcomposer.org/installer | php
>>>>>>> yiichina/master
mv composer.phar /usr/local/bin/composer
+=======
+```bash
+curl -sS https://getcomposer.org/installer | php
+mv composer.phar /usr/local/bin/composer
+```
+>>>>>>> master
On Windows, you'll download and run [Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe).
@@ -59,12 +76,19 @@ by running `composer self-update`.
With Composer installed, you can install Yii by running the following commands under a Web-accessible folder:
+<<<<<<< HEAD
<<<<<<< HEAD
composer global require "fxp/composer-asset-plugin:1.0.0"
=======
composer global require "fxp/composer-asset-plugin:~1.0.0"
>>>>>>> yiichina/master
composer create-project --prefer-dist yiisoft/yii2-app-basic basic
+=======
+```bash
+composer global require "fxp/composer-asset-plugin:~1.1.1"
+composer create-project --prefer-dist yiisoft/yii2-app-basic basic
+```
+>>>>>>> master
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
@@ -77,7 +101,9 @@ once for all. The second command installs Yii in a directory named `basic`. You
> Tip: If you want to install the latest development version of Yii, you may use the following command instead,
> which adds a [stability option](https://getcomposer.org/doc/04-schema.md#minimum-stability):
>
-> composer create-project --prefer-dist --stability=dev yiisoft/yii2-app-basic basic
+> ```bash
+> composer create-project --prefer-dist --stability=dev yiisoft/yii2-app-basic basic
+> ```
>
> Note that the development version of Yii should not be used for production as it may break your running code.
@@ -110,41 +136,57 @@ But there are other installation options available:
* If you only want to install the core framework and would like to build an entire application from scratch,
you may follow the instructions as explained in [Building Application from Scratch](tutorial-start-from-scratch.md).
* If you want to start with a more sophisticated application, better suited to team development environments,
+<<<<<<< HEAD
<<<<<<< HEAD
you may consider installing the [Advanced Application Template](tutorial-advanced-app.md).
=======
you may consider installing the [Advanced Project Template](https://github.com/yiisoft/yii2-app-advanced/blob/master/docs/guide/README.md).
>>>>>>> yiichina/master
+=======
+ you may consider installing the [Advanced Project Template](https://github.com/yiisoft/yii2-app-advanced/blob/master/docs/guide/README.md).
+>>>>>>> master
Verifying the Installation
--------------------------
-After installation, you can use your browser to access the installed Yii application with the following URL:
-
-```
-http://localhost/basic/web/index.php
+After installation is done, either configure your web server (see next section) or use the
+[built-in PHP web server](https://secure.php.net/manual/en/features.commandline.webserver.php) by running the following
+console command while in the project `web` directory:
+
+```bash
+php yii serve
```
-This URL assumes you have installed Yii in a directory named `basic`, directly under the Web server's document root directory,
-and that the Web server is running on your local machine (`localhost`). You may need to adjust it to your installation environment.
+> Note: By default the HTTP-server will listen to port 8080. However if that port is already in use or you wish to
+serve multiple applications this way, you might want to specify what port to use. Just add the --port argument:
+
+```bash
+php yii serve --port=8888
+```
+
+You can use your browser to access the installed Yii application with the following URL:
+
+```
+http://localhost:8080/
+```
You should see the above "Congratulations!" page in your browser. If not, please check if your PHP installation satisfies
Yii's requirements. You can check if the minimum requirements are met using one of the following approaches:
-* Use a browser to access the URL `http://localhost/basic/requirements.php`
+* Copy `/requirements.php` to `/web/requirements.php` and then use a browser to access it via `http://localhost/requirements.php`
* Run the following commands:
- ```
+ ```bash
cd basic
php requirements.php
```
-You should configure your PHP installation so that it meets the minimum requirements of Yii. Most importantly, you should have PHP 5.4 or above. You should also install
-the [PDO PHP Extension](http://www.php.net/manual/en/pdo.installation.php) and a corresponding database driver
-(such as `pdo_mysql` for MySQL databases), if your application needs a database.
+You should configure your PHP installation so that it meets the minimum requirements of Yii. Most importantly, you
+should have PHP 5.4 or above. You should also install the [PDO PHP Extension](http://www.php.net/manual/en/pdo.installation.php)
+and a corresponding database driver (such as `pdo_mysql` for MySQL databases), if your application needs a database.
Configuring Web Servers
@@ -179,7 +221,7 @@ the [Shared Hosting Environment](tutorial-shared-hosting.md) section for more de
Use the following configuration in Apache's `httpd.conf` file or within a virtual host configuration. Note that you
should replace `path/to/basic/web` with the actual path for `basic/web`.
-```
+```apache
# Set document root to be "basic/web"
DocumentRoot "path/to/basic/web"
@@ -203,7 +245,7 @@ To use [Nginx](http://wiki.nginx.org/), you should install PHP as an [FPM SAPI](
You may use the following Nginx configuration, replacing `path/to/basic/web` with the actual path for
`basic/web` and `mysite.local` with the actual hostname to serve.
-```
+```nginx
server {
charset utf-8;
client_max_body_size 128M;
@@ -220,7 +262,7 @@ server {
location / {
# Redirect everything that isn't a real file to index.php
- try_files $uri $uri/ /index.php?$args;
+ try_files $uri $uri/ /index.php$is_args$args;
}
# uncomment to avoid processing of calls to non-existing static files by Yii
@@ -231,7 +273,7 @@ server {
location ~ \.php$ {
include fastcgi_params;
- fastcgi_param SCRIPT_FILENAME $document_root/$fastcgi_script_name;
+ fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_pass 127.0.0.1:9000;
#fastcgi_pass unix:/var/run/php5-fpm.sock;
try_files $uri =404;
diff --git a/docs/guide/start-looking-ahead.md b/docs/guide/start-looking-ahead.md
index 89adb7c639..78cbce422f 100644
--- a/docs/guide/start-looking-ahead.md
+++ b/docs/guide/start-looking-ahead.md
@@ -3,7 +3,7 @@ Looking Ahead
If you've read through the entire "Getting Started" chapter, you have now created a complete Yii application. In the process, you have learned how to implement some commonly
needed features, such as getting data from users via an HTML form, fetching data from a database, and
-displaying data in a paginated fashion. You have also learned how to use [Gii](tool-gii.md) to generate
+displaying data in a paginated fashion. You have also learned how to use [Gii](https://github.com/yiisoft/yii2-gii/blob/master/docs/guide/README.md) to generate
code automatically. Using Gii for code generation turns the bulk of your Web development process into a task as simple as just filling out some forms.
This section will summarize the Yii resources available to help you be more productive when using the framework.
@@ -27,6 +27,7 @@ This section will summarize the Yii resources available to help you be more prod
* Community
- Forum:
- IRC chat: The #yii channel on the freenode network ()
+ - Gitter chat:
- GitHub:
- Facebook:
- Twitter:
diff --git a/docs/guide/start-workflow.md b/docs/guide/start-workflow.md
index 00645a7905..335526b56d 100644
--- a/docs/guide/start-workflow.md
+++ b/docs/guide/start-workflow.md
@@ -11,11 +11,17 @@ how the code is organized, and how the application handles requests in general.
your application to be `http://hostname/index.php` or something similar.
For your needs, please adjust the URLs in our descriptions accordingly.
<<<<<<< HEAD
+<<<<<<< HEAD
=======
Note that unlike framework itself, after project template is installed it's all yours. You're free to add or delete
code and overall modify it as you need.
>>>>>>> yiichina/master
+=======
+
+Note that unlike framework itself, after project template is installed it's all yours. You're free to add or delete
+code and overall modify it as you need.
+>>>>>>> master
Functionality
@@ -23,7 +29,7 @@ Functionality
The basic application installed contains four pages:
-* The homepage, displayed when you access the URL `http://hostname/index.php`,
+* the homepage, displayed when you access the URL `http://hostname/index.php`,
* the "About" page,
* the "Contact" page, which displays a contact form that allows end users to contact you via email,
* and the "Login" page, which displays a login form that can be used to authenticate end users. Try logging in
@@ -33,15 +39,20 @@ These pages share a common header and footer. The header contains a main menu ba
among different pages.
You should also see a toolbar at the bottom of the browser window.
-This is a useful [debugger tool](tool-debugger.md) provided by Yii to record and display a lot of debugging information, such as log messages, response statuses, the database queries run, and so on.
+This is a useful [debugger tool](https://github.com/yiisoft/yii2-debug/blob/master/docs/guide/README.md) provided by Yii to record and display a lot of debugging information, such as log messages, response statuses, the database queries run, and so on.
Additionally to the web application, there is a console script called `yii`, which is located in the applications base directory.
+<<<<<<< HEAD
This script can be used to run background and maintainance tasks for the application, which are described
<<<<<<< HEAD
in the [Console Application Section](tutoral-console.md).
=======
in the [Console Application Section](tutorial-console.md).
>>>>>>> yiichina/master
+=======
+This script can be used to run background and maintenance tasks for the application, which are described
+in the [Console Application Section](tutorial-console.md).
+>>>>>>> master
Application Structure
@@ -70,7 +81,7 @@ basic/ application base path
In general, the files in the application can be divided into two types: those under `basic/web` and those
under other directories. The former can be directly accessed via HTTP (i.e., in a browser), while the latter can not and should not be.
-Yii implements the [model-view-controller (MVC)](http://wikipedia.org/wiki/Model-view-controller) design pattern,
+Yii implements the [model-view-controller (MVC)](http://wikipedia.org/wiki/Model-view-controller) architectural pattern,
which is reflected in the above directory organization. The `models` directory contains all [model classes](structure-models.md),
the `views` directory contains all [view scripts](structure-views.md), and the `controllers` directory contains
all [controller classes](structure-controllers.md).
diff --git a/docs/guide/structure-application-components.md b/docs/guide/structure-application-components.md
index 103713b6ac..e45331e742 100644
--- a/docs/guide/structure-application-components.md
+++ b/docs/guide/structure-application-components.md
@@ -96,11 +96,15 @@ if you do not specify its class, the default one will be used.
Please refer to the [Handling Errors](runtime-handling-errors.md) section for more details.
* [[yii\i18n\Formatter|formatter]]: formats data when they are displayed to end users. For example, a number
may be displayed with thousand separator, a date may be formatted in long format.
+<<<<<<< HEAD
<<<<<<< HEAD
Please refer to the [Data Formatting](output-formatter.md) section for more details.
=======
Please refer to the [Data Formatting](output-formatting.md) section for more details.
>>>>>>> yiichina/master
+=======
+ Please refer to the [Data Formatting](output-formatting.md) section for more details.
+>>>>>>> master
* [[yii\i18n\I18N|i18n]]: supports message translation and formatting.
Please refer to the [Internationalization](tutorial-i18n.md) section for more details.
* [[yii\log\Dispatcher|log]]: manages log targets.
diff --git a/docs/guide/structure-applications.md b/docs/guide/structure-applications.md
index 276f22af71..53f9ca3159 100644
--- a/docs/guide/structure-applications.md
+++ b/docs/guide/structure-applications.md
@@ -10,13 +10,13 @@ the [entry script](structure-entry-scripts.md) and is globally accessible throug
There are two types of applications: [[yii\web\Application|Web applications]] and
[[yii\console\Application|console applications]]. As the names indicate, the former mainly handles
-Web requests while the latter console command requests.
+Web requests, while the latter handles console command requests.
## Application Configurations
When an [entry script](structure-entry-scripts.md) creates an application, it will load
-a [configuration](concept-configurations.md) and apply it to the application, like the following:
+a [configuration](concept-configurations.md) and apply it to the application, as follows:
```php
require(__DIR__ . '/../vendor/autoload.php');
@@ -53,14 +53,14 @@ and [[yii\base\Application::basePath|basePath]].
The [[yii\base\Application::id|id]] property specifies a unique ID that differentiates an application
from others. It is mainly used programmatically. Although not a requirement, for best interoperability
-it is recommended that you use alphanumeric characters only when specifying an application ID.
+it is recommended that you use only alphanumeric characters when specifying an application ID.
#### [[yii\base\Application::basePath|basePath]]
The [[yii\base\Application::basePath|basePath]] property specifies the root directory of an application.
It is the directory that contains all protected source code of an application system. Under this directory,
-you normally will see sub-directories such as `models`, `views`, `controllers`, which contain source code
+you normally will see sub-directories such as `models`, `views`, and `controllers`, which contain source code
corresponding to the MVC pattern.
You may configure the [[yii\base\Application::basePath|basePath]] property using a directory path
@@ -82,7 +82,7 @@ different applications.
This property allows you to define a set of [aliases](concept-aliases.md) in terms of an array.
The array keys are alias names, and the array values are the corresponding path definitions.
-For example,
+For example:
```php
[
@@ -93,8 +93,8 @@ For example,
]
```
-This property is provided such that you can define aliases in terms of application configurations instead of
-the method calls [[Yii::setAlias()]].
+This property is provided so that you can define aliases in terms of application configurations instead of
+by calling the [[Yii::setAlias()]] method.
#### [[yii\base\Application::bootstrap|bootstrap]]
@@ -106,13 +106,13 @@ you may list its ID as an element in this property.
Each component listed in this property may be specified in one of the following formats:
-- an application component ID as specified via [components](#components).
-- a module ID as specified via [modules](#modules).
-- a class name.
-- a configuration array.
+- an application component ID as specified via [components](#components),
+- a module ID as specified via [modules](#modules),
+- a class name,
+- a configuration array,
- an anonymous function that creates and returns a component.
-For example,
+For example:
```php
[
@@ -138,28 +138,33 @@ For example,
```
> Info: If a module ID is the same as an application component ID, the application component will be used during
- the bootstrapping process. If you want to use the module instead, you may specify it using an anonymous function
- like the following:
+> the bootstrapping process. If you want to use the module instead, you may specify it using an anonymous function
+> like the following:
+>
> ```php
-[
- function () {
- return Yii::$app->getModule('user');
- },
-]
-```
+> [
+> function () {
+> return Yii::$app->getModule('user');
+> },
+> ]
+> ```
During the bootstrapping process, each component will be instantiated. If the component class
implements [[yii\base\BootstrapInterface]], its [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] method
will also be called.
+<<<<<<< HEAD
<<<<<<< HEAD
Another practical example is in the application configuration for the [Basic Application Template](start-installation.md),
=======
Another practical example is in the application configuration for the [Basic Project Template](start-installation.md),
>>>>>>> yiichina/master
+=======
+Another practical example is in the application configuration for the [Basic Project Template](start-installation.md),
+>>>>>>> master
where the `debug` and `gii` modules are configured as bootstrapping components when the application is running
-in development environment,
+in the development environment:
```php
if (YII_ENV_DEV) {
@@ -183,7 +188,7 @@ a [controller action](structure-controllers.md) which should handle all user req
used when the application is in maintenance mode and needs to handle all incoming requests via a single action.
The configuration is an array whose first element specifies the route of the action.
-The rest of the array elements (key-value pairs) specify the parameters to be bound to the action. For example,
+The rest of the array elements (key-value pairs) specify the parameters to be bound to the action. For example:
```php
[
@@ -195,11 +200,12 @@ The rest of the array elements (key-value pairs) specify the parameters to be bo
]
```
+> Info: Debug panel on development environment will not work when this property is enabled
#### [[yii\base\Application::components|components]]
This is the single most important property. It allows you to register a list of named components
-called [application components](structure-application-components.md) that you can use in other places. For example,
+called [application components](structure-application-components.md) that you can use in other places. For example:
```php
[
@@ -219,7 +225,7 @@ Each application component is specified as a key-value pair in the array. The ke
while the value represents the component class name or [configuration](concept-configurations.md).
You can register any component with an application, and the component can later be accessed globally
-using the expression `\Yii::$app->ComponentID`.
+using the expression `\Yii::$app->componentID`.
Please read the [Application Components](structure-application-components.md) section for details.
@@ -262,7 +268,7 @@ be `app\controllers\admin\PostController`.
It is important that the fully qualified controller classes should be [autoloadable](concept-autoloading.md)
and the actual namespace of your controller classes match the value of this property. Otherwise,
-you will receive "Page Not Found" error when accessing the application.
+you will receive a "Page Not Found" error when accessing the application.
In case you want to break the convention as described above, you may configure the [controllerMap](#controllerMap)
property.
@@ -277,7 +283,7 @@ if your application needs to support multiple languages.
The value of this property determines various [internationalization](tutorial-i18n.md) aspects,
including message translation, date formatting, number formatting, etc. For example, the [[yii\jui\DatePicker]] widget
will use this property value by default to determine in which language the calendar should be displayed and how
-should the date be formatted.
+the date should be formatted.
It is recommended that you specify a language in terms of an [IETF language tag](http://en.wikipedia.org/wiki/IETF_language_tag).
For example, `en` stands for English, while `en-US` stands for English (United States).
@@ -290,7 +296,7 @@ More details about this property can be found in the [Internationalization](tuto
This property specifies the [modules](structure-modules.md) that the application contains.
The property takes an array of module classes or [configurations](concept-configurations.md) with the array keys
-being the module IDs. For example,
+being the module IDs. For example:
```php
[
@@ -313,8 +319,8 @@ Please refer to the [Modules](structure-modules.md) section for more details.
#### [[yii\base\Application::name|name]]
This property specifies the application name that may be displayed to end users. Unlike the
-[[yii\base\Application::id|id]] property which should take a unique value, the value of this property is mainly for
-display purpose and does not need to be unique.
+[[yii\base\Application::id|id]] property, which should take a unique value, the value of this property is mainly for
+display purposes; it does not need to be unique.
You do not always need to configure this property if none of your code is using it.
@@ -334,15 +340,15 @@ image size as a parameter like the following:
]
```
-Then in your code where you need to use the size value, you can simply use the code like the following:
+Then in your code where you need to use the size value, you can simply use code like the following:
```php
$size = \Yii::$app->params['thumbnail.size'];
$width = \Yii::$app->params['thumbnail.size'][0];
```
-Later if you decide to change the thumbnail size, you only need to modify it in the application configuration
-without touching any dependent code.
+Later if you decide to change the thumbnail size, you only need to modify it in the application configuration;
+you don't need to touch any dependent code.
#### [[yii\base\Application::sourceLanguage|sourceLanguage]]
@@ -359,9 +365,9 @@ More details about this property can be found in the [Internationalization](tuto
#### [[yii\base\Application::timeZone|timeZone]]
-This property is provided as an alternative way of setting the default time zone of PHP runtime.
+This property is provided as an alternative way of setting the default time zone of the PHP runtime.
By configuring this property, you are essentially calling the PHP function
-[date_default_timezone_set()](http://php.net/manual/en/function.date-default-timezone-set.php). For example,
+[date_default_timezone_set()](http://php.net/manual/en/function.date-default-timezone-set.php). For example:
```php
[
@@ -372,28 +378,28 @@ By configuring this property, you are essentially calling the PHP function
#### [[yii\base\Application::version|version]]
-This property specifies the version of the application. It defaults to `'1.0'`. You do not always need to configure
+This property specifies the version of the application. It defaults to `'1.0'`. You do not need to configure
this property if none of your code is using it.
### Useful Properties
The properties described in this subsection are not commonly configured because their default values
-stipulate common conventions. However, you may still configure them in case you want to break the conventions.
+derive from common conventions. However, you may still configure them in case you want to break the conventions.
#### [[yii\base\Application::charset|charset]]
-This property specifies the charset that the application uses. The default value is `'UTF-8'` which should
-be kept as is for most applications unless you are working with some legacy systems that use a lot of non-unicode data.
+This property specifies the charset that the application uses. The default value is `'UTF-8'`, which should
+be kept as-is for most applications unless you are working with a legacy system that uses a lot of non-Unicode data.
#### [[yii\base\Application::defaultRoute|defaultRoute]]
This property specifies the [route](runtime-routing.md) that an application should use when a request
-does not specify one. The route may consist of child module ID, controller ID, and/or action ID.
-For example, `help`, `post/create`, `admin/post/create`. If action ID is not given, it will take the default
-value as specified in [[yii\base\Controller::defaultAction]].
+does not specify one. The route may consist of a child module ID, a controller ID, and/or an action ID.
+For example, `help`, `post/create`, or `admin/post/create`. If an action ID is not given, this property will take
+the default value specified in [[yii\base\Controller::defaultAction]].
For [[yii\web\Application|Web applications]], the default value of this property is `'site'`, which means
the `SiteController` controller and its default action should be used. As a result, if you access
@@ -409,13 +415,17 @@ without providing any arguments, it will display the help information.
This property specifies the list of [extensions](structure-extensions.md) that are installed and used by the application.
By default, it will take the array returned by the file `@vendor/yiisoft/extensions.php`. The `extensions.php` file
<<<<<<< HEAD
+<<<<<<< HEAD
is generated and maintained automatically when you use [Composer](http://getcomposer.org) to install extensions.
=======
is generated and maintained automatically when you use [Composer](https://getcomposer.org) to install extensions.
>>>>>>> yiichina/master
+=======
+is generated and maintained automatically when you use [Composer](https://getcomposer.org) to install extensions.
+>>>>>>> master
So in most cases, you do not need to configure this property.
-In the special case when you want to maintain extensions manually, you may configure this property like the following:
+In the special case when you want to maintain extensions manually, you may configure this property as follows:
```php
[
@@ -463,14 +473,14 @@ You may configure it as a directory or a path [alias](concept-aliases.md).
#### [[yii\base\Application::runtimePath|runtimePath]]
-This property specifies the path where temporary files, such as log files, cache files, can be generated.
+This property specifies the path where temporary files, such as log files and cache files, can be generated.
The default value is the directory represented by the alias `@app/runtime`.
You may configure it as a directory or a path [alias](concept-aliases.md). Note that the runtime path must
be writable by the process running the application. And the path should be protected from being accessed
-by end users because the temporary files under it may contain sensitive information.
+by end users, because the temporary files under it may contain sensitive information.
-To simplify accessing to this path, Yii has predefined a path alias named `@runtime` for it.
+To simplify access to this path, Yii has predefined a path alias named `@runtime` for it.
#### [[yii\base\Application::viewPath|viewPath]]
@@ -481,18 +491,22 @@ represented by the alias `@app/views`. You may configure it as a directory or a
#### [[yii\base\Application::vendorPath|vendorPath]]
+<<<<<<< HEAD
<<<<<<< HEAD
This property specifies the vendor directory managed by [Composer](http://getcomposer.org). It contains
=======
This property specifies the vendor directory managed by [Composer](https://getcomposer.org). It contains
>>>>>>> yiichina/master
+=======
+This property specifies the vendor directory managed by [Composer](https://getcomposer.org). It contains
+>>>>>>> master
all third party libraries used by your application, including the Yii framework. The default value is
the directory represented by the alias `@app/vendor`.
You may configure this property as a directory or a path [alias](concept-aliases.md). When you modify
this property, make sure you also adjust the Composer configuration accordingly.
-To simplify accessing to this path, Yii has predefined a path alias named `@vendor` for it.
+To simplify access to this path, Yii has predefined a path alias named `@vendor` for it.
#### [[yii\console\Application::enableCoreCommands|enableCoreCommands]]
@@ -503,8 +517,8 @@ whether the core commands included in the Yii release should be enabled. The def
## Application Events
-An application triggers several events during the lifecycle of handling an request. You may attach event
-handlers to these events in application configurations like the following,
+An application triggers several events during the lifecycle of handling a request. You may attach event
+handlers to these events in application configurations as follows:
```php
[
@@ -518,7 +532,7 @@ The use of the `on eventName` syntax is described in the [Configurations](concep
section.
Alternatively, you may attach event handlers during the [bootstrapping process](runtime-bootstrapping.md)
-after the application instance is created. For example,
+after the application instance is created. For example:
```php
\Yii::$app->on(\yii\base\Application::EVENT_BEFORE_REQUEST, function ($event) {
@@ -554,7 +568,7 @@ The actual event name is `beforeAction`.
The event parameter is an instance of [[yii\base\ActionEvent]]. An event handler may set
the [[yii\base\ActionEvent::isValid]] property to be `false` to stop running the action.
-For example,
+For example:
```php
[
@@ -570,7 +584,7 @@ For example,
Note that the same `beforeAction` event is also triggered by [modules](structure-modules.md)
and [controllers](structure-controllers.md). Application objects are the first ones
triggering this event, followed by modules (if any), and finally controllers. If an event handler
-sets [[yii\base\ActionEvent::isValid]] to be `false`, all the following events will NOT be triggered.
+sets [[yii\base\ActionEvent::isValid]] to be `false`, all of the subsequent events will NOT be triggered.
### [[yii\base\Application::EVENT_AFTER_ACTION|EVENT_AFTER_ACTION]]
@@ -580,7 +594,7 @@ The actual event name is `afterAction`.
The event parameter is an instance of [[yii\base\ActionEvent]]. Through
the [[yii\base\ActionEvent::result]] property, an event handler may access or modify the action result.
-For example,
+For example:
```php
[
@@ -617,7 +631,7 @@ an application will undergo the following lifecycle:
3. The entry script calls [[yii\base\Application::run()]] to run the application:
* Trigger the [[yii\base\Application::EVENT_BEFORE_REQUEST|EVENT_BEFORE_REQUEST]] event.
* Handle the request: resolve the request into a [route](runtime-routing.md) and the associated parameters;
- create the module, controller and action objects as specified by the route; and run the action.
+ create the module, controller, and action objects as specified by the route; and run the action.
* Trigger the [[yii\base\Application::EVENT_AFTER_REQUEST|EVENT_AFTER_REQUEST]] event.
* Send response to the end user.
4. The entry script receives the exit status from the application and completes the request processing.
diff --git a/docs/guide/structure-assets.md b/docs/guide/structure-assets.md
index 51ab8ca541..10b176b07d 100644
--- a/docs/guide/structure-assets.md
+++ b/docs/guide/structure-assets.md
@@ -25,11 +25,15 @@ its corresponding fully qualified PHP class name (without the leading backslash)
be [autoloadable](concept-autoloading.md). It usually specifies where the assets are located, what CSS and
JavaScript files the bundle contains, and how the bundle depends on other bundles.
+<<<<<<< HEAD
<<<<<<< HEAD
The following code defines the main asset bundle used by [the basic application template](start-installation.md):
=======
The following code defines the main asset bundle used by [the basic project template](start-installation.md):
>>>>>>> yiichina/master
+=======
+The following code defines the main asset bundle used by [the basic project template](start-installation.md):
+>>>>>>> master
```php
publishOptions['beforeCopy'] = function ($from, $to) {
- $dirname = basename(dirname($from));
- return $dirname === 'fonts' || $dirname === 'css';
- };
- }
+ ];
+ public $publishOptions = [
+ 'only' => [
+ 'fonts/',
+ 'css/',
+ ]
+ ];
}
```
The above example defines an asset bundle for the ["fontawesome" package](http://fontawesome.io/). By specifying
-the `beforeCopy` publishing option, only the `fonts` and `css` subdirectories will be published.
+the `only` publishing option, only the `fonts` and `css` subdirectories will be published.
### Bower and NPM Assets
diff --git a/docs/guide/structure-controllers.md b/docs/guide/structure-controllers.md
index 4290493c03..67e9d58d81 100644
--- a/docs/guide/structure-controllers.md
+++ b/docs/guide/structure-controllers.md
@@ -67,9 +67,9 @@ the `create` view through which users can provide the needed input.
End users address actions through the so-called *routes*. A route is a string that consists of the following parts:
* a module ID: this exists only if the controller belongs to a non-application [module](structure-modules.md);
-* a controller ID: a string that uniquely identifies the controller among all controllers within the same application
+* a [controller ID](#controller-ids): a string that uniquely identifies the controller among all controllers within the same application
(or the same module if the controller belongs to a module);
-* an action ID: a string that uniquely identifies the action among all actions within the same controller.
+* an [action ID](#action-ids): a string that uniquely identifies the action among all actions within the same controller.
Routes take the following format:
@@ -112,55 +112,59 @@ For this reason, controller IDs are often nouns referring to the types of the re
For example, you may use `article` as the ID of a controller that handles article data.
By default, controller IDs should contain these characters only: English letters in lower case, digits,
-underscores, dashes and forward slashes. For example, `article` and `post-comment` are both valid controller IDs,
+underscores, hyphens, and forward slashes. For example, `article` and `post-comment` are both valid controller IDs,
while `article?`, `PostComment`, `admin\post` are not.
A controller ID may also contain a subdirectory prefix. For example, `admin/article` stands for an `article` controller
in the `admin` subdirectory under the [[yii\base\Application::controllerNamespace|controller namespace]].
-Valid characters for subdirectory prefixes include: English letters in lower and upper cases, digits, underscores and
+Valid characters for subdirectory prefixes include: English letters in lower and upper cases, digits, underscores, and
forward slashes, where forward slashes are used as separators for multi-level subdirectories (e.g. `panels/admin`).
### Controller Class Naming
-Controller class names can be derived from controller IDs according to the following rules:
+Controller class names can be derived from controller IDs according to the following procedure:
-* Turn the first letter in each word separated by dashes into upper case. Note that if the controller ID
+1. Turn the first letter in each word separated by hyphens into upper case. Note that if the controller ID
contains slashes, this rule only applies to the part after the last slash in the ID.
-* Remove dashes and replace any forward slashes with backward slashes.
-* Append the suffix `Controller`.
-* And prepend the [[yii\base\Application::controllerNamespace|controller namespace]].
+2. Remove hyphens and replace any forward slashes with backward slashes.
+3. Append the suffix `Controller`.
+4. Prepend the [[yii\base\Application::controllerNamespace|controller namespace]].
+<<<<<<< HEAD
<<<<<<< HEAD
The followings are some examples, assuming the [[yii\base\Application::controllerNamespace|controller namespace]]
=======
The following are some examples, assuming the [[yii\base\Application::controllerNamespace|controller namespace]]
>>>>>>> yiichina/master
+=======
+The following are some examples, assuming the [[yii\base\Application::controllerNamespace|controller namespace]]
+>>>>>>> master
takes the default value `app\controllers`:
-* `article` derives `app\controllers\ArticleController`;
-* `post-comment` derives `app\controllers\PostCommentController`;
-* `admin/post-comment` derives `app\controllers\admin\PostCommentController`;
-* `adminPanels/post-comment` derives `app\controllers\adminPanels\PostCommentController`.
+* `article` becomes `app\controllers\ArticleController`;
+* `post-comment` becomes `app\controllers\PostCommentController`;
+* `admin/post-comment` becomes `app\controllers\admin\PostCommentController`;
+* `adminPanels/post-comment` becomes `app\controllers\adminPanels\PostCommentController`.
Controller classes must be [autoloadable](concept-autoloading.md). For this reason, in the above examples,
the `article` controller class should be saved in the file whose [alias](concept-aliases.md)
-is `@app/controllers/ArticleController.php`; while the `admin/post2-comment` controller should be
-in `@app/controllers/admin/Post2CommentController.php`.
+is `@app/controllers/ArticleController.php`; while the `admin/post-comment` controller should be
+in `@app/controllers/admin/PostCommentController.php`.
-> Info: The last example `admin/post2-comment` shows how you can put a controller under a sub-directory
+> Info: The last example `admin/post-comment` shows how you can put a controller under a sub-directory
of the [[yii\base\Application::controllerNamespace|controller namespace]]. This is useful when you want
to organize your controllers into several categories and you do not want to use [modules](structure-modules.md).
### Controller Map
-You can configure [[yii\base\Application::controllerMap|controller map]] to overcome the constraints
-of the controller IDs and class names described above. This is mainly useful when you are using some
-third-party controllers which you do not have control over their class names.
+You can configure the [[yii\base\Application::controllerMap|controller map]] to overcome the constraints
+of the controller IDs and class names described above. This is mainly useful when you are using
+third-party controllers and you do not have control over their class names.
-You may configure [[yii\base\Application::controllerMap|controller map]] in the
-[application configuration](structure-applications.md#application-configurations) like the following:
+You may configure the [[yii\base\Application::controllerMap|controller map]] in the
+[application configuration](structure-applications.md#application-configurations). For example:
```php
[
@@ -183,7 +187,7 @@ You may configure [[yii\base\Application::controllerMap|controller map]] in the
Each application has a default controller specified via the [[yii\base\Application::defaultRoute]] property.
When a request does not specify a [route](#routes), the route specified by this property will be used.
For [[yii\web\Application|Web applications]], its value is `'site'`, while for [[yii\console\Application|console applications]],
-it is `help`. Therefore, if a URL is `http://hostname/index.php`, it means the `site` controller will handle the request.
+it is `help`. Therefore, if a URL is `http://hostname/index.php`, then the `site` controller will handle the request.
You may change the default controller with the following [application configuration](structure-applications.md#application-configurations):
@@ -198,7 +202,7 @@ You may change the default controller with the following [application configurat
Creating actions can be as simple as defining the so-called *action methods* in a controller class. An action method is
a *public* method whose name starts with the word `action`. The return value of an action method represents
-the response data to be sent to end users. The following code defines two actions `index` and `hello-world`:
+the response data to be sent to end users. The following code defines two actions, `index` and `hello-world`:
```php
namespace app\controllers;
@@ -222,16 +226,16 @@ class SiteController extends Controller
### Action IDs
-An action is often designed to perform a particular manipulation about a resource. For this reason,
+An action is often designed to perform a particular manipulation of a resource. For this reason,
action IDs are usually verbs, such as `view`, `update`, etc.
By default, action IDs should contain these characters only: English letters in lower case, digits,
-underscores and dashes. The dashes in an actionID are used to separate words. For example,
-`view`, `update2`, `comment-post` are all valid action IDs, while `view?`, `Update` are not.
+underscores, and hyphens. (You can use hyphens to separate words.) For example,
+`view`, `update2`, and `comment-post` are all valid action IDs, while `view?` and `Update` are not.
You can create actions in two ways: inline actions and standalone actions. An inline action is
defined as a method in the controller class, while a standalone action is a class extending
-[[yii\base\Action]] or its child class. Inline actions take less effort to create and are often preferred
+[[yii\base\Action]] or its child classes. Inline actions take less effort to create and are often preferred
if you have no intention to reuse these actions. Standalone actions, on the other hand, are mainly
created to be used in different controllers or be redistributed as [extensions](structure-extensions.md).
@@ -240,11 +244,11 @@ created to be used in different controllers or be redistributed as [extensions](
Inline actions refer to the actions that are defined in terms of action methods as we just described.
-The names of the action methods are derived from action IDs according to the following criteria:
+The names of the action methods are derived from action IDs according to the following procedure:
-* Turn the first letter in each word of the action ID into upper case;
-* Remove dashes;
-* Prepend the prefix `action`.
+1. Turn the first letter in each word of the action ID into upper case.
+2. Remove hyphens.
+3. Prepend the prefix `action`.
For example, `index` becomes `actionIndex`, and `hello-world` becomes `actionHelloWorld`.
@@ -288,7 +292,7 @@ As you can see, the `actions()` method should return an array whose keys are act
action class names or [configurations](concept-configurations.md). Unlike inline actions, action IDs for standalone
actions can contain arbitrary characters, as long as they are declared in the `actions()` method.
-To create a standalone action class, you should extend [[yii\base\Action]] or its child class, and implement
+To create a standalone action class, you should extend [[yii\base\Action]] or a child class, and implement
a public method named `run()`. The role of the `run()` method is similar to that of an action method. For example,
```php
@@ -309,7 +313,7 @@ class HelloWorldAction extends Action
### Action Results
-The return value of an action method or the `run()` method of a standalone action is significant. It stands
+The return value of an action method or of the `run()` method of a standalone action is significant. It stands
for the result of the corresponding action.
The return value can be a [response](runtime-responses.md) object which will be sent to the end user as the response.
@@ -424,25 +428,25 @@ to fulfill the request:
* If the action ID is found to match an action method, an inline action will be created;
* Otherwise an [[yii\base\InvalidRouteException]] exception will be thrown.
3. The controller sequentially calls the `beforeAction()` method of the application, the module (if the controller
- belongs to a module) and the controller.
- * If one of the calls returns false, the rest of the uncalled `beforeAction()` will be skipped and the
+ belongs to a module), and the controller.
+ * If one of the calls returns false, the rest of the uncalled `beforeAction()` methods will be skipped and the
action execution will be cancelled.
* By default, each `beforeAction()` method call will trigger a `beforeAction` event to which you can attach a handler.
-4. The controller runs the action:
- * The action parameters will be analyzed and populated from the request data;
+4. The controller runs the action.
+ * The action parameters will be analyzed and populated from the request data.
5. The controller sequentially calls the `afterAction()` method of the controller, the module (if the controller
- belongs to a module) and the application.
+ belongs to a module), and the application.
* By default, each `afterAction()` method call will trigger an `afterAction` event to which you can attach a handler.
6. The application will take the action result and assign it to the [response](runtime-responses.md).
## Best Practices
-In a well-designed application, controllers are often very thin with each action containing only a few lines of code.
+In a well-designed application, controllers are often very thin, with each action containing only a few lines of code.
If your controller is rather complicated, it usually indicates that you should refactor it and move some code
to other classes.
-In summary, controllers
+Here are some specific best practices. Controllers
* may access the [request](runtime-requests.md) data;
* may call methods of [models](structure-models.md) and other service components with request data;
diff --git a/docs/guide/structure-entry-scripts.md b/docs/guide/structure-entry-scripts.md
index d667ea3ade..ca588ba925 100644
--- a/docs/guide/structure-entry-scripts.md
+++ b/docs/guide/structure-entry-scripts.md
@@ -1,7 +1,7 @@
Entry Scripts
=============
-Entry scripts are the first chain in the application bootstrapping process. An application (either
+Entry scripts are the first step in the application bootstrapping process. An application (either
Web application or console application) has a single entry script. End users make requests to
entry scripts which instantiate application instances and forward the requests to them.
@@ -17,10 +17,14 @@ Entry scripts mainly do the following work:
* Define global constants;
<<<<<<< HEAD
+<<<<<<< HEAD
* Register [Composer autoloader](http://getcomposer.org/doc/01-basic-usage.md#autoloading);
=======
* Register [Composer autoloader](https://getcomposer.org/doc/01-basic-usage.md#autoloading);
>>>>>>> yiichina/master
+=======
+* Register [Composer autoloader](https://getcomposer.org/doc/01-basic-usage.md#autoloading);
+>>>>>>> master
* Include the [[Yii]] class file;
* Load application configuration;
* Create and configure an [application](structure-applications.md) instance;
@@ -29,11 +33,15 @@ Entry scripts mainly do the following work:
## Web Applications
+<<<<<<< HEAD
<<<<<<< HEAD
The following is the code in the entry script for the [Basic Web Application Template](start-installation.md).
=======
The following is the code in the entry script for the [Basic Web Project Template](start-installation.md).
>>>>>>> yiichina/master
+=======
+The following is the code in the entry script for the [Basic Web Project Template](start-installation.md).
+>>>>>>> master
```php