refactored the message command.

framework/yii/console/Controller.php

@@ -30,8 +30,7 @@ use yii\helpers\Console;
 class Controller extends \yii\base\Controller
 {
 	/**
-	 * @var boolean whether the call of [[confirm()]] requires a user input.
-	 * If false, [[confirm()]] will always return true no matter what user enters or not.
+	 * @var boolean whether to run the command interactively.
 	 */
 	public $interactive = true;
 

framework/yii/console/controllers/MessageController.php

@@ -8,6 +8,7 @@
 
 namespace yii\console\controllers;
 
+use Yii;
 use yii\console\Controller;
 use yii\console\Exception;
 use yii\helpers\FileHelper;
@@ -18,10 +19,10 @@ use yii\helpers\FileHelper;
  * under the specified directory.
  *
  * Usage:
- * 1. Create a configuration file using 'template' action:
- *    yii message/template /path/to/myapp/messages/config.php
+ * 1. Create a configuration file using the 'message/config' command:
+ *    yii message/config /path/to/myapp/messages/config.php
  * 2. Edit the created config file, adjusting it for your web application needs.
- * 3. Run the 'generate' action, using created config:
+ * 3. Run the 'message/extract' extract, using created config:
  *    yii message /path/to/myapp/messages/config.php
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
@@ -32,100 +33,85 @@ class MessageController extends Controller
 	/**
 	 * @var string controller default action ID.
 	 */
-	public $defaultAction = 'generate';
+	public $defaultAction = 'extract';
+
+
 	/**
-	 * Searches for messages to be translated in the specified
-	 * source files and compiles them into PHP arrays as message source.
+	 * Creates a configuration file for the "extract" command.
 	 *
-	 * @param string $config the path of the configuration file. You can find
-	 * an example in framework/messages/config.php.
-	 * @throws \yii\console\Exception on failure.
+	 * The generated configuration file contains detailed instructions on
+	 * how to customize it to fit for your needs. After customization,
+	 * you may use this configuration file with the "extract" command.
 	 *
-	 * The file can be placed anywhere and must be a valid PHP script which
-	 * returns an array of name-value pairs. Each name-value pair represents
-	 * a configuration option.
+	 * @param string $filePath output file name.
+	 * @throws Exception on failure.
+	 */
+	public function actionConfig($filePath)
+	{
+		if (file_exists($filePath)) {
+			if (!$this->confirm("File '{$filePath}' already exists. Do you wish to overwrite it?")) {
+				return;
+			}
+		}
+		copy(Yii::getAlias('@yii/views/messageConfig.php'), $filePath);
+		echo "Configuration file template created at '{$filePath}'.\n\n";
+	}
+
+	/**
+	 * Extracts messages to be translated from source code.
 	 *
-	 * The following options are available:
+	 * This command will search through source code files and extract
+	 * messages that need to be translated in different languages.
 	 *
-	 *  - sourcePath: string, root directory of all source files.
-	 *  - messagePath: string, root directory containing message translations.
-	 *  - languages: array, list of language codes that the extracted messages
-	 *    should be translated to. For example, array('zh_cn', 'en_au').
-	 *  - fileTypes: array, a list of file extensions (e.g. 'php', 'xml').
-	 *    Only the files whose extension name can be found in this list
-	 *    will be processed. If empty, all files will be processed.
-	 *  - exclude: array, a list of directory and file exclusions. Each
-	 *    exclusion can be either a name or a path. If a file or directory name
-	 *    or path matches the exclusion, it will not be copied. For example,
-	 *    an exclusion of '.svn' will exclude all files and directories whose
-	 *    name is '.svn'. And an exclusion of '/a/b' will exclude file or
-	 *    directory 'sourcePath/a/b'.
-	 *  - translator: the name of the function for translating messages.
-	 *    Defaults to 'Yii::t'. This is used as a mark to find messages to be
-	 *    translated. Accepts both string for single function name or array for
-	 *    multiple function names.
-	 *  - overwrite: if message file must be overwritten with the merged messages.
-	 *  - removeOld: if message no longer needs translation it will be removed,
-	 *    instead of being enclosed between a pair of '@@' marks.
-	 *  - sort: sort messages by key when merging, regardless of their translation
-	 *    state (new, obsolete, translated.)
+	 * @param string $configFile the path of the configuration file.
+	 * You may use the "yii message/config" command to generate
+	 * this file and then customize it for your needs.
+	 * @throws Exception on failure.
 	 */
-	public function actionGenerate($config)
+	public function actionExtract($configFile)
 	{
-		if (!is_file($config)) {
-			throw new Exception("the configuration file {$config} does not exist.");
+		if (!is_file($configFile)) {
+			throw new Exception("the configuration file {$configFile} does not exist.");
 		}
 
-		$config = require($config);
+		$config = array_merge(array(
+			'translator' => 'Yii::t',
+			'overwrite' => false,
+			'removeUnused' => false,
+			'sort' => false,
+		), require($configFile));
 
-		$translator = 'Yii::t';
-		extract($config);
-
-		if (!isset($sourcePath, $messagePath, $languages)) {
+		if (!isset($config['sourcePath'], $config['messagePath'], $config['languages'])) {
 			throw new Exception('The configuration file must specify "sourcePath", "messagePath" and "languages".');
 		}
-		if (!is_dir($sourcePath)) {
-			throw new Exception("The source path {$sourcePath} is not a valid directory.");
+		if (!is_dir($config['sourcePath'])) {
+			throw new Exception("The source path {$config['sourcePath']} is not a valid directory.");
 		}
-		if (!is_dir($messagePath)) {
-			throw new Exception("The message path {$messagePath} is not a valid directory.");
+		if (!is_dir($config['messagePath'])) {
+			throw new Exception("The message path {$config['messagePath']} is not a valid directory.");
 		}
-		if (empty($languages)) {
+		if (empty($config['languages'])) {
 			throw new Exception("Languages cannot be empty.");
 		}
 
-		if (!isset($overwrite)) {
-			$overwrite = false;
-		}
-		if (!isset($removeOld)) {
-			$removeOld = false;
-		}
-		if (!isset($sort)) {
-			$sort = false;
-		}
-
-		$options = array();
-		if (isset($fileTypes)) {
-			$options['fileTypes'] = $fileTypes;
-		}
-		if (isset($exclude)) {
-			$options['exclude'] = $exclude;
-		}
-		$files = FileHelper::findFiles(realpath($sourcePath), $options);
+		$files = FileHelper::findFiles(realpath($config['sourcePath']), $config);
 
 		$messages = array();
 		foreach ($files as $file) {
-			$messages = array_merge_recursive($messages, $this->extractMessages($file, $translator));
+			$messages = array_merge($messages, $this->extractMessages($file, $config['translator']));
 		}
 
-		foreach ($languages as $language) {
-			$dir = $messagePath . DIRECTORY_SEPARATOR . $language;
+		foreach ($config['languages'] as $language) {
+			$dir = $config['messagePath'] . DIRECTORY_SEPARATOR . $language;
 			if (!is_dir($dir)) {
 				@mkdir($dir);
 			}
 			foreach ($messages as $category => $msgs) {
 				$msgs = array_values(array_unique($msgs));
-				$this->generateMessageFile($msgs, $dir . DIRECTORY_SEPARATOR . $category . '.php', $overwrite, $removeOld, $sort);
+				$this->generateMessageFile($msgs, $dir . DIRECTORY_SEPARATOR . $category . '.php',
+					$config['overwrite'],
+					$config['removeUnused'],
+					$config['sort']);
 			}
 		}
 	}
@@ -168,10 +154,10 @@ class MessageController extends Controller
 	 * @param array $messages
 	 * @param string $fileName name of the file to write to
 	 * @param boolean $overwrite if existing file should be overwritten without backup
-	 * @param boolean $removeOld if obsolete translations should be removed
+	 * @param boolean $removeUnused if obsolete translations should be removed
 	 * @param boolean $sort if translations should be sorted
 	 */
-	protected function generateMessageFile($messages, $fileName, $overwrite, $removeOld, $sort)
+	protected function generateMessageFile($messages, $fileName, $overwrite, $removeUnused, $sort)
 	{
 		echo "Saving messages to $fileName...";
 		if (is_file($fileName)) {
@@ -199,9 +185,9 @@ class MessageController extends Controller
 			}
 			ksort($translated);
 			foreach ($translated as $message => $translation) {
-				if (!isset($merged[$message]) && !isset($todo[$message]) && !$removeOld) {
+				if (!isset($merged[$message]) && !isset($todo[$message]) && !$removeUnused) {
 					if (substr($translation, 0, 2) === '@@' && substr($translation, -2) === '@@') {
-						$todo[$message]=$translation;
+						$todo[$message] = $translation;
 					} else {
 						$todo[$message] = '@@' . $translation . '@@';
 					}
@@ -248,44 +234,4 @@ return $array;
 EOD;
 		file_put_contents($fileName, $content);
 	}
-
-	/**
-	 * Creates template of configuration file for [[actionGenerate]].
-	 * @param string $configFile output file name.
-	 * @throws \yii\console\Exception on failure.
-	 */
-	public function actionTemplate($configFile)
-	{
-		$template = <<<EOD
-<?php
-/**
- * Configuration file for the "yii {$this->id}" console command.
- */
-return array(
-	'sourcePath' => __DIR__,
-	'messagePath' => __DIR__ . DIRECTORY_SEPARATOR . 'messages',
-	'languages' => array(),
-	'fileTypes' => array('php'),
-	'overwrite' => true,
-	'exclude' => array(
-		'.svn',
-		'.gitignore',
-		'.gitkeep',
-		'.hgignore',
-		'.hgkeep',
-		'/messages',
-	),
-);
-EOD;
-		if (file_exists($configFile)) {
-			if (!$this->confirm("File '{$configFile}' already exists. Do you wish to overwrite it?")) {
-				return;
-			}
-		}
-		if (!file_put_contents($configFile, $template)) {
-			throw new Exception("Unable to write template file '{$configFile}'.");
-		} else {
-			echo "Configuration file template created at '{$configFile}'.\n\n";
-		}
-	}
 }

framework/yii/helpers/base/FileHelper.php

@@ -141,7 +141,7 @@ class FileHelper
 	 *   A path matches a pattern if it contains the pattern string at its end. For example,
 	 *   '/a/b' will match all files and directories ending with '/a/b'; and the '.svn' will match all files and
 	 *   directories whose name ends with '.svn'. Note, the '/' characters in a pattern matches both '/' and '\'.
-	 *   If a file/directory matches both a name in "only" and "except", it will NOT be copied.
+	 *   If a file/directory matches a pattern in both "only" and "except", it will NOT be copied.
 	 * - except: array, list of patterns that the files or directories should NOT match if they want to be copied.
 	 *   For more details on how to specify the patterns, please refer to the "only" option.
 	 * - recursive: boolean, whether the files under the subdirectories should also be copied. Defaults to true.
@@ -215,10 +215,10 @@ class FileHelper
 	 *   A path matches a pattern if it contains the pattern string at its end. For example,
 	 *   '/a/b' will match all files and directories ending with '/a/b'; and the '.svn' will match all files and
 	 *   directories whose name ends with '.svn'. Note, the '/' characters in a pattern matches both '/' and '\'.
-	 *   If a file/directory matches both a name in "only" and "except", it will NOT be returned.
+	 *   If a file/directory matches a pattern in both in "only" and "except", it will NOT be returned.
 	 * - except: array, list of patterns that the files or directories should NOT match if they want to be returned.
 	 *   For more details on how to specify the patterns, please refer to the "only" option.
-	 * - recursive: boolean, whether the files under the subdirectories should also be lookied for. Defaults to true.
+	 * - recursive: boolean, whether the files under the subdirectories should also be looked for. Defaults to true.
 	 * @return array files found under the directory. The file list is sorted.
 	 */
 	public static function findFiles($dir, $options = array())

framework/yii/views/messageConfig.php

+<?php
+
+return array(
+	// string, required, root directory of all source files
+	'sourcePath' => __DIR__,
+	// string, required, root directory containing message translations.
+	'messagePath' => __DIR__ . DIRECTORY_SEPARATOR . 'messages',
+	// array, required, list of language codes that the extracted messages
+	// should be translated to. For example, array('zh_cn', 'de').
+	'languages' => array('de'),
+	// string, the name of the function for translating messages.
+	// Defaults to 'Yii::t'. This is used as a mark to find the messages to be
+	// translated. You may use a string for single function name or an array for
+	// multiple function names.
+	'translator' => 'Yii::t',
+	// boolean, whether to sort messages by keys when merging new messages
+	// with the existing ones. Defaults to false, which means the new (untranslated)
+	// messages will be separated from the old (translated) ones.
+	'sort' => false,
+	// boolean, whether the message file should be overwritten with the merged messages
+	'overwrite' => true,
+	// boolean, whether to remove messages that no longer appear in the source code.
+	// Defaults to false, which means each of these messages will be enclosed with a pair of '@@' marks.
+	'removeUnused' => false,
+	// array, list of patterns that specify which files/directories should be processed.
+	// If empty or not set, all files/directories will be processed.
+	// A path matches a pattern if it contains the pattern string at its end. For example,
+	// '/a/b' will match all files and directories ending with '/a/b';
+	// and the '.svn' will match all files and directories whose name ends with '.svn'.
+	// Note, the '/' characters in a pattern matches both '/' and '\'.
+	// If a file/directory matches both a pattern in "only" and "except", it will NOT be processed.
+	'only' => array('.php'),
+	// array, list of patterns that specify which files/directories should NOT be processed.
+	// If empty or not set, all files/directories will be processed.
+	// Please refer to "only" for details about the patterns.
+	'except' => array(
+		'.svn',
+		'.git',
+		'.gitignore',
+		'.gitkeep',
+		'.hgignore',
+		'.hgkeep',
+		'/messages',
+	),
+);

tests/unit/framework/console/controllers/MessageControllerTest.php

@@ -155,17 +155,17 @@ class MessageControllerTest extends TestCase
 
 	// Tests:
 
-	public function testActionTemplate()
+	public function testActionConfig()
 	{
 		$configFileName = $this->configFileName;
-		$this->runMessageControllerAction('template', array($configFileName));
+		$this->runMessageControllerAction('config', array($configFileName));
 		$this->assertTrue(file_exists($configFileName), 'Unable to create config file template!');
 	}
 
 	public function testConfigFileNotExist()
 	{
 		$this->setExpectedException('yii\\console\\Exception');
-		$this->runMessageControllerAction('generate', array('not_existing_file.php'));
+		$this->runMessageControllerAction('extract', array('not_existing_file.php'));
 	}
 
 	public function testCreateTranslation()
@@ -182,7 +182,7 @@ class MessageControllerTest extends TestCase
 			'sourcePath' => $this->sourcePath,
 			'messagePath' => $this->messagePath,
 		));
-		$this->runMessageControllerAction('generate', array($this->configFileName));
+		$this->runMessageControllerAction('extract', array($this->configFileName));
 
 		$this->assertTrue(file_exists($this->messagePath . DIRECTORY_SEPARATOR . $language), 'No language dir created!');
 		$messageFileName = $this->messagePath . DIRECTORY_SEPARATOR . $language . DIRECTORY_SEPARATOR . $category . '.php';
@@ -209,7 +209,7 @@ class MessageControllerTest extends TestCase
 			'sourcePath' => $this->sourcePath,
 			'messagePath' => $this->messagePath,
 		));
-		$this->runMessageControllerAction('generate', array($this->configFileName));
+		$this->runMessageControllerAction('extract', array($this->configFileName));
 
 		$messageFileName = $this->messagePath . DIRECTORY_SEPARATOR . $language . DIRECTORY_SEPARATOR . $category . '.php';
 
@@ -218,7 +218,7 @@ class MessageControllerTest extends TestCase
 		$messageFileContent .= '// some not generated by command content';
 		file_put_contents($messageFileName, $messageFileContent);
 
-		$this->runMessageControllerAction('generate', array($this->configFileName));
+		$this->runMessageControllerAction('extract', array($this->configFileName));
 
 		$this->assertEquals($messageFileContent, file_get_contents($messageFileName));
 	}
@@ -249,7 +249,7 @@ class MessageControllerTest extends TestCase
 			'messagePath' => $this->messagePath,
 			'overwrite' => true,
 		));
-		$this->runMessageControllerAction('generate', array($this->configFileName));
+		$this->runMessageControllerAction('extract', array($this->configFileName));
 
 		$messages = require($this->messagePath . DIRECTORY_SEPARATOR . $messageFileName);
 		$this->assertTrue(array_key_exists($newMessage, $messages), 'Unable to add new message!');
@@ -281,9 +281,9 @@ class MessageControllerTest extends TestCase
 			'sourcePath' => $this->sourcePath,
 			'messagePath' => $this->messagePath,
 			'overwrite' => true,
-			'removeOld' => false,
+			'removeUnused' => false,
 		));
-		$this->runMessageControllerAction('generate', array($this->configFileName));
+		$this->runMessageControllerAction('extract', array($this->configFileName));
 
 		$messages = require($this->messagePath . DIRECTORY_SEPARATOR . $messageFileName);
 
@@ -321,7 +321,7 @@ class MessageControllerTest extends TestCase
 			'messagePath' => $this->messagePath,
 			'overwrite' => true,
 		));
-		$this->runMessageControllerAction('generate', array($this->configFileName));
+		$this->runMessageControllerAction('extract', array($this->configFileName));
 
 		$messages = require($this->messagePath . DIRECTORY_SEPARATOR . $messageFileName);
 		$this->assertTrue($zeroMessageContent === $messages[$zeroMessage], 'Message content "0" is lost!');
@@ -357,7 +357,7 @@ class MessageControllerTest extends TestCase
 			'messagePath' => $this->messagePath,
 			'translator' => $translators,
 		));
-		$this->runMessageControllerAction('generate', array($this->configFileName));
+		$this->runMessageControllerAction('extract', array($this->configFileName));
 
 		$messageFileName = $this->messagePath . DIRECTORY_SEPARATOR . $language . DIRECTORY_SEPARATOR . $category . '.php';
 		$messages = require($messageFileName);