Configurazione degli Assets

Panoramica delle opzioni di configurazione per Nette Assets.

assets:
	# percorso base per la risoluzione dei percorsi relativi del mapper
	basePath: ...            # (string) predefinito a %wwwDir%

	# URL base per la risoluzione degli URL relativi del mapper
	baseUrl: ...             # (string) predefinito a %baseUrl%

	# abilitare il versioning degli asset globalmente?
	versioning: ...           # (bool) predefinito a true

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

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

baseUrl imposta il prefisso URL predefinito per la risoluzione degli URL relativi nei mapper. Per impostazione predefinita, usa l'URL radice (%baseUrl%).

L'opzione versioning controlla globalmente se i parametri di versione vengono aggiunti agli URL degli asset per il cache busting. I singoli mapper possono sovrascrivere questa impostazione.

Mappers

I mapper possono essere configurati in tre modi: notazione stringa semplice, notazione array dettagliata o come riferimento a un servizio.

Il modo più semplice per 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 come %baseUrl%/<path>
• Eredita l'impostazione di versioning globale

Per un maggiore controllo, usa la notazione dettagliata:

assets:
	mapping:
		images:
			# directory dove sono memorizzati i file
			path: ...                    # (string) opzionale, predefinito a ''

			# prefisso URL per i link generati
			url: ...                     # (string) opzionale, predefinito a path

			# abilitare il versioning per questo mapper?
			versioning: ...              # (bool) opzionale, eredita l'impostazione globale

			# aggiungi automaticamente estensione(i) durante la ricerca di file
			extension: ...               # (string|array) opzionale, predefinito a null

Comprendere come vengono risolti i valori di configurazione:

Risoluzione del percorso

I percorsi relativi vengono risolti da basePath (o %wwwDir% se basePath non è impostato)

I percorsi assoluti vengono usati così come sono

URL Risoluzione

Gli URL relativi vengono risolti da baseUrl (o %baseUrl% se baseUrl non è impostato)

Gli URL assoluti (con schema o //) vengono usati così come sono

Se url non è specificato, usa 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ì come è: /var/shared/uploads
			url: https://cdn.example.com # Usato così come è: https://cdn.example.com

		# Solo percorso specificato
		styles:
			path: css                    # Percorso: /var/www/project/www/css
										 # URL: https://example.com/assets/css

Mappers Personalizzati

Per i mapper personalizzati, fai riferimento o definisci un servizio:

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

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

Vite Mapper

Il mapper Vite richiede solo di aggiungere type: vite. Questa è una lista completa delle opzioni di configurazione:

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

			# directory di output della build di Vite
			path: ...                 # (string) opzionale, predefinito a ''

			# prefisso URL per gli asset costruiti
			url: ...                  # (string) opzionale, predefinito a path

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

			# configurazione del server di sviluppo Vite
			devServer: ...            # (bool|string) opzionale, predefinito a true

			# versioning per i file della directory pubblica
			versioning: ...           # (bool) opzionale, eredita l'impostazione globale

			# estensione automatica per i file della directory pubblica
			extension: ...            # (string|array) opzionale, predefinito a null

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

• true (predefinito) – Rileva automaticamente il server di sviluppo Vite sull'host e la porta attuali. Se il server di sviluppo è in esecuzione e la tua applicazione è in modalità debug, gli asset vengono caricati da esso con supporto per l'Hot Module Replacement. Se il server di sviluppo non è in esecuzione, gli asset vengono caricati dai file costruiti nella directory pubblica.
• false – Disabilita completamente l'integrazione del server di sviluppo. Gli asset vengono sempre caricati dai file costruiti.
• URL personalizzato (es. https://localhost:5173) – Specifica manualmente l'URL del server di sviluppo inclusi protocollo e porta. Utile quando il server di sviluppo è in esecuzione su un host o una porta diversa.

Le opzioni versioning ed extension si applicano solo ai file nella directory pubblica di Vite che non vengono elaborati da Vite.

Configurazione Manuale

Quando non si usa Nette DI, configura i mapper manualmente:

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

$registry = new Registry;

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

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