feature #10593 [Templating] Added ability to set a specific version of the asset (romainneutron)

This PR was merged into the 2.5-dev branch.

Discussion
----------

[Templating] Added ability to set a specific version of the asset

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| License       | MIT
| Doc PR        | https://github.com/symfony/symfony-docs/pull/3742/files

This PR replaces #6092

Commits
-------

1642094 [Templating] Update changelog
6fce503 [Templating] Added ability to set a specific version of the asset

src/Symfony/Bundle/TwigBundle/Extension/AssetsExtension.php

@@ -48,15 +48,16 @@ class AssetsExtension extends \Twig_Extension
      *
      * Absolute paths (i.e. http://...) are returned unmodified.
      *
-     * @param string  $path        A public path
-     * @param string  $packageName The name of the asset package to use
-     * @param Boolean $absolute    Whether to return an absolute URL or a relative one
+     * @param string              $path        A public path
+     * @param string              $packageName The name of the asset package to use
+     * @param Boolean             $absolute    Whether to return an absolute URL or a relative one
+     * @param string|Boolean|null $version     A specific version
      *
      * @return string A public path which takes into account the base path and URL path
      */
-    public function getAssetUrl($path, $packageName = null, $absolute = false)
+    public function getAssetUrl($path, $packageName = null, $absolute = false, $version = null)
     {
-        $url = $this->container->get('templating.helper.assets')->getUrl($path, $packageName);
+        $url = $this->container->get('templating.helper.assets')->getUrl($path, $packageName, $version);
 
         if (!$absolute) {
             return $url;

src/Symfony/Component/Templating/Asset/Package.php

@@ -33,34 +33,42 @@ class Package implements PackageInterface
         $this->format = $format ?: '%s?%s';
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function getVersion()
     {
         return $this->version;
     }
 
-    public function getUrl($path)
+    /**
+     * {@inheritdoc}
+     */
+    public function getUrl($path, $version = null)
     {
         if (false !== strpos($path, '://') || 0 === strpos($path, '//')) {
             return $path;
         }
 
-        return $this->applyVersion($path);
+        return $this->applyVersion($path, $version);
     }
 
     /**
      * Applies version to the supplied path.
      *
-     * @param string $path A path
+     * @param string              $path    A path
+     * @param string|Boolean|null $version A specific version
      *
      * @return string The versionized path
      */
-    protected function applyVersion($path)
+    protected function applyVersion($path, $version = null)
     {
-        if (null === $this->version) {
+        $version = null !== $version ? $version : $this->version;
+        if (null === $version || false === $version) {
             return $path;
         }
 
-        $versionized = sprintf($this->format, ltrim($path, '/'), $this->version);
+        $versionized = sprintf($this->format, ltrim($path, '/'), $version);
 
         if ($path && '/' == $path[0]) {
             $versionized = '/'.$versionized;

src/Symfony/Component/Templating/Asset/PackageInterface.php

@@ -28,9 +28,10 @@ interface PackageInterface
     /**
      * Returns an absolute or root-relative public path.
      *
-     * @param string $path A path
+     * @param string              $path    A path
+     * @prama string|Boolean|null $version A specific version for the path
      *
      * @return string The public path
      */
-    public function getUrl($path);
+    public function getUrl($path, $version = null);
 }

src/Symfony/Component/Templating/Asset/PathPackage.php

@@ -42,13 +42,16 @@ class PathPackage extends Package
         }
     }
 
-    public function getUrl($path)
+    /**
+     * {@inheritdoc}
+     */
+    public function getUrl($path, $version = null)
     {
         if (false !== strpos($path, '://') || 0 === strpos($path, '//')) {
             return $path;
         }
 
-        $url = $this->applyVersion($path);
+        $url = $this->applyVersion($path, $version);
 
         // apply the base path
         if ('/' !== substr($url, 0, 1)) {

src/Symfony/Component/Templating/Asset/UrlPackage.php

@@ -41,13 +41,16 @@ class UrlPackage extends Package
         }
     }
 
-    public function getUrl($path)
+    /**
+     * {@inheritdoc}
+     */
+    public function getUrl($path, $version = null)
     {
         if (false !== strpos($path, '://') || 0 === strpos($path, '//')) {
             return $path;
         }
 
-        $url = $this->applyVersion($path);
+        $url = $this->applyVersion($path, $version);
 
         if ($url && '/' != $url[0]) {
             $url = '/'.$url;

src/Symfony/Component/Templating/CHANGELOG.md

@@ -1,6 +1,12 @@
 CHANGELOG
 =========
 
+2.5.0
+-----
+
+ * added ability to generate versioned URLs
+ * added ability to generate absolute URLs
+
 2.1.0
 -----
 

src/Symfony/Component/Templating/Helper/CoreAssetsHelper.php

@@ -105,14 +105,15 @@ class CoreAssetsHelper extends Helper implements PackageInterface
      *
      * Absolute paths (i.e. http://...) are returned unmodified.
      *
-     * @param string $path        A public path
-     * @param string $packageName The name of the asset package to use
+     * @param string              $path        A public path
+     * @param string              $packageName The name of the asset package to use
+     * @param string|Boolean|null $version     A specific version
      *
      * @return string A public path which takes into account the base path and URL path
      */
-    public function getUrl($path, $packageName = null)
+    public function getUrl($path, $packageName = null, $version = null)
     {
-        return $this->getPackage($packageName)->getUrl($path);
+        return $this->getPackage($packageName)->getUrl($path, $version);
     }
 
     /**

src/Symfony/Component/Templating/Tests/Helper/AssetsHelperTest.php

@@ -57,6 +57,14 @@ class AssetsHelperTest extends \PHPUnit_Framework_TestCase
         $this->assertEquals('/', $helper->getUrl(''), '->getUrl() with empty arg returns the prefix alone');
     }
 
+    public function testGetUrlWithVersion()
+    {
+        $helper = new AssetsHelper(null, array(), '12');
+        $this->assertEquals('/foo.js?12', $helper->getUrl('foo.js'));
+        $this->assertEquals('/foo.js?bar', $helper->getUrl('foo.js', null, 'bar'));
+        $this->assertEquals('/foo.js', $helper->getUrl('foo.js', null, false));
+    }
+
     public function testGetUrlLeavesProtocolRelativePathsUntouched()
     {
         $helper = new AssetsHelper(null, 'http://foo.com');