Download the PHP package nette/assets without Composer

Nette Assets

 <!---->

Introduction

Nette Assets is a powerful asset management library for PHP that helps you:

✅ organize and serve your static assets (images, CSS, JavaScript, audio, etc.)
✅ handle asset versioning automatically
✅ get image dimensions without hassle
✅ verify asset existence
✅ support multiple storage backends
✅ integrate with Vite for modern frontend development

The library provides a clean and intuitive API to manage static assets in your web applications with a focus on developer experience and performance.

 <!---->

Installation and Requirements

The recommended way to install is via Composer:

Nette Assets requires PHP 8.1 or higher.

 <!---->

Core Concepts

The library revolves around a few key components:

• Asset: An interface representing a single static asset. All assets provide a public URL via __toString(). Different asset types (like ImageAsset, ScriptAsset, AudioAsset) provide type-specific properties.
• Mapper: An interface responsible for taking an asset reference (like app.js or images/logo.png) and resolving it into an Asset object. Different mappers can fetch assets from various sources (filesystem, CDN, cloud storage, manifest files). FilesystemMapper is the built-in implementation for serving files from a local directory. If the requested asset cannot be found, the mapper throws an AssetNotFoundException.
• Registry: A central service that holds all configured Mapper instances, each identified by a unique string ID (e.g., 'default', 'audio', 'images'). It provides the main entry point (getAsset()) for retrieving assets using a qualified reference, which throws AssetNotFoundException if the requested asset cannot be found. For cases where handling non-existent assets without exceptions is preferred, it also provides tryGetAsset(), which returns null instead of throwing an exception.
• Qualified Reference: This identifies the specific asset you want to retrieve via the Registry. It supports three formats:
  • A simple string reference (e.g., 'app.js') which uses the default mapper.
  • A prefixed string mapper:reference (e.g., 'audio:podcast.mp3') which specifies the mapper explicitly.
  • An array [mapper, reference] (e.g., ['images', 'logo.png']) which also specifies the mapper explicitly.

 <!---->

Asset Types

The library provides specialized asset interfaces and implementations for different content types:

• ImageAsset - Images with width, height, alternative text, and lazy loading support
• ScriptAsset - JavaScript files with dependencies, integrity hashes, and development mode support
• StyleAsset - CSS files with media queries and dependencies
• AudioAsset - Audio files with duration information
• VideoAsset - Video files with dimensions, duration, poster image, and autoplay settings
• GenericAsset - Generic files

 <!---->

Configuration

Configuration is typically done in your application's NEON configuration file under the assets key.

You can define a base filesystem path and URL prefix under the main assets: key. These serve as the foundation from which relative paths defined in mappers are resolved.

However, explicit configuration is often optional. If omitted, path typically defaults to your public web root (%wwwDir%), and url defaults to the application's base URL path (for example https://domain/).

The mapping section defines your named mappers. Each key in mapping is a mapper identifier (e.g., default, audio, images). Now, let's see how different mapper configurations under mapping behave relative to the base settings:

 <!---->

Extension Autodetection

The mapper can automatically handle file extensions if the reference doesn't include one. You configure this using the extension option within a mapper's definition.

 <!---->

Using Custom Mappers

By default, the configurations in the mapping section implicitly create instances of the built-in Nette\Assets\FilesystemMapper. If FilesystemMapper doesn't fit your needs (e.g., you need to load assets from a database, S3, or read a manifest file generated by build tools like Vite or Webpack), you can provide an instance of your own class implementing Nette\Assets\Mapper:

 <!---->

Retrieving Assets

Retrieve assets via the Registry service, typically injected where needed. The main method is getAsset():

 <!---->

Usage in Latte

Assuming Latte helper asset is registered to call the Registry:

The resulting URL string obtained from $asset->url or {asset(...)} will include versioning information if provided by the mapper.

 <!---->

Asset Versioning

The built-in FilesystemMapper supports asset versioning. By default, it automatically appends a version query parameter based on the file's last modification time (filemtime):

generates, for example:

This helps with browser cache invalidation. Custom mappers can implement different versioning strategies (e.g., using content hashes from a build manifest).

You can disable versioning per asset:

Or in configuration file:

 <!---->

Image Dimensions

When using FilesystemMapper (or any mapper returning a FileAsset), you can easily retrieve image dimensions (assuming corresponding Latte helpers are registered):

FileAsset provides $duration property for estimating MP3 duration (most reliable for Constant Bitrate files).

Entry Points and Bundle Support

Nette Assets supports modern bundlers and build tools that generate multiple files from a single entry point:

• The EntryAsset class implements both ScriptAsset and StyleAsset interfaces
• It manages dependencies automatically and provides information about the main entry point
• The renderAsset Latte function automatically generates HTML tags for all related files

Vite Integration

Vite integration automatically handles:

• Main entry points
• Dynamic imports (chunks)
• CSS extraction
• Development mode with HMR support

Usage in Latte Templates