Configurarea Asset-urilor

Prezentare generală a opțiunilor de configurare pentru Nette Assets.

assets:
	# cale de bază pentru rezolvarea căilor relative ale mapper-ilor
	basePath: ...            # (șir de caractere) implicit %wwwDir%

	# URL de bază pentru rezolvarea URL-urilor relative ale mapper-ilor
	baseUrl: ...             # (șir de caractere) implicit %baseUrl%

	# activează versionarea asset-urilor global?
	versioning: ...           # (boolean) implicit true

	# definește mapper-ii de asset-uri
	mapping: ...             # (array) implicit cale 'assets'

basePath setează directorul implicit al sistemului de fișiere pentru rezolvarea căilor relative în mapperi. Implicit, utilizează directorul web (%wwwDir%).

baseUrl setează prefixul URL implicit pentru rezolvarea URL-urilor relative în mapperi. Implicit, utilizează URL-ul rădăcină (%baseUrl%).

Opțiunea versioning controlează global dacă parametrii de versiune sunt adăugați la URL-urile asset-urilor pentru invalidarea cache-ului. Mapperii individuali pot suprascrie această setare.

Mapperi

Mapperii pot fi configurați în trei moduri: notație simplă de șir, notație detaliată de array sau ca referință la un serviciu.

Cel mai simplu mod de a defini un mapper:

assets:
	mapping:
		default: assets     # Creează un mapper de sistem de fișiere pentru %wwwDir%/assets/
		images: img         # Creează un mapper de sistem de fișiere pentru %wwwDir%/img/
		scripts: js         # Creează un mapper de sistem de fișiere pentru %wwwDir%/js/

Fiecare mapper creează un FilesystemMapper care:

• Caută fișiere în %wwwDir%/<cale>
• Generează URL-uri precum %baseUrl%/<cale>
• Moștenește setarea globală de versionare

Pentru mai mult control, utilizați notația detaliată:

assets:
	mapping:
		images:
			# directorul unde sunt stocate fișierele
			path: ...                    # (șir de caractere) opțional, implicit ''

			# prefix URL pentru link-urile generate
			url: ...                     # (șir de caractere) opțional, implicit cale

			# activează versionarea pentru acest mapper?
			versioning: ...              # (boolean) opțional, moștenește setarea globală

			# adaugă automat extensie(i) la căutarea fișierelor
			extension: ...               # (șir de caractere|array) opțional, implicit null

Înțelegerea modului în care valorile de configurare sunt rezolvate:

Rezolvarea Căii

Căile relative sunt rezolvate din basePath (sau %wwwDir% dacă basePath nu este setat)

Căile absolute sunt utilizate ca atare

Rezolvarea URL-ului

URL-urile relative sunt rezolvate din baseUrl (sau %baseUrl% dacă baseUrl nu este setat)

URL-urile absolute (cu schemă sau //) sunt utilizate ca atare

Dacă url nu este specificat, utilizează valoarea path

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

	mapping:
		# Cale și URL relativ
		images:
			path: img                    # Rezolvat la: /var/www/project/www/img
			url: images                  # Rezolvat la: https://example.com/assets/images

		# Cale și URL absolut
		uploads:
			path: /var/shared/uploads    # Utilizat ca atare: /var/shared/uploads
			url: https://cdn.example.com # Utilizat ca atare: https://cdn.example.com

		# Doar calea specificată
		styles:
			path: css                    # Cale: /var/www/project/www/css
										 # URL: https://example.com/assets/css

Mapperi Personalizați

Pentru mapperi personalizați, referențiați sau definiți un serviciu:

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

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

Vite Mapper

Mapper-ul Vite necesită doar adăugarea type: vite. Aceasta este o listă completă de opțiuni de configurare:

assets:
	mapping:
		default:
			# tip mapper (obligatoriu pentru Vite)
			type: vite                # (șir de caractere) obligatoriu, trebuie să fie 'vite'

			# directorul de ieșire al construirii Vite
			path: ...                 # (șir de caractere) opțional, implicit ''

			# prefix URL pentru asset-urile construite
			url: ...                  # (șir de caractere) opțional, implicit cale

			# locația fișierului manifest Vite
			manifest: ...             # (șir de caractere) opțional, implicit <cale>/.vite/manifest.json

			# configurare server de dezvoltare Vite
			devServer: ...            # (boolean|șir de caractere) opțional, implicit true

			# versionare pentru fișierele din directorul public
			versioning: ...           # (boolean) opțional, moștenește setarea globală

			# auto-extensie pentru fișierele din directorul public
			extension: ...            # (șir de caractere|array) opțional, implicit null

Opțiunea devServer controlează modul în care asset-urile sunt încărcate în timpul dezvoltării:

• true (implicit) – Detectează automat serverul de dezvoltare Vite pe gazda și portul curente. Dacă serverul de dezvoltare rulează și aplicația dumneavoastră este în modul de depanare, asset-urile sunt încărcate de la acesta cu suport pentru înlocuirea la cald a modulelor (HMR). Dacă serverul de dezvoltare nu rulează, asset-urile sunt încărcate din fișierele construite din directorul public.
• false – Dezactivează complet integrarea serverului de dezvoltare. Asset-urile sunt întotdeauna încărcate din fișierele construite.
• URL personalizat (de ex., https://localhost:5173) – Specificați manual URL-ul serverului de dezvoltare, inclusiv protocolul și portul. Util atunci când serverul de dezvoltare rulează pe o altă gazdă sau port.

Opțiunile versioning și extension se aplică doar fișierelor din directorul public al Vite care nu sunt procesate de Vite.

Configurare Manuală

Când nu utilizați Nette DI, configurați mapperii manual:

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

$registry = new Registry;

// Adaugă mapper de sistem de fișiere
$registry->addMapper('images', new FilesystemMapper(
	baseUrl: 'https://example.com/img',
	basePath: __DIR__ . '/www/img',
	extensions: ['webp', 'jpg', 'png'],
	versioning: true,
));

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