Конфигурация Assets

Обзор параметров конфигурации Nette Assets.

assets:
	# базовый путь для разрешения относительных путей мапперов
	basePath: ...            # (string) по умолчанию %wwwDir%

	# базовый URL для разрешения относительных URL мапперов
	baseUrl: ...             # (string) по умолчанию %baseUrl%

	# включить версионирование ресурсов глобально?
	versioning: ...           # (bool) по умолчанию true

	# определяет мапперы ресурсов
	mapping: ...             # (array) по умолчанию путь 'assets'

basePath задаёт каталог файловой системы по умолчанию для разрешения относительных путей в мапперах. По умолчанию используется веб-каталог (%wwwDir%).

baseUrl задаёт приставку URL по умолчанию для разрешения относительных URL в мапперах. По умолчанию используется корневой URL (%baseUrl%).

Параметр versioning глобально управляет тем, добавляются ли к URL ресурсов параметры версии для сброса кеша. Отдельные мапперы могут эту настройку переопределить.

Мапперы

Мапперы можно настроить тремя способами: простой строковой записью, подробной записью массивом или как сервис (записью сущности ClassName(...) либо @serviceName()).

Проще всего определить маппер так:

assets:
	mapping:
		default: assets     # Создаёт файловый маппер для %wwwDir%/assets/
		images: img         # Создаёт файловый маппер для %wwwDir%/img/
		scripts: js         # Создаёт файловый маппер для %wwwDir%/js/

Каждый маппер создаёт FilesystemMapper, который:

• ищет файлы в %wwwDir%/<path>
• порождает URL вида %baseUrl%/<path>
• наследует глобальную настройку версионирования

Для большего контроля используйте подробную запись:

assets:
	mapping:
		images:
			# каталог, где хранятся файлы
			path: ...                    # (string) необязательно, по умолчанию базовый путь (basePath)

			# приставка URL для порождаемых ссылок
			url: ...                     # (string) необязательно, по умолчанию значение path

			# включить версионирование для этого маппера?
			versioning: ...              # (bool) необязательно, наследует глобальную настройку

			# автоматически дописывать расширение или расширения при поиске файлов
			extension: ...               # (string|array) необязательно, по умолчанию null

Как разрешаются значения конфигурации:

Разрешение пути

относительные пути разрешаются от basePath (или от %wwwDir%, если basePath не задан)

абсолютные пути используются как есть

Разрешение URL

относительные URL разрешаются от baseUrl (или от %baseUrl%, если baseUrl не задан)

абсолютные URL (со схемой или //) используются как есть (URL с // берёт схему из baseUrl)

если url не указан, используется значение path

assets:
	basePath: /var/www/project/www
	baseUrl: https://example.com/assets

	mapping:
		# Относительный путь и URL
		images:
			path: img                    # Разрешится в: /var/www/project/www/img
			url: images                  # Разрешится в: https://example.com/assets/images

		# Абсолютный путь и URL
		uploads:
			path: /var/shared/uploads    # Используется как есть: /var/shared/uploads
			url: https://cdn.example.com # Используется как есть: https://cdn.example.com

		# Указан только path
		styles:
			path: css                    # Путь: /var/www/project/www/css
										 # URL: https://example.com/assets/css

Собственные мапперы

Для собственных мапперов сошлитесь на существующий сервис через @serviceName либо определите его прямо через ClassName(аргументы) или голое имя класса:

services:
	s3mapper: App\Assets\S3Mapper(%s3.bucket%)

assets:
	mapping:
		cloud: @s3mapper
		database: App\Assets\DatabaseMapper(@database.connection)

Маппер Vite

Мапперу Vite достаточно добавить type: vite. Вот полный список параметров конфигурации:

assets:
	mapping:
		default:
			# тип маппера (обязателен для Vite)
			type: vite                # (string) обязательно, должно быть 'vite'

			# каталог вывода сборки Vite
			path: ...                 # (string) необязательно, по умолчанию базовый путь (basePath)

			# приставка URL для собранных ресурсов
			url: ...                  # (string) необязательно, по умолчанию значение path

			# расположение файла манифеста Vite
			manifest: ...             # (string) необязательно, относительно path, по умолчанию <path>/.vite/manifest.json

			# настройка dev-сервера Vite
			devServer: ...            # (bool|string) необязательно, по умолчанию true

			# версионирование файлов из публичного каталога
			versioning: ...           # (bool) необязательно, наследует глобальную настройку

			# автоматическое расширение для файлов из публичного каталога
			extension: ...            # (string|array) необязательно, по умолчанию null

Параметр devServer управляет тем, как ресурсы загружаются при разработке:

• true (по умолчанию) – автоматически определяет запущенный dev-сервер Vite (по файлу .vite/nette.json, который плагин Vite для Nette создаёт в каталоге сборки). Если dev-сервер запущен и ваше приложение в режиме отладки, ресурсы загружаются из него с поддержкой горячей замены модулей. Если dev-сервер не запущен, ресурсы загружаются из собранных файлов в публичном каталоге.
• false – полностью отключает интеграцию с dev-сервером. Ресурсы всегда загружаются из собранных файлов.
• Собственный URL (например, https://localhost:5173) – вручную задаёт URL dev-сервера вместе с протоколом и портом. Полезно, когда dev-сервер работает на другом хосте или порте. Как и автоопределение, это действует только в режиме отладки; в продакшне всегда используются собранные файлы.

Параметры versioning и extension относятся только к файлам из публичного каталога Vite, которые сам Vite не обрабатывает.

Настройка вручную

Когда вы не используете Nette DI, настраивайте мапперы вручную:

use Nette\Assets\Registry;
use Nette\Assets\FilesystemMapper;
use Nette\Assets\ViteMapper;

$registry = new Registry;

// Добавляем файловый маппер
$registry->addMapper('images', new FilesystemMapper(
	baseUrl: 'https://example.com/img',
	basePath: __DIR__ . '/www/img',
	extensions: ['webp', 'jpg', 'png'],
	versioning: true,
));

// Добавляем маппер Vite
$registry->addMapper('app', new ViteMapper(
	baseUrl: '/build',
	basePath: __DIR__ . '/www/build',
	manifestPath: __DIR__ . '/www/build/.vite/manifest.json',
	devServer: 'https://localhost:5173',
));

Любой зарегистрированный маппер можно получить по имени методом getMapper():

$mapper = $registry->getMapper('images');   // вернёт зарегистрированный маппер
$default = $registry->getMapper();           // вернёт маппер 'default'