How to Use a Custom Version Strategy for Assets

Asset versioning is a technique that improves the performance of web applications by adding a version identifier to the URL of the static assets (CSS, JavaScript, images, etc.) When the content of the asset changes, its identifier is also modified to force the browser to download it again instead of reusing the cached asset.

アセットのバージョニングは、静的アセット (CSS、JavaScript、画像など) の URL にバージョン識別子を追加することで、Web アプリケーションのパフォーマンスを向上させる手法です。アセットのコンテンツが変更されると、その識別子も変更され、ブラウザが強制的にキャッシュされたアセットを再利用する代わりに、もう一度ダウンロードしてください。

If your application requires advanced versioning, such as generating the version dynamically based on some external information, you can create your own version strategy.

外部情報に基づいてバージョンを動的に生成するなど、アプリケーションに高度なバージョン管理が必要な場合は、独自のバージョン戦略を作成できます。

Note

ノート

Symfony provides various cache busting implementations via the version, version_format, and json_manifest_path configuration options.

symfony は、version、version_format、および json_manifest_path 構成オプションを介して、さまざまなキャッシュ無効化の実装を提供します。

Creating your Own Asset Version Strategy

The following example shows how to create a version strategy compatible with gulp-buster. This tool defines a configuration file called busters.json which maps each asset file to its content hash:

次の例は、gulp-buster と互換性のあるバージョン戦略を作成する方法を示しています。このツールは、各アセット ファイルをそのコンテンツ ハッシュにマップする busters.json という構成ファイルを定義します。
1
2
3
4
 
{
    "js/script.js": "f9c7afd05729f10f55b689f36bb20172",
    "css/style.css": "91cd067f79a5839536b46c494c4272d8"
}

Implement VersionStrategyInterface

Asset version strategies are PHP classes that implement the VersionStrategyInterface. In this example, the constructor of the class takes as arguments the path to the manifest file generated by gulp-buster and the format of the generated version string:

アセット バージョン戦略は、VersionStrategyInterface を実装する PHP クラスです。この例では、クラスのコンストラクターは引数として、gulp-buster によって生成されたマニフェスト ファイルへのパスと、生成されたバージョン文字列の形式を取ります。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
// src/Asset/VersionStrategy/GulpBusterVersionStrategy.php
namespace App\Asset\VersionStrategy;

use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface;

class GulpBusterVersionStrategy implements VersionStrategyInterface
{
    /**
     * @var string
     */
    private $manifestPath;

    /**
     * @var string
     */
    private $format;

    /**
     * @var string[]
     */
    private $hashes;

    /**
     * @param string      $manifestPath
     * @param string|null $format
     */
    public function __construct(string $manifestPath, string $format = null)
    {
        $this->manifestPath = $manifestPath;
        $this->format = $format ?: '%s?%s';
    }

    public function getVersion(string $path)
    {
        if (!is_array($this->hashes)) {
            $this->hashes = $this->loadManifest();
        }

        return $this->hashes[$path] ?? '';
    }

    public function applyVersion(string $path)
    {
        $version = $this->getVersion($path);

        if ('' === $version) {
            return $path;
        }

        return sprintf($this->format, $path, $version);
    }

    private function loadManifest()
    {
        return json_decode(file_get_contents($this->manifestPath), true);
    }
}

Register the Strategy Service

After creating the strategy PHP class, register it as a Symfony service.

ストラテジー PHP クラスを作成したら、それを Symfony サービスとして登録します。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
6
 
# config/services.yaml
services:
    App\Asset\VersionStrategy\GulpBusterVersionStrategy:
        arguments:
            - "%kernel.project_dir%/busters.json"
            - "%%s?version=%%s"

Finally, enable the new asset versioning for all the application assets or just for some asset package thanks to the version_strategy option:

最後に、version_strategy オプションを使用して、すべてのアプリケーション アセットまたは一部のアセット パッケージに対して新しいアセットのバージョン管理を有効にします。
  • YAML
    YAML
  • XML
    XML
  • PHP
    PHP
1
2
3
4
5
 
# config/packages/framework.yaml
framework:
    # ...
    assets:
        version_strategy: 'App\Asset\VersionStrategy\GulpBusterVersionStrategy'