Konfiguracja Assets

Przegląd opcji konfiguracyjnych dla Nette Assets.

assets:
	# ścieżka bazowa do rozwiązywania względnych ścieżek mapperów
	basePath: ...            # (string) domyślnie %wwwDir%

	# URL bazowy do rozwiązywania względnych URL-i mapperów
	baseUrl: ...             # (string) domyślnie %baseUrl%

	# włączyć wersjonowanie zasobów globalnie?
	versioning: ...           # (bool) domyślnie true

	# definiuje mappery zasobów
	mapping: ...             # (array) domyślnie ścieżka 'assets'

basePath ustawia domyślny katalog systemu plików do rozwiązywania ścieżek względnych w mapperach. Domyślnie używa katalogu webowego (%wwwDir%).

baseUrl ustawia domyślny prefiks URL do rozwiązywania URL-i względnych w mapperach. Domyślnie używa URL głównego (%baseUrl%).

Opcja versioning steruje globalnie tym, czy do URL-i zasobów dodawane są parametry wersji na potrzeby cache bustingu. Poszczególne mappery mogą to ustawienie nadpisać.

Mappery

Mappery można skonfigurować na trzy sposoby: prostym zapisem tekstowym, szczegółowym zapisem tablicowym albo jako usługę (zapisem encji ClassName(...) albo @serviceName()).

Najprostszy sposób zdefiniowania mappera:

assets:
	mapping:
		default: assets     # Tworzy mapper systemu plików dla %wwwDir%/assets/
		images: img         # Tworzy mapper systemu plików dla %wwwDir%/img/
		scripts: js         # Tworzy mapper systemu plików dla %wwwDir%/js/

Każdy mapper tworzy FilesystemMapper, który:

• Szuka plików w %wwwDir%/<path>
• Generuje URL-e w rodzaju %baseUrl%/<path>
• Dziedziczy globalne ustawienie wersjonowania

Dla większej kontroli użyj zapisu szczegółowego:

assets:
	mapping:
		images:
			# katalog, w którym przechowywane są pliki
			path: ...                    # (string) opcjonalne, domyślnie ścieżka bazowa (basePath)

			# prefiks URL dla generowanych odnośników
			url: ...                     # (string) opcjonalne, domyślnie path

			# włączyć wersjonowanie dla tego mappera?
			versioning: ...              # (bool) opcjonalne, dziedziczy ustawienie globalne

			# automatyczne dodawanie rozszerzenia (rozszerzeń) przy szukaniu plików
			extension: ...               # (string|array) opcjonalne, domyślnie null

Jak rozwiązywane są wartości konfiguracyjne:

Rozwiązywanie ścieżki

Ścieżki względne rozwiązywane są od basePath (albo %wwwDir%, jeśli basePath nie jest ustawione)

Ścieżki absolutne używane są bez zmian

Rozwiązywanie URL

URL-e względne rozwiązywane są od baseUrl (albo %baseUrl%, jeśli baseUrl nie jest ustawione)

URL-e absolutne (ze schematem albo //) używane są bez zmian (URL // bierze schemat z baseUrl)

Jeśli url nie jest podane, używa wartości path

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

	mapping:
		# Ścieżka i URL względne
		images:
			path: img                    # Rozwiązane do: /var/www/project/www/img
			url: images                  # Rozwiązane do: https://example.com/assets/images

		# Ścieżka i URL absolutne
		uploads:
			path: /var/shared/uploads    # Użyte bez zmian: /var/shared/uploads
			url: https://cdn.example.com # Użyte bez zmian: https://cdn.example.com

		# Podana tylko ścieżka
		styles:
			path: css                    # Ścieżka: /var/www/project/www/css
										 # URL: https://example.com/assets/css

Własne mappery

Dla własnych mapperów odwołaj się do istniejącej usługi przez @serviceName albo zdefiniuj ją bezpośrednio za pomocą ClassName(argumenty) czy samej nazwy klasy:

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

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

Mapper Vite

Mapper Vite wymaga tylko dodania type: vite. Oto kompletna lista opcji konfiguracyjnych:

assets:
	mapping:
		default:
			# typ mappera (wymagany dla Vite)
			type: vite                # (string) wymagane, musi być 'vite'

			# katalog wyjściowy buildu Vite
			path: ...                 # (string) opcjonalne, domyślnie ścieżka bazowa (basePath)

			# prefiks URL dla zbudowanych zasobów
			url: ...                  # (string) opcjonalne, domyślnie path

			# lokalizacja pliku manifestu Vite
			manifest: ...             # (string) opcjonalne, względem path, domyślnie <path>/.vite/manifest.json

			# konfiguracja serwera deweloperskiego Vite
			devServer: ...            # (bool|string) opcjonalne, domyślnie true

			# wersjonowanie plików z katalogu public
			versioning: ...           # (bool) opcjonalne, dziedziczy ustawienie globalne

			# automatyczne rozszerzenie dla plików z katalogu public
			extension: ...            # (string|array) opcjonalne, domyślnie null

Opcja devServer steruje tym, jak zasoby wczytywane są podczas tworzenia:

• true (domyślnie) – Automatycznie wykrywa działający serwer deweloperski Vite (przez plik .vite/nette.json, który plugin Vite dla Nette tworzy w katalogu buildu). Jeśli serwer deweloperski działa i Twoja aplikacja jest w trybie debug, zasoby wczytywane są z niego ze wsparciem dla hot module replacement. Jeśli serwer deweloperski nie działa, zasoby wczytywane są ze zbudowanych plików w katalogu publicznym.
• false – Całkowicie wyłącza integrację z serwerem deweloperskim. Zasoby zawsze wczytywane są ze zbudowanych plików.
• Własny URL (np. https://localhost:5173) – Ręcznie podaje URL serwera deweloperskiego wraz z protokołem i portem. Przydaje się, gdy serwer deweloperski działa na innym hoście albo porcie. Podobnie jak autodetekcja, stosuje się tylko w trybie debug; w produkcji zawsze używane są zbudowane pliki.

Opcje versioning i extension dotyczą wyłącznie plików w katalogu public Vite, które nie są przez Vite przetwarzane.

Konfiguracja ręczna

Gdy nie używasz Nette DI, skonfiguruj mappery ręcznie:

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

$registry = new Registry;

// Dodajemy mapper systemu plików
$registry->addMapper('images', new FilesystemMapper(
	baseUrl: 'https://example.com/img',
	basePath: __DIR__ . '/www/img',
	extensions: ['webp', 'jpg', 'png'],
	versioning: true,
));

// Dodajemy mapper Vite
$registry->addMapper('app', new ViteMapper(
	baseUrl: '/build',
	basePath: __DIR__ . '/www/build',
	manifestPath: __DIR__ . '/www/build/.vite/manifest.json',
	devServer: 'https://localhost:5173',
));

Dowolny zarejestrowany mapper możesz też pobrać po nazwie metodą getMapper():

$mapper = $registry->getMapper('images');   // zwraca zarejestrowany mapper
$default = $registry->getMapper();           // zwraca mapper 'default'