CombineAssets

Combiner class used for combining JavaScript and StyleSheet files.

 class System\Classes\CombineAssets

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

Traits

Trait Description
Singleton

Singleton trait.

Properties

public $useCache : bool

Cache untouched files.

public $useDeepHashing : bool

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

public $useMinify : bool

Compress (minify) asset files.

protected $aliases : array

Aliases for asset file paths.

protected $bundles : array

Bundles that are compiled to the filesystem.

protected static $cssExtensions : array

A list of known StyleSheet extensions.

protected $filters : array

Filters to apply to each file.

protected static $jsExtensions : array

A list of known JavaScript extensions.

protected $localPath : string

The local path context to find assets.

protected $storagePath : string

The output folder for storing combined files.

private static $callbacks : array

Cache of registration callbacks.

Methods

public static combine (array $assets = [], string $localPath = null) : string

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
Property Description
$assets
array

Collection of assets

$localPath
string

Prefix all assets with this path (optional)

Returns
string

URL to contents.

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

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
Property Description
$assets
array

Collection of assets

$destination
string

Write the combined file to this location

$localPath
string

Prefix all assets with this path (optional)

Returns
void

public getAliases (string $extension = null) : self

Returns aliases.

Parameters
Property Description
$extension
string

Extension name. Eg: css

Returns
self

public getBundles (string $extension = null) : self

Returns bundles.

Parameters
Property Description
$extension
string

Extension name. Eg: css

Returns
self

public getContents (string $cacheKey) : Response

Returns the combined contents from a prepared cache identifier.

Parameters
Property Description
$cacheKey
string

Cache identifier.

Returns
Response

Combined file contents.

public getFilters (string $extension = null) : self

Returns filters.

Parameters
Property Description
$extension
string

Extension name. Eg: css

Returns
self

public init ()

Constructor

Returns
mixed

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

Register an alias to use for a longer file reference.

Parameters
Property Description
$alias
string

Alias name. Eg: framework

$file
string

Path to file to use for alias

$extension
string

Extension name. Eg: css

Returns
self

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

Registers bundle.

Parameters
Property Description
$files
string | array

Files to be registered to bundle

$destination
string

Destination file will be compiled to.

$extension
string

Extension name. Eg: css

Returns
self

public static 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/winter.less');
});
Parameters
Property Description
$callback
callable

A callable function.

Returns
mixed

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

Register a filter to apply to the combining process.

Parameters
Property Description
$extension
string | array

Extension name. Eg: css

$filter
object

Collection of files to combine.

Returns
self

public resetAliases (string $extension = null) : self

Clears any registered aliases.

Parameters
Property Description
$extension
string

Extension name. Eg: css

Returns
self

public static resetCache () : void

Resets the combiner cache

Returns
void

public resetFilters (string $extension = null) : self

Clears any registered filters.

Parameters
Property Description
$extension
string

Extension name. Eg: css

Returns
self

protected getCache (string $cacheKey) : array

Look up information about a cache identifier.

Parameters
Property Description
$cacheKey
string

Cache identifier

Returns
array

Cache information

protected getCacheKey (array $assets) : string

Builds a unique string based on assets

Parameters
Property Description
$assets
array

Asset files

Returns
string

Unique identifier

protected getCombinedUrl (string $outputFilename = "undefined.css") : string

Returns the URL used for accessing the combined files.

Parameters
Property Description
$outputFilename
string

A custom file name to use.

Returns
string

protected getDeepHashFromAssets (array $assets) : void

Returns a deep hash on filters that support it.

Parameters
Property Description
$assets
array

List of asset files.

Returns
void

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

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
Property Description
$path
string | null
Returns
string

The new target path

protected prepareAssets (array $assets) : array

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

Parameters
Property Description
$assets
array
Returns
array

protected prepareCombiner (array $assets, string $rewritePath = null) : string

Returns the combined contents from a prepared cache identifier.

Parameters
Property Description
$assets
array

List of asset files.

$rewritePath
string
Returns
string

Combined file contents.

protected prepareRequest (array $assets, string $localPath = null) : string

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

Parameters
Property Description
$assets
array

List of asset files.

$localPath
string

File extension, used for aesthetic purposes only.

Returns
string

URL to contents.

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

Stores information about a asset collection against a cache identifier.

Parameters
Property Description
$cacheKey
string

Cache identifier.

$cacheInfo
array

List of asset files.

Returns
bool

Successful

protected putCacheIndex (string $cacheKey) : bool

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

Parameters
Property Description
$cacheKey
string

Cache identifier

Returns
bool

Returns false if identifier is already in store

protected setHashOnCombinerFilters ($hash) : void

Busts the cache based on a different cache key.

Parameters
Property Description
$hash
mixed
Returns
void

inherited public __clone ()

Inherited from Singleton
Returns
mixed

inherited public __wakeup ()

Inherited from Singleton
Returns
mixed

inherited public static final forgetInstance ($container = null) : void

Inherited from Singleton

Forget this singleton's instance if it exists

Parameters
Property Description
$container
mixed
Returns
void

inherited public static final instance ($container = null) : static

Inherited from Singleton

Create a new instance of this singleton.

Parameters
Property Description
$container
mixed
Returns
static

inherited protected final __construct ()

Inherited from Singleton

Constructor.

Returns
mixed
Copyright © 2024 Winter CMS