Новое в Symfony 6.3 — Компонент AssetMapper

Работа с веб-ресурсами в веб-проектах постоянно меняется. Браузеры и фронтенд технологии сильно развиваются, и Symfony приходится адаптироваться к ним. В прошлом Symfony включала Assetic в качестве конвейера обработки веб-ресурсов. Он может комбинировать, компилировать и фильтровать ресурсы, прежде чем использовать их в приложении.

В 2017 году мы представили Webpack Encore как современную альтернативу Assetic, основанную на Webpack и обладающую бесконечными возможностями для управления веб-ресурсами. Это может быть немного сложным для новичков, но после настройки этот конвейер создания ресурсов прост в управлении и отлично работает.

Хотя мы были довольны решением, основанным на Webpack Encore, недавно в браузеры была добавлена поддержка революционной функции, называемой карты импорта. Карта импорта — это объект JSON сообщающий браузеры, как разрешать модули при импорте JavaScript модулей. Она сопоставляет имена модулей с их расположением (в виде относительных путей или абсолютных URL-адресов).

Например, если вы добавите это в HTML код своих веб-страниц:

<script type="importmap">
  {
    "imports": {
      "square": "./module/shapes/square.js",
      "circle": "https://example.com/shapes/circle.js"
    }
  }
</script>

Вы можете использовать в своём JavaScript коде следующее:

import { name as squareName, draw } from "square";
import { name as circleName } from "circle";

// ...

Вам не нужно создавать и компилировать ресурсы. Браузер может найти встроенные/скомпилированные модули в путях/URL-адресах, предоставленных картой импорта. В Symfony 6.3 мы представляем новый компонент AssertMapper, который позволяет использовать карты импорта для управления вашими ресурсами. Этот компонент избавляет от необходимости использовать Webpack, Webpack Encore, Node.js, yarn/npm и т.д.

Компонент делится на две основные возможности:

1. Возможность сопоставления ресурсов с общедоступными и версионными путями;
2. Возможность использования карт импорта во фронтенд коде.

Сопоставление ресурсов с путями

Вот краткий обзор того, как этот компонент работает при сопоставлении ресурсов:

(1) Активируйте маппер/сопоставитель ресурсов, указав Symfony путь, который будет использоваться для их обслуживания:

# config/packages/framework.yaml
framework:
    asset_mapper:
        paths: ['assets/']

(2) Поместите созданные/скомпилированные ресурсы в каталог <ваш-проект>/assets/ (то же самое вы делаете при использовании Webpack Encore):

ваш-проект/
    assets/
        app.js
        styles/
            app.css
        images/
            logo.png

(3) Обратитесь к ресурсам с помощью знакомой вам функции assets():

<link rel="stylesheet" href="{{ asset('styles/app.css') }}">
<script src="{{ asset('app.js') }}" defer></script>

<img src="{{ asset('images/logo.png') }}">

Вот и всё. Окончательные пути используемые браузером будут выглядеть так:

<link rel="stylesheet" href="/assets/styles/app-b93e5de06d9459ec9c39f10d8f9ce5b2.css">
<script src="/assets/app-1fcc5be55ce4e002a3016a5f6e1d0174.js" defer type="module"></script>
<img src="/assets/images/logo-3f24cba25ce4e114a3116b5f6f1d2159.png">

Как это работает за кулисами?

• В среде dev слушатель перехватывает запросы к пути, который вы настроили ранее (assets/ в данном случае), находит файл в исходном каталоге <ваш-проект>/assets/ и возвращает его;
• В среде prod вы запускаете новую команду assets:mapper:compile, которая копирует все ресурсы в public/assets/, чтобы вернуть настоящие файлы. Эта команда также создаёт дамп файла public/assets/manifest.json, чтобы можно было быстро заменить исходные пути (например, styles/app.css) на их окончательные пути.

Внутренне этот компонент предоставляет базовый компилятор для таких вещей, как обновление значения операторов url(), включённых в CSS файлы, для обновления URL-адресов в исходных картах и т.д. Мы не воссоздаём Assetic, но нам нужно предоставить эти основные функции компиляции, чтобы сделать этот компонент полезным.

Работа с картами импорта

Функция карт импорта, включённая в компонент AssetMapper работает следующим образом. В JavaScript коде вы импортируете модули так же, как и раньше:

// assets/app.js
import { Application } from '@hotwired/stimulus';
import CoolStuff from './cool_stuff.js';

// ...

Разница в том, что теперь не нужно использовать npm/yarn для установки всех этих javaScript зависимостей. Вместо этого запустите команду importmap:require, чтобы установить эти зависимости:

php bin/console importmap:require '@hotwired/stimulus';

Эта команда создаст или обновит файл importmap.php в корне проекта:

return [
    'app' => [
        'path' => 'app.js',
        'preload' => true,
    ],
    '@hotwired/stimulus' => [
        'url' => 'https://ga.jspm.io/npm:@hotwired/stimulus@3.2.1/dist/stimulus.js',
    ],
];

Последний шаг — добавить новую функцию {{ importmap() }} внутрь тега <head> всех страниц. Конечный результат будет примерно таким:

<script type="importmap">
    { "imports": {
        "app": "/assets/app-cf9cfe84e945a554b2f1f64342d542bc.js",
        "cool_stuff.js": "/assets/cool_stuff-10b27bd6986c75a1e69c8658294bf22c.js",
        "@hotwired/stimulus": "https://ga.jspm.io/npm:@hotwired/stimulus@3.2.1/dist/stimulus.js",
    }}
</script>

<link rel="modulepreload" href="/assets/app-cf9cfe84e945a554b2f1f64342d542bc.js">
<link rel="modulepreload" href="/assets/cool_stuff-10b27bd6986c75a1e69c8658294bf22c.js">
<script type="module">import 'app';</script>

Есть много других замечательных возможностей, предоставляемых AssetMapper. Мы всё ещё пишем для него документацию и надеемся, что она будет готова вскоре после выпуска Symfony 6.3. Райан также выступит с докладом о AssetMapper под названием Modern UIs with UX, a little JS & Zero Node во время предстоящей конференции SymfonyOnline в июне 2023 года.