Merge remote-tracking branch 'upstream/master' into add-tests

docs/guide/apps-advanced.md

@@ -5,6 +5,42 @@ This template is for large projects developed in teams where backend is divided
 to multiple servers etc. This application template also goes a bit further regarding features and provides essential
 database, signup and password restore out of the box.
 
+Installation
+------------
+
+### Install via Composer
+
+If you do not have [Composer](http://getcomposer.org/), you may download it from
+[http://getcomposer.org/](http://getcomposer.org/) or run the following command on Linux/Unix/MacOS:
+
+~~~
+curl -s http://getcomposer.org/installer | php
+~~~
+
+You can then install the application using the following command:
+
+~~~
+php composer.phar create-project --stability=dev yiisoft/yii2-app-advanced /path/to/yii-application
+~~~
+
+Getting started
+---------------
+
+After you install the application, you have to conduct the following steps to initialize
+the installed application. You only need to do these once for all.
+
+1. Execute the `init` command and select `dev` as environment.
+---
+php /path/to/yii-application/init
+---
+2. Create a new database. It is assumed that MySQL InnoDB is used. If not, adjust `console/migrations/m130524_201442_init.php`.
+3. In `common/config/params.php` set your database details in `components.db` values.
+
+4. Set document roots of your Web server:
+
+- for frontend `/path/to/yii-application/frontend/web/` and using the URL `http://frontend/`
+- for backend `/path/to/yii-application/backend/web/` and using the URL `http://backend/`
+
 Directory structure
 -------------------
 

docs/guide/apps-basic.md

@@ -7,6 +7,24 @@ The application has four pages: the homepage, the about page, the contact page a
 The contact page displays a contact form that users can fill in to submit their inquiries to the webmaster,
 and the login page allows users to be authenticated before accessing privileged contents.
 
+Installation
+------------
+
+If you do not have [Composer](http://getcomposer.org/), you may download it from
+[http://getcomposer.org/](http://getcomposer.org/) or run the following command on Linux/Unix/MacOS:
+
+~~~
+curl -s http://getcomposer.org/installer | php
+~~~
+
+You can then install the Bootstrap Application using the following command:
+
+~~~
+php composer.phar create-project --stability=dev yiisoft/yii2-app-basic /path/to/yii-application
+~~~
+
+Now set document root directory of your Web server to /path/to/yii-application/web and you should be able to access the application using the URL `http://localhost/`.
+
 Directory structure
 -------------------
 
@@ -139,4 +157,4 @@ For example, to use markdown helper you need to add `michelf/php-markdown`. All
 [packagist.org](https://packagist.org/) so feel free to browse the website for useful code.
 
 After your `composer.json` is changed you can run `php composer.phar update`, wait till packages are downloaded and
-installed and then just use them. Autoloading of classes will be handled automatically.
+installed and then just use them. Autoloading of classes will be handled automatically.

docs/guide/bootstrap-widgets.md

@@ -1,6 +1,60 @@
-Twitter Bootstrap widgets
+Bootstrap widgets
-=========================
+=================
 
-Overview
+Yii includes support of [Bootstrap 3](http://getbootstrap.com/) markup and components framework out of the box. It is an
---------
+excellent framework that allows you to speed up development a lot.
 
+Bootstrap is generally about two parts:
+
+- Basics such as grid system, typography, helper classes and responsive utilities.
+- Ready to use components such as menus, pagination, modal boxes, tabs etc.
+
+Basics
+------
+
+Yii doesn't wrap bootstrap basics into PHP code since HTML is very simple by itself in this case. You can find details
+about using the basics at [bootstrap documentation website](http://getbootstrap.com/css/). Still Yii provides a
+convenient way to include bootstrap assets in your pages with a single line added to `AppAsset.php` located in your
+`config` directory:
+
+```php
+public $depends = array(
+	'yii\web\YiiAsset',
+	'yii\bootstrap\BootstrapAsset', // this line
+);
+```
+
+Using bootstrap through Yii asset manager allows you to combine and minimize its resources with your own ones when
+needed.
+
+Yii widgets
+-----------
+
+Most complex bootstrap components are wrapped into Yii widgets to allow more robust syntax and integrate with
+framework features. All widgets belong to `\yii\bootstrap` namespace. Let's review these.
+
+### Alert
+
+### Button
+
+### ButtonDropdown
+
+### ButtonGroup
+
+### Carousel
+
+### Collapse
+
+### Dropdown
+
+### Modal
+
+### Nav
+
+### NavBar
+
+### Progress
+
+### Tabs
+
+### Typeahead

docs/guide/caching.md

@@ -119,7 +119,7 @@ public function getCachedData()
 	$value = Yii::$app->getCache()->get($key);
 	if ($value === false) {
 		$value = /* regenerate value because it is not found in cache and then save it in cache for later use */;
-		Yii::$app->cache->set($id, $value);
+		Yii::$app->cache->set($key, $value);
 	}
 	return $value;
 }

docs/guide/installation.md

@@ -117,7 +117,10 @@ server {
             set $fsn $fastcgi_script_name;
         }
 
+        #for php-cgi
         fastcgi_pass   127.0.0.1:9000;
+        #for php-fpm
+        #fastcgi_pass unix:/var/run/php5-fpm.sock;
         include fastcgi_params;
         fastcgi_param  SCRIPT_FILENAME  $document_root$fsn;
 

docs/guide/model.md

@@ -143,6 +143,9 @@ class EmployeeController extends \yii\web\Controller
 }
 ```
 
+In the example above we are using [Active Record](active-record.md). For basic form models it's rarely needed to
+use scenarios since form model is typically used for a single form.
+
 Validation
 ----------
 

docs/guide/overview.md

@@ -5,7 +5,7 @@ Yii is a high-performance, component-based PHP framework for developing
 large-scale Web applications rapidly. It enables maximum reusability in Web
 programming and can significantly accelerate your Web application development
 process. The name Yii (pronounced `Yee` or `[ji:]`) is an acronym for
-"**Yes It Is!**".
+**Yes It Is!**.
 
 
 Requirements

docs/guide/view.md

@@ -0,0 +1,95 @@
+View
+====
+
+View is an important part of MVC and is reponsible for how data is presented to the end user.
+
+Basics
+------
+
+Yii uses PHP in view templates by default so in a web application a view typically contains some HTML, `echo`, `foreach`
+and such basic constructs. It may also contain widget calls. Using complex code in views is considered a bad practice.
+Such code should be moved to controller or widgets.
+
+View is typically called from controller action like the following:
+
+```php
+public function actionIndex()
+{
+	return $this->render('index', array(
+		'username' => 'samdark',
+	));
+}
+```
+
+First argument is the view name. In context of the controller Yii will search for its views in `views/site/` where `site`
+is controller ID. For details on how view name is resolved please refer to [yii\base\Controller::render] method.
+Second argument is data array that contains key-value pairs. Value is available in the view as a variable named the same
+as the corresponding key.
+
+So the view for the action above should be in `views/site/index.php` and can be something like:
+
+```php
+<p>Hello, <?php echo $username?>!</p>
+```
+
+Intead of just scalar values you can pass anything else such as arrays or objects.
+
+Layout
+------
+
+Partials
+--------
+
+
+Widgets
+-------
+
+Security
+--------
+
+One of the main security principles is to always escape output. If violated it leads to script execution and,
+most probably, to cross-site scripting known as XSS leading to leaking of admin passwords, making a user to automatically
+perform actions etc.
+
+Yii provides a good toolset in order help you escaping your output. The very basic thing to escape is a text without any
+markup. You can deal with it like the following:
+
+```php
+<?php
+use yii\helpers\Html;
+?>
+
+<div class="username">
+	<?php echo Html::encode($user->name); ?>
+</div>
+```
+
+When you want to render HTML it becomes complex so we're delegating the task to excellent
+[HTMLPurifier](http://htmlpurifier.org/) library. In order to use it you need to modify your `composer.json` first by
+adding the following to `require`:
+
+```javascript
+"ezyang/htmlpurifier": "v4.5.0"
+```
+
+After it's done run `php composer.phar install` and wait till package is downloaded. Now everything is prepared to use
+Yii's HtmlPurifier helper:
+
+```php
+<?php
+use yii\helpers\HtmlPurifier;
+?>
+
+<div class="post">
+	<?php echo HtmlPurifier::process($post->text); ?>
+</div>
+```
+
+Note that besides HTMLPurifier does excellent job making output safe it's not very fast so consider
+[caching result](caching.md).
+
+Alternative template languages
+------------------------------
+
+There are offlicial extensions for [Smarty](http://www.smarty.net/) and [Twig](http://twig.sensiolabs.org/). In order
+to learn more refer to [Using template engines](template.md) section of the guide.

extensions/composer/README.md

@@ -1,5 +1,5 @@
 Yii 2.0 Public Preview - Composer Installer
-======================
+===========================================
 
 Thank you for choosing Yii - a high-performance component-based PHP framework.
 
@@ -13,33 +13,32 @@ without prior notices. **Yii 2.0 is not ready for production use yet.**
 
 This is the yii2 composer installer.
 
+
 Installation
-----------------
+------------
 
 This extension offers you enhanced composer handling for your yii2-project. It will therefor require you to use composer.
 
 `
-php composer.phar require yiisoft/yii2-composer *
+php composer.phar require yiisoft/yii2-composer "*"
 `
 
 *Note: You might have to run `php composer.phar selfupdate` before using this extension.*
 
 
 Usage & Documentation
------------
+---------------------
+
 This extensions allows you to hook to certain composer events and prepare your yii2-app for usage.
 
 After the package is installed, the composer.json file has to be modified to enable this extension.
 
 To see it in action take a look at the example apps in the repository:
 
-[Basic](https://github.com/suralc/yii2/blob/master/apps/basic/composer.json#L27)
+- [Basic](https://github.com/suralc/yii2/blob/master/apps/basic/composer.json#L27)
-[Advanced](https://github.com/suralc/yii2/blob/extensions-readme/apps/advanced/composer.json)
+- [Advanced](https://github.com/suralc/yii2/blob/extensions-readme/apps/advanced/composer.json)
-
-However it might be useful to read through the official composer [documentation](http://getcomposer.org/doc/articles/scripts.md) to understand what this extension can to for you and what it can't. 
-
-You can also use this as an template to create your own composer additions to ease development and deployment of your app.
-
-
 
+However it might be useful to read through the official composer [documentation](http://getcomposer.org/doc/articles/scripts.md)
+to understand what this extension can do for you and what it can't.
 
+You can also use this as a template to create your own composer additions to ease development and deployment of your app.

extensions/jui/README.md

@@ -1,5 +1,5 @@
 Yii 2.0 Public Preview - JUI Extension
-======================
+======================================
 
 Thank you for choosing Yii - a high-performance component-based PHP framework.
 
@@ -13,13 +13,15 @@ without prior notices. **Yii 2.0 is not ready for production use yet.**
 
 This is the yii2-jui extension.
 
+
 Installation
-----------------
+------------
+
 The preferred way to install this extension is [composer](http://getcomposer.org/download/).
 
 Either run
 ```
-php composer.phar require yiisoft/yii2-jui*
+php composer.phar require yiisoft/yii2-jui "*"
 ```
 
 or add
@@ -33,23 +35,21 @@ to the require section of your composer.json.
 
 
 Usage & Documentation
------------
+---------------------
 
 This extension provides multiple widgets to work with jquery.ui, as well as a set of compatible jquery.ui files.
 
 You can use these widgets in your view files after you have registered the corresponding assets.
 
 Example:
------------
+
 ```php
 echo ProgressBar::widget(array(
 	'clientOptions' => array(
 		'value' => 75,
 	),
 ));
+```
 
-For further instructions refer to the guide (once it is finished)
+For further instructions refer to the yii guide.
-
-
-
 

extensions/mutex/README.md

@@ -1,5 +1,5 @@
 Yii 2.0 Public Preview - Mutex Extension
-======================
+========================================
 
 Thank you for choosing Yii - a high-performance component-based PHP framework.
 
@@ -13,13 +13,15 @@ without prior notices. **Yii 2.0 is not ready for production use yet.**
 
 This is the yii2-mutex extension.
 
+
 Installation
-----------------
+------------
+
 The prefered way to install this extension is through [composer](http://getcomposer.org/download/).
 
 Either run
 ```
-php composer.phar require yiisoft/yii2-mutex *
+php composer.phar require yiisoft/yii2-mutex "*"
 ```
 
 or add
@@ -33,12 +35,8 @@ to the require section of your composer.json.
 
 
 Usage & Documentation
------------
+---------------------
 
 This component can be used to perform actions similar to the concept of [mutual exclusion](http://en.wikipedia.org/wiki/Mutual_exclusion).
 
-For concrete examples and advanced usage refer to the guide.
+For concrete examples and advanced usage refer to the yii guide.
-
-
-
-

extensions/smarty/README.md

@@ -1,5 +1,5 @@
 Yii 2.0 Public Preview - Smarty View Renderer
-======================
+=============================================
 
 Thank you for choosing Yii - a high-performance component-based PHP framework.
 
@@ -13,13 +13,15 @@ without prior notices. **Yii 2.0 is not ready for production use yet.**
 
 This is the yii2-smarty extension.
 
+
 Installation
-----------------
+------------
+
 The prefered way to install this extension is through [composer](http://getcomposer.org/download/).
 
 Either run
 ```
-php composer.phar require yiisoft/yii2-smarty *
+php composer.phar require yiisoft/yii2-smarty "*"
 ```
 
 or add
@@ -33,12 +35,13 @@ to the require section of your composer.json.
 
 
 Usage & Documentation
------------
+---------------------
 
 This extension has to be registered prior to usage.
 To enable this view renderer add it to the $rendereres property of your view object.
 
-Example: 
+Example:
+
 ```php
 <?php
 // config.php
@@ -58,8 +61,4 @@ return array(
 );
 ```
 
-For further instructions refer to the related section in the guide.
+For further instructions refer to the related section in the yii guide.
-
-
-
-

extensions/twig/README.md

@@ -1,5 +1,5 @@
 Yii 2.0 Public Preview - Twig View Renderer
-======================
+===========================================
 
 Thank you for choosing Yii - a high-performance component-based PHP framework.
 
@@ -13,13 +13,15 @@ without prior notices. **Yii 2.0 is not ready for production use yet.**
 
 This is the yii2-twig extension.
 
+
 Installation
-----------------
+------------
+
 The prefered way to install this extension is through [composer](http://getcomposer.org/download/).
 
 Either run
 ```
-php composer.phar require yiisoft/yii2-twig *
+php composer.phar require yiisoft/yii2-twig "*"
 ```
 
 or add
@@ -33,7 +35,7 @@ to the require section of your composer.json.
 
 
 Usage & Documentation
------------
+---------------------
 
 This extension has to be registered prior to usage.
 To enable this view renderer add it to the $rendereres property of your view object.
@@ -59,6 +61,4 @@ return array(
 );
 ```
 
-For further instructions refer to the related section in the guide.
+For further instructions refer to the related section in the yii guide.
-
-

framework/yii/base/Formatter.php

@@ -314,11 +314,7 @@ class Formatter extends Component
 	protected function normalizeDatetimeValue($value)
 	{
 		if (is_string($value)) {
-			if (ctype_digit($value) || $value[0] === '-' && ctype_digit(substr($value, 1))) {
+			return is_numeric($value) ? (int)$value : strtotime($value);
-				return (int)$value;
-			} else {
-				return strtotime($value);
-			}
 		} elseif ($value instanceof DateTime) {
 			return $value->getTimestamp();
 		} else {

framework/yii/bootstrap/Dropdown.php

@@ -21,8 +21,9 @@ use yii\helpers\Html;
 class Dropdown extends Widget
 {
 	/**
-	 * @var array list of menu items in the dropdown. Each array element represents a single
+	 * @var array list of menu items in the dropdown. Each array element can be either an HTML string,
-	 * menu with the following structure:
+	 * or an array representing a single menu with the following structure:
+	 *
 	 * - label: string, required, the label of the item link
 	 * - url: string, optional, the url of the item link. Defaults to "#".
 	 * - linkOptions: array, optional, the HTML attributes of the item link.

framework/yii/helpers/HtmlBase.php

@@ -935,6 +935,30 @@ class HtmlBase
 	}
 
 	/**
+	 * Generates a tag that contains the first validation error of the specified model attribute.
+	 * Note that even if there is no validation error, this method will still return an empty error tag.
+	 * @param Model $model the model object
+	 * @param string $attribute the attribute name or expression. See [[getAttributeName()]] for the format
+	 * about attribute expression.
+	 * @param array $options the tag options in terms of name-value pairs. The values will be HTML-encoded
+	 * using [[encode()]]. If a value is null, the corresponding attribute will not be rendered.
+	 *
+	 * The following options are specially handled:
+	 *
+	 * - tag: this specifies the tag name. If not set, "p" will be used.
+	 *
+	 * @return string the generated label tag
+	 */
+	public static function error($model, $attribute, $options = array())
+	{
+		$attribute = static::getAttributeName($attribute);
+		$error = $model->getFirstError($attribute);
+		$tag = isset($options['tag']) ? $options['tag'] : 'p';
+		unset($options['tag']);
+		return Html::tag($tag, Html::encode($error), $options);
+	}
+
+	/**
 	 * Generates an input tag for the given model attribute.
 	 * This method will generate the "name" and "value" tag attributes automatically for the model attribute
 	 * unless they are explicitly specified in `$options`.

framework/yii/widgets/ActiveField.php

@@ -146,7 +146,6 @@ class ActiveField extends Component
 	protected function getClientOptions()
 	{
 		$enableClientValidation = $this->enableClientValidation || $this->enableClientValidation === null && $this->form->enableClientValidation;
-		$enableAjaxValidation = $this->enableAjaxValidation || $this->enableAjaxValidation === null && $this->form->enableAjaxValidation;
 		if ($enableClientValidation) {
 			$attribute = Html::getAttributeName($this->attribute);
 			$validators = array();
@@ -162,6 +161,7 @@ class ActiveField extends Component
 			}
 		}
 
+		$enableAjaxValidation = $this->enableAjaxValidation || $this->enableAjaxValidation === null && $this->form->enableAjaxValidation;
 		if ($enableAjaxValidation) {
 			$options['enableAjaxValidation'] = 1;
 		}
@@ -169,12 +169,7 @@ class ActiveField extends Component
 		if ($enableClientValidation && !empty($options['validate']) || $enableAjaxValidation) {
 			$inputID = Html::getInputId($this->model, $this->attribute);
 			$options['name'] = $inputID;
-			$names = array(
+			foreach (array('validateOnChange', 'validateOnType', 'validationDelay') as $name) {
-				'validateOnChange',
-				'validateOnType',
-				'validationDelay',
-			);
-			foreach ($names as $name) {
 				$options[$name] = $this->$name === null ? $this->form->$name : $this->$name;
 			}
 			$options['container'] = isset($this->selectors['container']) ? $this->selectors['container'] : ".field-$inputID";
@@ -216,22 +211,18 @@ class ActiveField extends Component
 	 * Note that even if there is no validation error, this method will still return an empty error tag.
 	 * @param array $options the tag options in terms of name-value pairs. It will be merged with [[errorOptions]].
 	 * The options will be rendered as the attributes of the resulting tag. The values will be HTML-encoded
-	 * using [[encode()]]. If a value is null, the corresponding attribute will not be rendered.
+	 * using [[Html::encode()]]. If a value is null, the corresponding attribute will not be rendered.
 	 *
 	 * The following options are specially handled:
 	 *
-	 * - tag: this specifies the tag name. If not set, "span" will be used.
+	 * - tag: this specifies the tag name. If not set, "p" will be used.
 	 *
 	 * @return string the generated label tag
 	 */
 	public function error($options = array())
 	{
 		$options = array_merge($this->errorOptions, $options);
-		$attribute = Html::getAttributeName($this->attribute);
+		return Html::error($this->model, $this->attribute, $options);
-		$error = $this->model->getFirstError($attribute);
-		$tag = isset($options['tag']) ? $options['tag'] : 'span';
-		unset($options['tag']);
-		return Html::tag($tag, Html::encode($error), $options);
 	}
 
 	/**