Configurazione di Assets

Panoramica delle opzioni di configurazione di Nette Assets.

assets:
	# percorso base per risolvere i percorsi relativi dei mapper
	basePath: ...            # (string) predefinito %wwwDir%

	# URL base per risolvere gli URL relativi dei mapper
	baseUrl: ...             # (string) predefinito %baseUrl%

	# attivare globalmente il versionamento degli asset?
	versioning: ...           # (bool) predefinito true

	# definisce i mapper degli asset
	mapping: ...             # (array) predefinito il percorso 'assets'

basePath imposta la directory predefinita del filesystem per risolvere i percorsi relativi nei mapper. Per impostazione predefinita usa la directory web (%wwwDir%).

baseUrl imposta il prefisso URL predefinito per risolvere gli URL relativi nei mapper. Per impostazione predefinita usa l'URL radice (%baseUrl%).

L'opzione versioning governa globalmente se agli URL degli asset vengano aggiunti i parametri di versione per invalidare la cache. I singoli mapper possono sovrascrivere questa impostazione.

Mapper

I mapper si possono configurare in tre modi: con la semplice notazione a stringa, con la notazione dettagliata ad array, oppure come servizio (usando la notazione a entità ClassName(...) oppure @serviceName()).

Il modo più semplice di definire un mapper:

assets:
	mapping:
		default: assets     # crea un mapper del filesystem per %wwwDir%/assets/
		images: img         # crea un mapper del filesystem per %wwwDir%/img/
		scripts: js         # crea un mapper del filesystem per %wwwDir%/js/

Ogni mapper crea un FilesystemMapper che:

• cerca i file in %wwwDir%/<path>
• genera URL del tipo %baseUrl%/<path>
• eredita l'impostazione globale del versionamento

Per un controllo maggiore usate la notazione dettagliata:

assets:
	mapping:
		images:
			# directory in cui sono salvati i file
			path: ...                    # (string) facoltativo, predefinito il percorso base (basePath)

			# prefisso URL per i link generati
			url: ...                     # (string) facoltativo, predefinito il valore di path

			# attivare il versionamento per questo mapper?
			versioning: ...              # (bool) facoltativo, eredita l'impostazione globale

			# aggiunge automaticamente l'estensione (o le estensioni) quando cerca i file
			extension: ...               # (string|array) facoltativo, predefinito null

Come vengono risolti i valori di configurazione:

Risoluzione del percorso

I percorsi relativi vengono risolti a partire da basePath (oppure da %wwwDir% se basePath non è impostato)

I percorsi assoluti vengono usati così come sono

Risoluzione dell'URL

Gli URL relativi vengono risolti a partire da baseUrl (oppure da %baseUrl% se baseUrl non è impostato)

Gli URL assoluti (con schema oppure //) vengono usati così come sono (un URL // prende lo schema da baseUrl)

Se url non è indicato, viene usato il valore di path

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

	mapping:
		# percorso e URL relativi
		images:
			path: img                    # risolto in: /var/www/project/www/img
			url: images                  # risolto in: https://example.com/assets/images

		# percorso e URL assoluti
		uploads:
			path: /var/shared/uploads    # usato così: /var/shared/uploads
			url: https://cdn.example.com # usato così: https://cdn.example.com

		# indicato solo il percorso
		styles:
			path: css                    # percorso: /var/www/project/www/css
										 # URL: https://example.com/assets/css

Mapper personalizzati

Per i mapper personalizzati fate riferimento a un servizio esistente con @serviceName, oppure definiteli direttamente con ClassName(argomenti) o con il semplice nome della classe:

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

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

Mapper Vite

Il mapper Vite richiede solo che aggiungiate type: vite. Questo è l'elenco completo delle opzioni di configurazione:

assets:
	mapping:
		default:
			# tipo di mapper (obbligatorio per Vite)
			type: vite                # (string) obbligatorio, deve essere 'vite'

			# directory di output della build di Vite
			path: ...                 # (string) facoltativo, predefinito il percorso base (basePath)

			# prefisso URL per gli asset compilati
			url: ...                  # (string) facoltativo, predefinito il valore di path

			# posizione del file manifest di Vite
			manifest: ...             # (string) facoltativo, relativo a path, predefinito <path>/.vite/manifest.json

			# configurazione del dev server di Vite
			devServer: ...            # (bool|string) facoltativo, predefinito true

			# versionamento per i file della directory public
			versioning: ...           # (bool) facoltativo, eredita l'impostazione globale

			# estensione automatica per i file della directory public
			extension: ...            # (string|array) facoltativo, predefinito null

L'opzione devServer governa come vengono caricati gli asset durante lo sviluppo:

• true (predefinito) – rileva automaticamente un dev server di Vite in esecuzione (tramite il file .vite/nette.json che il plugin Vite di Nette crea nella directory di build). Se il dev server è in esecuzione e la vostra applicazione è in modalità debug, gli asset vengono caricati da esso con il supporto all'hot module replacement. Se il dev server non è in esecuzione, gli asset vengono caricati dai file compilati nella directory pubblica.
• false – disattiva completamente l'integrazione con il dev server. Gli asset vengono sempre caricati dai file compilati.
• URL personalizzato (per esempio https://localhost:5173) – indicate a mano l'URL del dev server, protocollo e porta compresi. Torna utile quando il dev server gira su un host o una porta diversi. Come il rilevamento automatico, vale solo in modalità debug; in produzione si usano sempre i file compilati.

Le opzioni versioning ed extension valgono solo per i file della directory public di Vite che non vengono elaborati da Vite.

Configurazione manuale

Quando non usate Nette DI, configurate i mapper a mano:

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

$registry = new Registry;

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

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

Potete anche ottenere qualsiasi mapper registrato in base al nome con il metodo getMapper():

$mapper = $registry->getMapper('images');   // restituisce il mapper registrato
$default = $registry->getMapper();           // restituisce il mapper 'default'