1. Documentation
  2. API
  3. System
  4. Classes
  5. CombineAssets

System\Classes\CombineAssets

Overview

CombineAssets is 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.enable_asset_cache - Cache untouched assets
  • cms.enable_asset_minify - Compress assets using minification
  • cms.enable_asset_deep_hashing - Advanced caching of imports

Public Properties

public bool $useCache

useCache to cache untouched files.

public bool $useMinify

useMinify compress (minify) asset files.

public bool $useDeepHashing

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

jsExtensions is a list of known JavaScript extensions.

protected static array $cssExtensions

cssExtensions is 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 string $localPath

localPath context to find assets.

Public Methods

public __construct()

public __construct(): void

__construct this class

public static combine()

public static combine(
    array $assets = [],
    string $pathPrefix = 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'));

public combineToFile()

public combineToFile(
    array $assets,
    string $destination,
    string $pathPrefix = 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')
);

public getAliases()

public getAliases(string $extension = null): self

getAliases returns aliases.

public getBundles()

public getBundles(string $extension = null): self

getBundles returns bundles.

public getContents()

public getContents(string $cacheKey): string

Returns the combined contents from a prepared cache identifier.

public getFilters()

public getFilters($extension = null, $isProduction = false): array

getFilters returns all defined filters for a given extension

public static instance()

public static instance(): static

instance creates a new instance of this singleton

public registerAlias()

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

registerAlias to use for a longer file reference.

public registerBundle()

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

public static registerCallback()

public static registerCallback(callable $callback): void

registerCallback 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');
});

public registerFilter()

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

registerFilter to apply to the combining process.

public resetAliases()

public resetAliases(string $extension = null): self

resetAliases clears any registered aliases.

public static resetCache()

public static resetCache(): void

resetCache resets the combiner cache

public resetFilters()

public resetFilters(string $extension = null): self

resetFilters clears any registered filters.

Protected Methods

protected getAssetic()

protected getAssetic(): void

protected getCache()

protected getCache(string $cacheKey): array

getCache looks up information about a cache identifier.

protected getCacheKey()

protected getCacheKey(array $assets): string

getCacheKey builds a unique string based on assets

protected getCombinedUrl()

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

Returns the URL used for accessing the combined files.

protected getTargetPath()

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

getTargetPath 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/

protected prepareAssets()

protected prepareAssets(array $assets): array

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

protected prepareCombiner()

protected prepareCombiner(
    array $assets,
    string $rewritePath = null,
    $options = []
): October\Rain\Assetic\Asset\AssetInterface

prepareCombiner returns the combined contents from a prepared cache identifier.

protected prepareRequest()

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

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

protected putCache()

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

putCache stores information about a asset collection against a cache identifier.

protected putCacheIndex()

protected putCacheIndex(string $cacheKey): bool

putCacheIndex adds a cache identifier to the index store used for performing a reset of the cache. Returns false if identifier is already in store

protected setActiveSiteContext()

protected setActiveSiteContext($siteId = null, $theme = null): void

setActiveSiteContext sets the theme and site, if provided

protected setLocalPath()

protected setLocalPath($path = null): void