Configuration des assets

Aperçu des options de configuration de Nette Assets.

assets:
	# chemin de base pour résoudre les chemins relatifs des mappers
	basePath: ...            # (string) %wwwDir% par défaut

	# URL de base pour résoudre les URL relatives des mappers
	baseUrl: ...             # (string) %baseUrl% par défaut

	# activer le versionnage des assets globalement ?
	versioning: ...           # (bool) true par défaut

	# définit les mappers d'assets
	mapping: ...             # (array) chemin 'assets' par défaut

basePath définit le répertoire du système de fichiers par défaut pour résoudre les chemins relatifs des mappers. Par défaut, il utilise le répertoire web (%wwwDir%).

baseUrl définit le préfixe d'URL par défaut pour résoudre les URL relatives des mappers. Par défaut, il utilise l'URL racine (%baseUrl%).

L'option versioning détermine globalement si des paramètres de version sont ajoutés aux URL des assets pour invalider le cache. Chaque mapper peut redéfinir ce réglage.

Mappers

Les mappers peuvent être configurés de trois façons : notation simple sous forme de chaîne, notation détaillée sous forme de tableau, ou comme service (à l'aide de la notation entité ClassName(...) ou @serviceName()).

La façon la plus simple de définir un mapper :

assets:
	mapping:
		default: assets     # Crée un mapper de système de fichiers pour %wwwDir%/assets/
		images: img         # Crée un mapper de système de fichiers pour %wwwDir%/img/
		scripts: js         # Crée un mapper de système de fichiers pour %wwwDir%/js/

Chaque mapper crée un FilesystemMapper qui :

cherche les fichiers dans %wwwDir%/<chemin>
génère des URL de la forme %baseUrl%/<chemin>
hérite du réglage global de versionnage

Pour plus de contrôle, utilisez la notation détaillée :

assets:
	mapping:
		images:
			# répertoire où les fichiers sont stockés
			path: ...                    # (string) facultatif, chemin de base (basePath) par défaut

			# préfixe d'URL des liens générés
			url: ...                     # (string) facultatif, path par défaut

			# activer le versionnage pour ce mapper ?
			versioning: ...              # (bool) facultatif, hérite du réglage global

			# ajouter automatiquement la ou les extensions lors de la recherche de fichiers
			extension: ...               # (string|array) facultatif, null par défaut

Comprendre comment les valeurs de configuration sont résolues :

Résolution des chemins: les chemins relatifs sont résolus à partir de basePath (ou de %wwwDir% si basePath n'est pas défini); les chemins absolus sont utilisés tels quels
Résolution des URL: les URL relatives sont résolues à partir de baseUrl (ou de %baseUrl% si baseUrl n'est pas défini); les URL absolues (avec un schéma ou //) sont utilisées telles quelles (une URL // reçoit son schéma de baseUrl); si url n'est pas indiquée, elle prend la valeur de path

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

	mapping:
		# Chemin et URL relatifs
		images:
			path: img                    # Résolu en : /var/www/project/www/img
			url: images                  # Résolu en : https://example.com/assets/images

		# Chemin et URL absolus
		uploads:
			path: /var/shared/uploads    # Utilisé tel quel : /var/shared/uploads
			url: https://cdn.example.com # Utilisé tel quel : https://cdn.example.com

		# Seul le chemin est indiqué
		styles:
			path: css                    # Chemin : /var/www/project/www/css
										 # URL : https://example.com/assets/css

Mappers personnalisés

Pour des mappers personnalisés, référencez un service existant avec @serviceName, ou définissez-le directement avec ClassName(arguments) ou un simple nom de classe :

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

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

Mapper Vite

Le mapper Vite exige seulement que vous ajoutiez type: vite. Voici la liste complète des options de configuration :

assets:
	mapping:
		default:
			# type de mapper (obligatoire pour Vite)
			type: vite                # (string) obligatoire, doit valoir 'vite'

			# répertoire de sortie du build Vite
			path: ...                 # (string) facultatif, chemin de base (basePath) par défaut

			# préfixe d'URL des assets construits
			url: ...                  # (string) facultatif, path par défaut

			# emplacement du fichier manifest de Vite
			manifest: ...             # (string) facultatif, relatif à path, <path>/.vite/manifest.json par défaut

			# configuration du serveur de développement Vite
			devServer: ...            # (bool|string) facultatif, true par défaut

			# versionnage des fichiers du répertoire public
			versioning: ...           # (bool) facultatif, hérite du réglage global

			# extension automatique pour les fichiers du répertoire public
			extension: ...            # (string|array) facultatif, null par défaut

L'option devServer détermine la façon dont les assets sont chargés pendant le développement :

true (par défaut) – détecte automatiquement un serveur de développement Vite en cours d'exécution (via le fichier .vite/nette.json que le plugin Vite de Nette crée dans le répertoire de build). Si le serveur de développement tourne et que votre application est en mode débogage, les assets sont chargés depuis lui avec prise en charge du hot module replacement. Si le serveur de développement ne tourne pas, les assets sont chargés depuis les fichiers construits du répertoire public.
false – désactive complètement l'intégration du serveur de développement. Les assets sont toujours chargés depuis les fichiers construits.
URL personnalisée (par exemple https://localhost:5173) – indique manuellement l'URL du serveur de développement, protocole et port compris. Utile lorsque le serveur de développement tourne sur un autre hôte ou un autre port. Comme la détection automatique, cela ne s'applique qu'en mode débogage ; en production, ce sont toujours les fichiers construits qui sont utilisés.

Les options versioning et extension ne s'appliquent qu'aux fichiers du répertoire public de Vite qui ne sont pas traités par Vite.

Configuration manuelle

Quand vous n'utilisez pas Nette DI, configurez les mappers manuellement :

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

$registry = new Registry;

// Ajoute un mapper de système de fichiers
$registry->addMapper('images', new FilesystemMapper(
	baseUrl: 'https://example.com/img',
	basePath: __DIR__ . '/www/img',
	extensions: ['webp', 'jpg', 'png'],
	versioning: true,
));

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

Vous pouvez aussi récupérer n'importe quel mapper enregistré par son nom à l'aide de la méthode getMapper() :

$mapper = $registry->getMapper('images');   // renvoie le mapper enregistré
$default = $registry->getMapper();           // renvoie le mapper 'default'