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

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


```neon
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()`).

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

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

Каждый маппер создаёт `FilesystemMapper`, который:
- ищет файлы в `%wwwDir%/<path>`
- порождает URL вида `%baseUrl%/<path>`
- наследует глобальную настройку версионирования


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

```neon
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`


```neon
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(аргументы)` или голое имя класса:

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

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


Маппер Vite
-----------

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

```neon
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, настраивайте мапперы вручную:

```php
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()`:

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