Assets Konfiguráció

A Nette Assets konfigurációs lehetőségeinek áttekintése.

assets:
	# alapútvonal a relatív mapper útvonalak feloldásához
	basePath: ...            # (string) alapértelmezés szerint %wwwDir%

	# alap URL a relatív mapper URL-ek feloldásához
	baseUrl: ...             # (string) alapértelmezés szerint %baseUrl%

	# asset verziózás engedélyezése globálisan?
	versioning: ...           # (bool) alapértelmezés szerint true

	# asset mapperek definiálása
	mapping: ...             # (array) alapértelmezés szerint 'assets' útvonal

A basePath beállítja az alapértelmezett fájlrendszer könyvtárat a mapperek relatív útvonalainak feloldásához. Alapértelmezés szerint a webkönyvtárat (%wwwDir%) használja.

A baseUrl beállítja az alapértelmezett URL prefixet a mapperek relatív URL-einek feloldásához. Alapértelmezés szerint a gyökér URL-t (%baseUrl%) használja.

A versioning opció globálisan szabályozza, hogy a verzióparaméterek hozzáadódnak-e az asset URL-ekhez a gyorsítótár törléséhez. Az egyes mapperek felülírhatják ezt a beállítást.

Mapperek

A mapperek háromféleképpen konfigurálhatók: egyszerű string jelöléssel, részletes tömb jelöléssel, vagy egy szolgáltatásra való hivatkozással.

A mapper definiálásának legegyszerűbb módja:

assets:
	mapping:
		default: assets     # Fájlrendszer mappert hoz létre a %wwwDir%/assets/ számára
		images: img         # Fájlrendszer mappert hoz létre a %wwwDir%/img/ számára
		scripts: js         # Fájlrendszer mappert hoz létre a %wwwDir%/js/ számára

Minden mapper létrehoz egy FilesystemMapper-t, amely:

• Fájlokat keres a %wwwDir%/<path>-ban
• URL-eket generál, mint %baseUrl%/<path>
• Örökli a globális verziózási beállítást

A nagyobb kontroll érdekében használd a részletes jelölést:

assets:
	mapping:
		images:
			# könyvtár, ahol a fájlok tárolódnak
			path: ...                    # (string) opcionális, alapértelmezés szerint ''

			# URL prefix a generált linkekhez
			url: ...                     # (string) opcionális, alapértelmezés szerint path

			# verziózás engedélyezése ehhez a mapperhez?
			versioning: ...              # (bool) opcionális, örökli a globális beállítást

			# automatikus kiterjesztés(ek) hozzáadása fájlok keresésekor
			extension: ...               # (string|array) opcionális, alapértelmezés szerint null

A konfigurációs értékek feloldásának megértése:

Útvonal feloldás

A relatív útvonalak a basePath-ból (vagy %wwwDir%, ha a basePath nincs beállítva) oldódnak fel

Az abszolút útvonalak változatlanul használatosak

URL feloldás

A relatív URL-ek a baseUrl-ből (vagy %baseUrl%, ha a baseUrl nincs beállítva) oldódnak fel

Az abszolút URL-ek (sémával vagy //) változatlanul használatosak

Ha az url nincs megadva, akkor a path értékét használja

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

	mapping:
		# Relatív útvonal és URL
		images:
			path: img                    # Feloldva: /var/www/project/www/img
			url: images                  # Feloldva: https://example.com/assets/images

		# Abszolút útvonal és URL
		uploads:
			path: /var/shared/uploads    # Változatlanul használva: /var/shared/uploads
			url: https://cdn.example.com # Változatlanul használva: https://cdn.example.com

		# Csak az útvonal megadva
		styles:
			path: css                    # Útvonal: /var/www/project/www/css
										 # URL: https://example.com/assets/css

Egyedi mapperek

Egyedi mapperek esetén hivatkozzon vagy definiáljon egy szolgáltatást:

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

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

Vite Mapper

A Vite mapperhez csak a type: vite hozzáadása szükséges. Ez a konfigurációs lehetőségek teljes listája:

assets:
	mapping:
		default:
			# mapper típus (kötelező a Vite-hez)
			type: vite                # (string) kötelező, 'vite' kell legyen

			# Vite build kimeneti könyvtár
			path: ...                 # (string) opcionális, alapértelmezés szerint ''

			# URL prefix a beépített assetekhez
			url: ...                  # (string) opcionális, alapértelmezés szerint path

			# Vite manifest fájl helye
			manifest: ...             # (string) opcionális, alapértelmezés szerint <path>/.vite/manifest.json

			# Vite dev szerver konfiguráció
			devServer: ...            # (bool|string) opcionális, alapértelmezés szerint true

			# verziózás a public könyvtár fájljaihoz
			versioning: ...           # (bool) opcionális, örökli a globális beállítást

			# automatikus kiterjesztés a public könyvtár fájljaihoz
			extension: ...            # (string|array) opcionális, alapértelmezés szerint null

A devServer opció szabályozza, hogyan töltődnek be az assetek fejlesztés közben:

• true (alapértelmezett) – Automatikusan felismeri a Vite dev szervert az aktuális hoston és porton. Ha a dev szerver fut és az alkalmazásod debug módban van, az assetek onnan töltődnek be hot module replacement támogatással. Ha a dev szerver nem fut, az assetek a buildelt fájlokból töltődnek be a public könyvtárból.
• false – Teljesen letiltja a dev szerver integrációt. Az assetek mindig a buildelt fájlokból töltődnek be.
• Egyedi URL (pl. https://localhost:5173) – Manuálisan adja meg a dev szerver URL-jét, beleértve a protokollt és a portot. Hasznos, ha a dev szerver más hoston vagy porton fut.

Az versioning és extension opciók csak a Vite public könyvtárában lévő olyan fájlokra vonatkoznak, amelyeket a Vite nem dolgoz fel.

Manuális konfiguráció

Ha nem használja a Nette DI-t, konfigurálja a mappereket manuálisan:

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

$registry = new Registry;

// Fájlrendszer mapper hozzáadása
$registry->addMapper('images', new FilesystemMapper(
	baseUrl: 'https://example.com/img',
	basePath: __DIR__ . '/www/img',
	extensions: ['webp', 'jpg', 'png'],
	versioning: true,
));

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