System\Classes\CombineAssets

Source: ~/modules/system/classes/CombineAssets.php

Combiner class used for combining JavaScript and StyleSheet files.

This works by taking a collection of asset locations, serializing them, then storing them in the session with a unique ID. The ID is then used to generate a URL to the /combine route via the system controller.

When the combine route is hit, the unique ID is used to serve up the assets — minified, compiled or both. Special E-Tags are used to prevent compilation and delivery of cached assets that are unchanged.

Use the CombineAssets::combine method to combine your own assets.

The functionality of this class is controlled by these config items:

• cms.enableAssetCache - Cache untouched assets
• cms.enableAssetMinify - Compress assets using minification
• cms.enableAssetDeepHashing - Advanced caching of imports

See also:

• System controller
• Session service

Public properties

public bool $useCache

Cache untouched files.

public bool $useMinify

Compress (minify) asset files.

public bool $useDeepHashing

When true, cache will be busted when an import is modified. Enabling this feature will make page loading slower.

Protected properties

protected static array $jsExtensions

A list of known JavaScript extensions.

protected static array $cssExtensions

A list of known StyleSheet extensions.

protected array $aliases

Aliases for asset file paths.

protected array $bundles

Bundles that are compiled to the filesystem.

protected array $filters

Filters to apply to each file.

protected string $localPath

The local path context to find assets.

protected string $storagePath

The output folder for storing combined files.

protected static $instance

Public methods

public void __clone()

public void __wakeup()

public static string combine(array $assets=array(), string $localPath=NULL)

Combines JavaScript or StyleSheet file references to produce a page relative URL to the combined contents.

$assets = [
    'assets/vendor/mustache/mustache.js',
    'assets/js/vendor/jquery.ui.widget.js',
    'assets/js/vendor/canvas-to-blob.js',
];

CombineAssets::combine($assets, base_path('plugins/acme/blog'));

Parameters

• array $assets - Collection of assets
• string $localPath - Prefix all assets with this path (optional)

public void combineToFile(array $assets, string $destination, string $localPath=NULL)

Combines a collection of assets files to a destination file

$assets = [
    'assets/less/header.less',
    'assets/less/footer.less',
];

CombineAssets::combineToFile(
    $assets,
    base_path('themes/website/assets/theme.less'),
    base_path('themes/website')
);

Parameters

• array $assets - Collection of assets
• string $destination - Write the combined file to this location
• string $localPath - Prefix all assets with this path (optional)

public static void forgetInstance()

Forget this singleton's instance if it exists

public self getAliases(string $extension=NULL)

Returns aliases.

Parameters

• string $extension - Extension name. Eg: css

public self getBundles(string $extension=NULL)

Returns bundles.

Parameters

• string $extension - Extension name. Eg: css

public string getContents(string $cacheKey)

Returns the combined contents from a prepared cache identifier.

Parameters

• string $cacheKey - Cache identifier.

public self getFilters(string $extension=NULL)

Returns filters.

Parameters

• string $extension - Extension name. Eg: css

public void init()

Constructor

public static void instance()

Create a new instance of this singleton.

public self registerAlias(string $alias, string $file, string $extension=NULL)

Register an alias to use for a longer file reference.

Parameters

• string $alias - Alias name. Eg: framework
• string $file - Path to file to use for alias
• string $extension - Extension name. Eg: css

public self registerBundle(string|array $files, string $destination=NULL, string $extension=NULL)

Registers bundle.

Parameters

• string|array $files - Files to be registered to bundle
• string $destination - Destination file will be compiled to.
• string $extension - Extension name. Eg: css

public static void registerCallback(callable $callback)

Registers a callback function that defines bundles. The callback function should register bundles by calling the manager's registerBundle method. This instance is passed to the callback function as an argument. Usage:

CombineAssets::registerCallback(function ($combiner) {
    $combiner->registerBundle('~/modules/backend/assets/less/october.less');
});

Parameters

• callable $callback - A callable function.

public self registerFilter(string|array $extension, object $filter)

Register a filter to apply to the combining process.

Parameters

• string|array $extension - Extension name. Eg: css
• object $filter - Collection of files to combine.

public self resetAliases(string $extension=NULL)

Clears any registered aliases.

Parameters

• string $extension - Extension name. Eg: css

public static void resetCache()

Resets the combiner cache

public self resetFilters(string $extension=NULL)

Clears any registered filters.

Parameters

• string $extension - Extension name. Eg: css

Protected methods

protected void __construct()

Constructor.

protected array getCache(string $cacheKey)

Look up information about a cache identifier.

Parameters

• string $cacheKey - Cache identifier

protected string getCacheKey(array $assets)

Builds a unique string based on assets

Parameters

• array $assets - Asset files

protected string getCombinedUrl(string $outputFilename='undefined.css')

Returns the URL used for accessing the combined files.

Parameters

• string $outputFilename - A custom file name to use.

protected void getDeepHashFromAssets(array $assets)

Returns a deep hash on filters that support it.

Parameters

• array $assets - List of asset files.

protected string getTargetPath(string|null $path=NULL)

Returns the target path for use with the combiner. The target path helps generate relative links within CSS.

/combine returns combine/ /index.php/combine returns index-php/combine/

Parameters

• string|null $path

protected array prepareAssets(array $assets)

Prepares an array of assets by normalizing the collection and processing aliases.

Parameters

• array $assets

protected string prepareCombiner(array $assets, string $rewritePath=NULL)

Returns the combined contents from a prepared cache identifier.

Parameters

• array $assets - List of asset files.
• string $rewritePath

protected string prepareRequest(array $assets, string $localPath=NULL)

Combines asset file references of a single type to produce a URL reference to the combined contents.

Parameters

• array $assets - List of asset files.
• string $localPath - File extension, used for aesthetic purposes only.

protected bool putCache(string $cacheKey, array $cacheInfo)

Stores information about a asset collection against a cache identifier.

Parameters

• string $cacheKey - Cache identifier.
• array $cacheInfo - List of asset files.

protected bool putCacheIndex(string $cacheKey)

Adds a cache identifier to the index store used for performing a reset of the cache.

Parameters

• string $cacheKey - Cache identifier

protected void setHashOnCombinerFilters($hash)

Busts the cache based on a different cache key.

Parameters

• $hash