Symfony: версионирование статики с помощью asset

Веб-разработка
4 июля 2022
5 мин чтения
Symfony: версионирование статики с помощью asset

После обновления сайта пользователи иногда продолжают видеть старые CSS и JavaScript. Причина — кеш браузера: содержимое файла изменилось, а его URL остался прежним.

Принудительная перезагрузка страницы (Ctrl+Shift+R или Ctrl+F5 в распространённых настольных браузерах) может решить проблему на одном компьютере, но заставлять пользователей делать это после каждого релиза неправильно. Обычный Ctrl+R не гарантирует обход кеша.

Для решения проблемы используется версионирование статических ресурсов: при изменении содержимого меняется URL файла или его параметр версии.

В современных проектах Symfony есть несколько способов:

  • AssetMapper — появился в Symfony 6.3 и предоставляет версионированные URL ресурсов без обязательной сборки через Webpack.
  • Webpack Encore — может создавать файлы с хешами содержимого и manifest.json; для разрешения адресов используется json_manifest_path.
  • Symfony Asset Component — поддерживает простые версии и собственные реализации VersionStrategyInterface. Этот вариант полезен для проектов без AssetMapper и сборщика либо для нестандартных сценариев публикации статики.

Ниже рассмотрим третий вариант: собственную стратегию, в которой версия меняется при развёртывании приложения.

Содержание

Что нужно сделать:

  1. Используем asset() в Twig. Все ссылки на ресурсы, для которых необходимо версионирование, должны генерироваться через эту функцию:
   <link rel="stylesheet" href="{{ asset('css/app.css') }}">
   <script src="{{ asset('js/app.js') }}" defer></script>
   <svg><use href="{{ asset('img/sprite.svg') }}#test-123"></use></svg>
  1. Создаём стратегию версионирования. Она читает версию из файла var/asset_version.txt и добавляет к URL параметр v. Если в исходном URL есть якорь, параметр вставляется перед ним.

Файл src/Asset/VersionStrategy/ReleaseVersionStrategy.php:

   <?php

   declare(strict_types=1);

   namespace App\Asset\VersionStrategy;

   use Symfony\Component\Asset\VersionStrategy\VersionStrategyInterface;

   final class ReleaseVersionStrategy implements VersionStrategyInterface
   {
       public function __construct(
           private readonly string $versionFile,
       ) {
       }

       public function getVersion(string $path): string
       {
           if (!is_file($this->versionFile)) {
               return '1';
           }

           $version = trim((string) file_get_contents($this->versionFile));

           return $version !== '' ? $version : '1';
       }

       public function applyVersion(string $path): string
       {
           $version = $this->getVersion($path);
           $parts = explode('#', $path, 2);
           $url = $parts[0];
           $fragment = $parts[1] ?? null;

           $separator = str_contains($url, '?') ? '&' : '?';
           $url .= $separator . 'v=' . rawurlencode($version);

           return $fragment === null ? $url : $url . '#' . $fragment;
       }
   }
  1. Подключаем стратегию в Symfony. В config/services.yaml добавляем определение сервиса:
   services:
       App\Asset\VersionStrategy\ReleaseVersionStrategy:
           arguments:
               $versionFile: '%kernel.project_dir%/var/asset_version.txt'

В config/packages/framework.yaml указываем стратегию:

   framework:
       assets:
           version_strategy: App\Asset\VersionStrategy\ReleaseVersionStrategy

Если в проекте уже есть настройки framework.assets, объедините параметры в существующем разделе, а не создавайте второй. Для работы необходимы установленные Symfony Asset Component и Twig-интеграция.

  1. Обновляем версию при релизе. Файл версии создаётся отдельной командой или скриптом развёртывания. Пример команды bin/console app:mark-updated в src/Command/MarkUpdatedCommand.php:
   <?php

   declare(strict_types=1);

   namespace App\Command;

   use Symfony\Component\Console\Attribute\AsCommand;
   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;

   #[AsCommand(
       name: 'app:mark-updated',
       description: 'Обновляет версию статических ресурсов',
   )]
   final class MarkUpdatedCommand extends Command
   {
       public function __construct(private readonly string $projectDir)
       {
           parent::__construct();
       }

       protected function execute(InputInterface $input, OutputInterface $output): int
       {
           $directory = $this->projectDir . '/var';

           if (!is_dir($directory) && !mkdir($directory, 0775, true) && !is_dir($directory)) {
               throw new \RuntimeException('Не удалось создать каталог var');
           }

           $version = bin2hex(random_bytes(8));
           $path = $directory . '/asset_version.txt';

           if (file_put_contents($path, $version, LOCK_EX) === false) {
               throw new \RuntimeException('Не удалось записать версию статики');
           }

           $output->writeln('Версия статики: ' . $version);

           return Command::SUCCESS;
       }
   }

Для автосвязывания аргумента конструктора в config/services.yaml добавляем:

   services:
       App\Command\MarkUpdatedCommand:
           arguments:
               $projectDir: '%kernel.project_dir%'

Затем выполняем:

   php bin/console app:mark-updated

В результате ссылка css/app.css будет иметь вид /css/app.css?v=..., а ссылка img/sprite.svg#test-123 — /img/sprite.svg?v=...#test-123.

Важно: если используете OPcache, долгоживущие процессы, несколько экземпляров приложения или CDN, версия должна согласованно обновляться на всех экземплярах. При долгом кешировании HTML необходимо также продумать, когда браузер получит страницу с новыми URL ресурсов.

Итог

После релиза новые HTML-страницы будут содержать ссылки с обновлённой версией. Браузер воспринимает такие URL как новые ресурсы и загружает актуальные файлы, если сервер и промежуточные кеши настроены корректно.

Собственная стратегия полезна для существующих проектов, но имеет ограничение: при каждом изменении версии обновляются URL всех ресурсов, даже если изменился только один файл. Для новых проектов, где это возможно, разумнее рассмотреть AssetMapper или файлы с хешами содержимого через Webpack Encore.

Документация: AssetMapper, пользовательские стратегии версионирования, версионирование Webpack Encore.

Редакция NJ Soft
Редакция NJ Soft
Редактор блога

Поделиться:

Нужна разработка или поддержка проекта?

Разрабатываем веб-сервисы и мобильные приложения, дорабатываем и поддерживаем существующие проекты. Расскажите о задаче — предложим решение.