Merge pull request #2 from yiisoft/master

Merge from master

docs/guide/migration.md

@@ -1,3 +1,319 @@
 Database Migration
 ==================
 
+Like source code, the structure of a database is evolving as we develop and maintain
+a database-driven application. For example, during development, we may want to
+add a new table; or after the application is put into production, we may realize
+the need of adding an index on a column. It is important to keep track of these
+structural database changes (called **migration**) like we do with our source
+code. If the source code and the database are out of sync, it is very likely
+the whole system may break. For this reason, Yii provides a database migration
+tool that can keep track of database migration history, apply new migrations,
+or revert existing ones.
+
+The following steps show how we can use database migration during development:
+
+1. Tim creates a new migration (e.g. create a new table)
+2. Tim commits the new migration into source control system (e.g. GIT, Mercurial)
+3. Doug updates from source control system and receives the new migration
+4. Doug applies the migration to his local development database
+
+
+Yii supports database migration via the `yiic migrate` command line tool. This
+tool supports creating new migrations, applying/reverting/redoing migrations, and
+showing migration history and new migrations.
+
+Creating Migrations
+-------------------
+
+To create a new migration (e.g. create a news table), we run the following command:
+
+~~~
+yiic migrate/create <name>
+~~~
+
+The required `name` parameter specifies a very brief description of the migration
+(e.g. `create_news_table`). As we will show in the following, the `name` parameter
+is used as part of a PHP class name. Therefore, it should only contain letters,
+digits and/or underscore characters.
+
+~~~
+yiic migrate/create create_news_table
+~~~
+
+The above command will create under the `protected/migrations` directory a new
+file named `m101129_185401_create_news_table.php` which contains the following
+initial code:
+
+~~~
+[php]
+class m101129_185401_create_news_table extends \yii\db\Migration
+{
+	public function up()
+	{
+	}
+
+	public function down()
+	{
+		echo "m101129_185401_create_news_table cannot be reverted.\n";
+		return false;
+	}
+}
+~~~
+
+Notice that the class name is the same as the file name which is of the pattern
+`m<timestamp>_<name>`, where `<timestamp>` refers to the UTC timestamp (in the
+format of `yymmdd_hhmmss`) when the migration is created, and `<name>` is taken
+from the command's `name` parameter.
+
+The `up()` method should contain the code implementing the actual database
+migration, while the `down()` method may contain the code reverting what is
+done in `up()`.
+
+Sometimes, it is impossible to implement `down()`. For example, if we delete
+table rows in `up()`, we will not be able to recover them in `down()`. In this
+case, the migration is called irreversible, meaning we cannot roll back to
+a previous state of the database. In the above generated code, the `down()`
+method returns `false` to indicate that the migration cannot be reverted.
+
+As an example, let's show the migration about creating a news table.
+
+~~~
+[php]
+class m101129_185401_create_news_table extends \yii\db\Migration
+{
+	public function up()
+	{
+		$this->db->createCommand()->createTable('tbl_news, array(
+			'id' => 'pk',
+			'title' => 'string NOT NULL',
+			'content' => 'text',
+		))->execute();
+	}
+
+	public function down()
+	{
+		$this->db->createCommand()->dropTable('tbl_news')->execute();
+	}
+}
+~~~
+
+The base class [\yii\db\Migration] exposes a database connection via `db`
+property. You can use it for manipulating data and schema of a database.
+
+Transactional Migrations
+------------------------
+
+While performing complex DB migrations, we usually want to make sure that each
+migration succeed or fail as a whole so that the database maintains the
+consistency and integrity. In order to achieve this goal, we can exploit
+DB transactions.
+
+We could explicitly start a DB transaction and enclose the rest of the DB-related
+code within the transaction, like the following:
+
+~~~
+[php]
+class m101129_185401_create_news_table extends \yii\db\Migration
+{
+	public function up()
+	{
+		$transaction=$this->getDbConnection()->beginTransaction();
+		try
+		{
+			$this->db->createCommand()->createTable('tbl_news, array(
+				'id' => 'pk',
+				'title' => 'string NOT NULL',
+				'content' => 'text',
+			))->execute();
+			$transaction->commit();
+		}
+		catch(Exception $e)
+		{
+			echo "Exception: ".$e->getMessage()."\n";
+			$transaction->rollback();
+			return false;
+		}
+	}
+
+	// ...similar code for down()
+}
+~~~
+
+> Note: Not all DBMS support transactions. And some DB queries cannot be put
+> into a transaction. In this case, you will have to implement `up()` and
+> `down()`, instead. And for MySQL, some SQL statements may cause
+> [implicit commit](http://dev.mysql.com/doc/refman/5.1/en/implicit-commit.html).
+
+
+Applying Migrations
+-------------------
+
+To apply all available new migrations (i.e., make the local database up-to-date),
+run the following command:
+
+~~~
+yiic migrate
+~~~
+
+The command will show the list of all new migrations. If you confirm to apply
+the migrations, it will run the `up()` method in every new migration class, one
+after another, in the order of the timestamp value in the class name.
+
+After applying a migration, the migration tool will keep a record in a database
+table named `tbl_migration`. This allows the tool to identify which migrations
+have been applied and which are not. If the `tbl_migration` table does not exist,
+the tool will automatically create it in the database specified by the `db`
+application component.
+
+Sometimes, we may only want to apply one or a few new migrations. We can use the
+following command:
+
+~~~
+yiic migrate/up 3
+~~~
+
+This command will apply the 3 new migrations. Changing the value 3 will allow
+us to change the number of migrations to be applied.
+
+We can also migrate the database to a specific version with the following command:
+
+~~~
+yiic migrate/to 101129_185401
+~~~
+
+That is, we use the timestamp part of a migration name to specify the version
+that we want to migrate the database to. If there are multiple migrations between
+the last applied migration and the specified migration, all these migrations
+will be applied. If the specified migration has been applied before, then all
+migrations applied after it will be reverted (to be described in the next section).
+
+
+Reverting Migrations
+--------------------
+
+To revert the last one or several applied migrations, we can use the following
+command:
+
+~~~
+yiic migrate/down [step]
+~~~
+
+where the optional `step` parameter specifies how many migrations to be reverted
+back. It defaults to 1, meaning reverting back the last applied migration.
+
+As we described before, not all migrations can be reverted. Trying to revert
+such migrations will throw an exception and stop the whole reverting process.
+
+
+Redoing Migrations
+------------------
+
+Redoing migrations means first reverting and then applying the specified migrations.
+This can be done with the following command:
+
+~~~
+yiic migrate/redo [step]
+~~~
+
+where the optional `step` parameter specifies how many migrations to be redone.
+It defaults to 1, meaning redoing the last migration.
+
+
+Showing Migration Information
+-----------------------------
+
+Besides applying and reverting migrations, the migration tool can also display
+the migration history and the new migrations to be applied.
+
+~~~
+yiic migrate/history [limit]
+yiic migrate/new [limit]
+~~~
+
+where the optional parameter `limit` specifies the number of migrations to be
+displayed. If `limit` is not specified, all available migrations will be displayed.
+
+The first command shows the migrations that have been applied, while the second
+command shows the migrations that have not been applied.
+
+
+Modifying Migration History
+---------------------------
+
+Sometimes, we may want to modify the migration history to a specific migration
+version without actually applying or reverting the relevant migrations. This
+often happens when developing a new migration. We can use the following command
+to achieve this goal.
+
+~~~
+yiic migrate/mark 101129_185401
+~~~
+
+This command is very similar to `yiic migrate/to` command, except that it only
+modifies the migration history table to the specified version without applying
+or reverting the migrations.
+
+
+Customizing Migration Command
+-----------------------------
+
+There are several ways to customize the migration command.
+
+### Use Command Line Options
+
+The migration command comes with four options that can be specified in command
+line:
+
+* `interactive`: boolean, specifies whether to perform migrations in an
+  interactive mode. Defaults to true, meaning the user will be prompted when
+  performing a specific migration. You may set this to false should the
+  migrations be done in a background process.
+
+* `migrationPath`: string, specifies the directory storing all migration class
+  files. This must be specified in terms of a path alias, and the corresponding
+  directory must exist. If not specified, it will use the `migrations`
+  sub-directory under the application base path.
+
+* `migrationTable`: string, specifies the name of the database table for storing
+  migration history information. It defaults to `tbl_migration`. The table
+  structure is `version varchar(255) primary key, apply_time integer`.
+
+* `connectionID`: string, specifies the ID of the database application component.
+  Defaults to 'db'.
+
+* `templateFile`: string, specifies the path of the file to be served as the code
+  template for generating the migration classes. This must be specified in terms
+  of a path alias (e.g. `application.migrations.template`). If not set, an
+  internal template will be used. Inside the template, the token `{ClassName}`
+  will be replaced with the actual migration class name.
+
+To specify these options, execute the migrate command using the following format
+
+~~~
+yiic migrate/up --option1=value1 --option2=value2 ...
+~~~
+
+For example, if we want to migrate for a `forum` module whose migration files
+are located within the module's `migrations` directory, we can use the following
+command:
+
+~~~
+yiic migrate/up --migrationPath=ext.forum.migrations
+~~~
+
+
+### Configure Command Globally
+
+While command line options allow us to configure the migration command
+on-the-fly, sometimes we may want to configure the command once for all.
+For example, we may want to use a different table to store the migration history,
+or we may want to use a customized migration template. We can do so by modifying
+the console application's configuration file like the following,
+
+```php
+TBD
+```
+
+Now if we run the `migrate` command, the above configurations will take effect
+without requiring us to enter the command line options every time.

framework/base/Application.php

@@ -306,6 +306,15 @@ class Application extends Module
 	}
 
 	/**
+	 * @return null|Component
+	 * @todo
+	 */
+	public function getAuthManager()
+	{
+		return $this->getComponent('auth');
+	}
+
+	/**
 	 * Registers the core application components.
 	 * @see setComponents
 	 */

framework/base/View.php

@@ -744,10 +744,10 @@ class View extends Component
 	{
 		$lines = array();
 		if (!empty($this->metaTags)) {
-			$lines[] = implode("\n", $this->cssFiles);
+			$lines[] = implode("\n", $this->metaTags);
 		}
 		if (!empty($this->linkTags)) {
-			$lines[] = implode("\n", $this->cssFiles);
+			$lines[] = implode("\n", $this->linkTags);
 		}
 		if (!empty($this->cssFiles)) {
 			$lines[] = implode("\n", $this->cssFiles);

framework/helpers/base/SecurityHelper.php

@@ -167,11 +167,11 @@ class SecurityHelper
 	 *
 	 * ~~~
 	 * // generates the hash (usually done during user registration or when the password is changed)
-	 * $hash = SecurityHelper::hashPassword($password);
+	 * $hash = SecurityHelper::generatePasswordHash($password);
 	 * // ...save $hash in database...
 	 *
 	 * // during login, validate if the password entered is correct using $hash fetched from database
-	 * if (PasswordHelper::verifyPassword($password, $hash) {
+	 * if (SecurityHelper::verifyPassword($password, $hash) {
 	 *     // password is good
 	 * } else {
 	 *     // password is bad
@@ -217,7 +217,7 @@ class SecurityHelper
 			throw new InvalidParamException('Password must be a string and cannot be empty.');
 		}
 
-		if (!preg_match('/^\$2[axy]\$(\d\d)\$[\./0-9A-Za-z]{22}/', $hash, $matches) || $matches[1] < 4 || $matches[1] > 30) {
+		if (!preg_match('/^\$2[axy]\$(\d\d)\$[\.\/0-9A-Za-z]{22}/', $hash, $matches) || $matches[1] < 4 || $matches[1] > 30) {
 			throw new InvalidParamException('Hash is invalid.');
 		}
 

framework/helpers/base/VarDumper.php

@@ -39,7 +39,7 @@ class VarDumper
 	 */
 	public static function dump($var, $depth = 10, $highlight = false)
 	{
-		echo self::dumpAsString($var, $depth, $highlight);
+		echo static::dumpAsString($var, $depth, $highlight);
 	}
 
 	/**

framework/logging/Target.php

@@ -89,7 +89,7 @@ abstract class Target extends \yii\base\Component
 	 */
 	public function collect($messages, $final)
 	{
-		$this->_messages = array($this->_messages, $this->filterMessages($messages));
+		$this->_messages = array_merge($this->_messages, $this->filterMessages($messages));
 		$count = count($this->_messages);
 		if ($count > 0 && ($final || $this->exportInterval > 0 && $count >= $this->exportInterval)) {
 			if (($context = $this->getContextMessage()) !== '') {

framework/validators/FileValidator.php

@@ -192,11 +192,11 @@ class FileValidator extends Validator
 				break;
 			case UPLOAD_ERR_CANT_WRITE:
 				$this->addError($object, $attribute, $this->message);
-				Yii::warning('Failed to write the uploaded file to disk: ', $file->getName(), __METHOD__);
+				Yii::warning('Failed to write the uploaded file to disk: ' . $file->getName(), __METHOD__);
 				break;
 			case UPLOAD_ERR_EXTENSION:
 				$this->addError($object, $attribute, $this->message);
-				Yii::warning('File upload was stopped by some PHP extension: ', $file->getName(), __METHOD__);
+				Yii::warning('File upload was stopped by some PHP extension: ' . $file->getName(), __METHOD__);
 				break;
 			default:
 				break;

framework/web/AccessRule.php

@@ -144,7 +144,7 @@ class AccessRule extends Component
 				return true;
 			} elseif ($role === '@' && !$user->getIsGuest()) {
 				return true;
-			} elseif ($user->hasAccess($role)) {
+			} elseif ($user->checkAccess($role)) {
 				return true;
 			}
 		}

framework/web/AssetConverter.php

@@ -53,8 +53,8 @@ class AssetConverter extends Component implements IAssetConverter
 					));
 					exec($command, $output);
 					Yii::info("Converted $asset into $result: " . implode("\n", $output), __METHOD__);
-					return "$baseUrl/$result";
 				}
+				return "$baseUrl/$result";
 			}
 		}
 		return "$baseUrl/$asset";

framework/web/UploadedFile.php

@@ -7,7 +7,7 @@
 
 namespace yii\web;
 
-use yii\widgets\ActiveForm;
+use yii\widgets\Html;
 
 /**
  * @author Qiang Xue <qiang.xue@gmail.com>
@@ -66,7 +66,7 @@ class UploadedFile extends \yii\base\Object
 	 */
 	public static function getInstance($model, $attribute)
 	{
-		$name = ActiveForm::getInputName($model, $attribute);
+		$name = Html::getInputName($model, $attribute);
 		return static::getInstanceByName($name);
 	}
 
@@ -80,7 +80,7 @@ class UploadedFile extends \yii\base\Object
 	 */
 	public static function getInstances($model, $attribute)
 	{
-		$name = ActiveForm::getInputName($model, $attribute);
+		$name = Html::getInputName($model, $attribute);
 		return static::getInstancesByName($name);
 	}
 

framework/web/UrlManager.php

@@ -51,7 +51,7 @@ class UrlManager extends Component
 	 * @var boolean whether to show entry script name in the constructed URL. Defaults to true.
 	 * This property is used only if [[enablePrettyUrl]] is true.
 	 */
-	public $showScriptName = true;
+	public $showScriptName = false;
 	/**
 	 * @var string the GET variable name for route. This property is used only if [[enablePrettyUrl]] is false.
 	 */
@@ -174,7 +174,7 @@ class UrlManager extends Component
 	public function createUrl($route, $params = array())
 	{
 		$anchor = isset($params['#']) ? '#' . $params['#'] : '';
-		unset($params['#']);
+		unset($params['#'], $params[$this->routeVar]);
 
 		$route = trim($route, '/');
 		$baseUrl = $this->getBaseUrl();

framework/web/User.php

@@ -447,4 +447,21 @@ class User extends Component
 			}
 		}
 	}
+
+	/**
+	 * Checks whether the user has access to the specified operation.
+	 * @param $operator
+	 * @param array $params
+	 * @return bool
+	 * @todo
+	 */
+	public function checkAccess($operation, $params = array())
+	{
+		$auth = Yii::$app->getAuthManager();
+		if ($auth !== null) {
+			return $auth->checkAccess($this->getId(), $operation, $params);
+		} else {
+			return true;
+		}
+	}
 }

tests/unit/framework/caching/ApcCacheTest.php

@@ -17,6 +17,8 @@ class ApcCacheTest extends CacheTest
 	{
 		if(!extension_loaded("apc")) {
 			$this->markTestSkipped("APC not installed. Skipping.");
+		} else if ('cli' === PHP_SAPI && !ini_get('apc.enable_cli')) {
+			$this->markTestSkipped("APC cli is not enabled. Skipping.");
 		}
 
 		if($this->_cacheInstance === null) {