Fixes #4710: added cache busting support for assets

docs/guide/structure-assets.md

@@ -370,6 +370,30 @@ when it is being published. This is faster than file copying and can also ensure
 always up-to-date.
 
 
+### Cache Busting <span id="cache-busting"></span>
+
+For Web application running in production mode, it is a common practice to enable HTTP caching for assets and other
+static resources. A drawback of this practice is that whenever you modify an asset and deploy it to production, a user
+client may still use the old version due to the HTTP caching. To overcome this drawback, you may use the cache busting
+feature, which was introduced in version 2.0.3, by configuring [[yii\web\AssetManager]] like the following:
+  
+```php
+return [
+    // ...
+    'components' => [
+        'assetManager' => [
+            'appendTimestamp' => true,
+        ],
+    ],
+];
+```
+
+By doing so, the URL of every published asset will be appended with its last modification timestamp. For example,
+the URL to `yii.js` may look like `/assets/5515a87c/yii.js?v=1423448645"`, where the parameter `v` represents the
+last modification timestamp of the `yii.js` file. Now if you modify an asset, its URL will be changed, too, which causes
+the client to fetch the latest version of the asset.
+
+
 ## Commonly Used Asset Bundles <span id="common-asset-bundles"></span>
 
 The core Yii code has defined many asset bundles. Among them, the following bundles are commonly used and may

framework/filters/PageCache.php

@@ -91,8 +91,8 @@ class PageCache extends ActionFilter
      */
     public $variations;
     /**
-     * @var boolean whether to enable the fragment cache. You may use this property to turn on and off
-     * the fragment cache according to specific setting (e.g. enable fragment cache only for GET requests).
+     * @var boolean whether to enable the page cache. You may use this property to turn on and off
+     * the page cache according to specific setting (e.g. enable page cache only for GET requests).
      */
     public $enabled = true;
     /**

framework/web/AssetManager.php

@@ -150,6 +150,15 @@ class AssetManager extends Component
      * significantly degrade the performance.
      */
     public $forceCopy = false;
+    /**
+     * @var boolean whether to append a timestamp to the URL of every published asset. When this is true,
+     * the URL of a published asset may look like `/path/to/asset?v=timestamp`, where `timestamp` is the
+     * last modification time of the published asset file.
+     * You normally would want to set this property to true when you have enabled HTTP caching for assets,
+     * because it allows you to bust caching when the assets are updated.
+     * @since 2.0.3
+     */
+    public $appendTimestamp = false;
 
     private $_dummyBundles = [];
 
@@ -252,9 +261,22 @@ class AssetManager extends Component
     public function getAssetUrl($bundle, $asset)
     {
         if (($actualAsset = $this->resolveAsset($bundle, $asset)) !== false) {
-            return Url::isRelative($actualAsset) ? $this->baseUrl . '/' . $actualAsset : $actualAsset;
+            $asset = $actualAsset;
+            $basePath = $this->basePath;
+            $baseUrl = $this->baseUrl;
+        } else {
+            $basePath = $bundle->basePath;
+            $baseUrl = $bundle->baseUrl;
+        }
+
+        if (!Url::isRelative($asset)) {
+            return $asset;
+        }
+
+        if ($this->appendTimestamp && ($timestamp = @filemtime("$basePath/$asset")) > 0) {
+            return "$baseUrl/$asset?v=$timestamp";
         } else {
-            return Url::isRelative($asset) ? $bundle->baseUrl . '/' . $asset : $asset;
+            return "$baseUrl/$asset";
         }
     }