Merge pull request #486 from klimov-paul/asset-command-i-4

#72 Improve the "asset" command Iteration 4

framework/yii/console/controllers/AssetController.php

@@ -14,6 +14,20 @@ use yii\console\Controller;
 /**
  * This command allows you to combine and compress your JavaScript and CSS files.
  *
+ * Usage:
+ * 1. Create a configuration file using 'template' action:
+ *    yii asset/template /path/to/myapp/config.php
+ * 2. Edit the created config file, adjusting it for your web application needs.
+ * 3. Run the 'compress' action, using created config:
+ *    yii asset /path/to/myapp/config.php /path/to/myapp/config/assets_compressed.php
+ * 4. Adjust your web application config to use compressed assets.
+ *
+ * Note: in the console environment some path aliases like '@wwwroot' and '@www' may not exist,
+ * so corresponding paths inside the configuration should be specified directly.
+ *
+ * Note: by default this command relies on an external tools to perform actual files compression,
+ * check [[jsCompressor]] and [[cssCompressor]] for more details.
+ *
  * @property array|\yii\web\AssetManager $assetManager asset manager, which will be used for assets processing.
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
@@ -43,7 +57,7 @@ class AssetController extends Controller
 	 * ~~~
 	 * 'all' => array(
 	 *     'css' => 'all.css',
-	 *     'js' => 'js.css',
+	 *     'js' => 'all.js',
 	 *     'depends' => array( ... ),
 	 * )
 	 * ~~~
@@ -57,7 +71,7 @@ class AssetController extends Controller
 	 */
 	private $_assetManager = array();
 	/**
-	 * @var string|callback Java Script file compressor.
+	 * @var string|callback JavaScript file compressor.
 	 * If a string, it is treated as shell command template, which should contain
 	 * placeholders {from} - source file name - and {to} - output file name.
 	 * Otherwise, it is treated as PHP callback, which should perform the compression.
@@ -159,7 +173,7 @@ class AssetController extends Controller
 			}
 		}
 
-		$this->getAssetManager(); // check asset manager configuration
+		$this->getAssetManager(); // check if asset manager configuration is correct
 	}
 
 	/**
@@ -308,7 +322,7 @@ class AssetController extends Controller
 	/**
 	 * Builds output asset bundle.
 	 * @param \yii\web\AssetBundle $target output asset bundle
-	 * @param string $type either "js" or "css".
+	 * @param string $type either 'js' or 'css'.
 	 * @param \yii\web\AssetBundle[] $bundles source asset bundles.
 	 * @param integer $timestamp current timestamp.
 	 * @throws Exception on failure.
@@ -420,24 +434,23 @@ class AssetController extends Controller
 		}
 		$array = var_export($array, true);
 		$version = date('Y-m-d H:i:s', time());
-		$bytesWritten = file_put_contents($bundleFile, <<<EOD
+		$bundleFileContent = <<<EOD
 <?php
 /**
- * This file is generated by the "yii script" command.
+ * This file is generated by the "yii {$this->id}" command.
  * DO NOT MODIFY THIS FILE DIRECTLY.
- * @version $version
+ * @version {$version}
  */
-return $array;
-EOD
-		);
-		if ($bytesWritten <= 0) {
+return {$array};
+EOD;
+		if (!file_put_contents($bundleFile, $bundleFileContent)) {
 			throw new Exception("Unable to write output bundle configuration at '{$bundleFile}'.");
 		}
 		echo "Output bundle configuration created at '{$bundleFile}'.\n";
 	}
 
 	/**
-	 * Compresses given Java Script files and combines them into the single one.
+	 * Compresses given JavaScript files and combines them into the single one.
 	 * @param array $inputFiles list of source file names.
 	 * @param string $outputFile output file name.
 	 * @throws \yii\console\Exception on failure
@@ -495,9 +508,10 @@ EOD
 	}
 
 	/**
-	 * Combines Java Script files into a single one.
+	 * Combines JavaScript files into a single one.
 	 * @param array $inputFiles source file names.
 	 * @param string $outputFile output file name.
+	 * @throws \yii\console\Exception on failure.
 	 */
 	public function combineJsFiles($inputFiles, $outputFile)
 	{
@@ -507,13 +521,16 @@ EOD
 				. file_get_contents($file)
 				. "/*** END FILE: $file ***/\n";
 		}
-		file_put_contents($outputFile, $content);
+		if (!file_put_contents($outputFile, $content)) {
+			throw new Exception("Unable to write output JavaScript file '{$outputFile}'.");
+		}
 	}
 
 	/**
 	 * Combines CSS files into a single one.
 	 * @param array $inputFiles source file names.
 	 * @param string $outputFile output file name.
+	 * @throws \yii\console\Exception on failure.
 	 */
 	public function combineCssFiles($inputFiles, $outputFile)
 	{
@@ -523,7 +540,9 @@ EOD
 				. $this->adjustCssUrl(file_get_contents($file), dirname($file), dirname($outputFile))
 				. "/*** END FILE: $file ***/\n";
 		}
-		file_put_contents($outputFile, $content);
+		if (!file_put_contents($outputFile, $content)) {
+			throw new Exception("Unable to write output CSS file '{$outputFile}'.");
+		}
 	}
 
 	/**
@@ -590,18 +609,23 @@ EOD
 	/**
 	 * Creates template of configuration file for [[actionCompress]].
 	 * @param string $configFile output file name.
+	 * @throws \yii\console\Exception on failure.
 	 */
 	public function actionTemplate($configFile)
 	{
 		$template = <<<EOD
 <?php
-
+/**
+ * Configuration file for the "yii asset" console command.
+ * Note: in the console environment some path aliases like '@wwwroot' and '@www' may not exist,
+ * so corresponding paths should be specified directly.
+ */
 return array(
-	//
+	// The list of asset bundles to compress:
 	'bundles' => require('path/to/bundles.php'),
-	//
+	// The list of extensions to compress:
 	'extensions' => require('path/to/namespaces.php'),
-	//
+	// Asset bundle for compression output:
 	'targets' => array(
 		'all' => array(
 			'basePath' => __DIR__,
@@ -610,7 +634,7 @@ return array(
 			'css' => 'all-{ts}.css',
 		),
 	),
-
+	// Asset manager configuration:
 	'assetManager' => array(
 		'basePath' => __DIR__,
 		'baseUrl' => '/test',
@@ -622,9 +646,8 @@ EOD;
 				return;
 			}
 		}
-		$bytesWritten = file_put_contents($configFile, $template);
-		if ($bytesWritten<=0) {
-			echo "Error: unable to write file '{$configFile}'!\n\n";
+		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";
 		}

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

@@ -239,6 +239,7 @@ class AssetControllerTest extends TestCase
 
 		// Then :
 		$this->assertTrue(file_exists($bundleFile), 'Unable to create output bundle file!');
+		$this->assertTrue(is_array(require($bundleFile)), 'Output bundle file has incorrect format!');
 
 		$compressedCssFileName = $this->testAssetsBasePath . DIRECTORY_SEPARATOR . 'all.css';
 		$this->assertTrue(file_exists($compressedCssFileName), 'Unable to compress CSS files!');