CombineAssets
in package
Uses
Singleton
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
Tags
Table of Contents
- $useCache : bool
- $useDeepHashing : bool
- $useMinify : bool
- $aliases : array<string|int, mixed>
- $bundles : array<string|int, mixed>
- $cssExtensions : array<string|int, mixed>
- $filters : array<string|int, mixed>
- $instance : mixed
- $jsExtensions : array<string|int, mixed>
- $localPath : string
- $storagePath : string
- $callbacks : array<string|int, mixed>
- __clone() : mixed
- __wakeup() : mixed
- combine() : string
- Combines JavaScript or StyleSheet file references to produce a page relative URL to the combined contents.
- combineToFile() : void
- Combines a collection of assets files to a destination file
- forgetInstance() : mixed
- Forget this singleton's instance if it exists
- getAliases() : self
- Returns aliases.
- getBundles() : self
- Returns bundles.
- getContents() : string
- Returns the combined contents from a prepared cache identifier.
- getFilters() : self
- Returns filters.
- init() : mixed
- Constructor
- instance() : mixed
- Create a new instance of this singleton.
- registerAlias() : self
- Register an alias to use for a longer file reference.
- registerBundle() : self
- Registers bundle.
- registerCallback() : mixed
- Registers a callback function that defines bundles.
- registerFilter() : self
- Register a filter to apply to the combining process.
- resetAliases() : self
- Clears any registered aliases.
- resetCache() : void
- Resets the combiner cache
- resetFilters() : self
- Clears any registered filters.
- __construct() : mixed
- Constructor.
- getCache() : array<string|int, mixed>
- Look up information about a cache identifier.
- getCacheKey() : string
- Builds a unique string based on assets
- getCombinedUrl() : string
- Returns the URL used for accessing the combined files.
- getDeepHashFromAssets() : void
- Returns a deep hash on filters that support it.
- getTargetPath() : string
- Returns the target path for use with the combiner. The target path helps generate relative links within CSS.
- prepareAssets() : array<string|int, mixed>
- Prepares an array of assets by normalizing the collection and processing aliases.
- prepareCombiner() : string
- Returns the combined contents from a prepared cache identifier.
- prepareRequest() : string
- Combines asset file references of a single type to produce a URL reference to the combined contents.
- putCache() : bool
- Stores information about a asset collection against a cache identifier.
- putCacheIndex() : bool
- Adds a cache identifier to the index store used for performing a reset of the cache.
- setHashOnCombinerFilters() : void
- Busts the cache based on a different cache key.
Properties
$useCache
public
bool
$useCache
= false
Cache untouched files.
$useDeepHashing
public
bool
$useDeepHashing
= false
When true, cache will be busted when an import is modified. Enabling this feature will make page loading slower.
$useMinify
public
bool
$useMinify
= false
Compress (minify) asset files.
$aliases
protected
array<string|int, mixed>
$aliases
= []
Aliases for asset file paths.
$bundles
protected
array<string|int, mixed>
$bundles
= []
Bundles that are compiled to the filesystem.
$cssExtensions
protected
static array<string|int, mixed>
$cssExtensions
= ['css', 'less', 'scss', 'sass']
A list of known StyleSheet extensions.
$filters
protected
array<string|int, mixed>
$filters
= []
Filters to apply to each file.
$instance
protected
static mixed
$instance
$jsExtensions
protected
static array<string|int, mixed>
$jsExtensions
= ['js']
A list of known JavaScript extensions.
$localPath
protected
string
$localPath
The local path context to find assets.
$storagePath
protected
string
$storagePath
The output folder for storing combined files.
$callbacks
private
static array<string|int, mixed>
$callbacks
= []
Cache of registration callbacks.
Methods
__clone()
public
__clone() : mixed
Return values
mixed —__wakeup()
public
__wakeup() : mixed
Return values
mixed —combine()
Combines JavaScript or StyleSheet file references to produce a page relative URL to the combined contents.
public
static combine([array<string|int, mixed> $assets = [] ][, string $localPath = null ]) : string
$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
- $assets : array<string|int, mixed> = []
-
Collection of assets
- $localPath : string = null
-
Prefix all assets with this path (optional)
Return values
string —URL to contents.
combineToFile()
Combines a collection of assets files to a destination file
public
combineToFile(array<string|int, mixed> $assets, string $destination[, string $localPath = null ]) : void
$assets = [ 'assets/less/header.less', 'assets/less/footer.less', ];
CombineAssets::combineToFile( $assets, base_path('themes/website/assets/theme.less'), base_path('themes/website') );
Parameters
- $assets : array<string|int, mixed>
-
Collection of assets
- $destination : string
-
Write the combined file to this location
- $localPath : string = null
-
Prefix all assets with this path (optional)
Return values
void —forgetInstance()
Forget this singleton's instance if it exists
public
final static forgetInstance() : mixed
Return values
mixed —getAliases()
Returns aliases.
public
getAliases([string $extension = null ]) : self
Parameters
- $extension : string = null
-
Extension name. Eg: css
Return values
self —getBundles()
Returns bundles.
public
getBundles([string $extension = null ]) : self
Parameters
- $extension : string = null
-
Extension name. Eg: css
Return values
self —getContents()
Returns the combined contents from a prepared cache identifier.
public
getContents(string $cacheKey) : string
Parameters
- $cacheKey : string
-
Cache identifier.
Return values
string —Combined file contents.
getFilters()
Returns filters.
public
getFilters([string $extension = null ]) : self
Parameters
- $extension : string = null
-
Extension name. Eg: css
Return values
self —init()
Constructor
public
init() : mixed
Return values
mixed —instance()
Create a new instance of this singleton.
public
final static instance() : mixed
Return values
mixed —registerAlias()
Register an alias to use for a longer file reference.
public
registerAlias(string $alias, string $file[, string $extension = null ]) : self
Parameters
- $alias : string
-
Alias name. Eg: framework
- $file : string
-
Path to file to use for alias
- $extension : string = null
-
Extension name. Eg: css
Return values
self —registerBundle()
Registers bundle.
public
registerBundle(string|array<string|int, mixed> $files[, string $destination = null ][, string $extension = null ]) : self
Parameters
- $files : string|array<string|int, mixed>
-
Files to be registered to bundle
- $destination : string = null
-
Destination file will be compiled to.
- $extension : string = null
-
Extension name. Eg: css
Return values
self —registerCallback()
Registers a callback function that defines bundles.
public
static registerCallback(callable $callback) : mixed
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
- $callback : callable
-
A callable function.
Return values
mixed —registerFilter()
Register a filter to apply to the combining process.
public
registerFilter(string|array<string|int, mixed> $extension, object $filter) : self
Parameters
- $extension : string|array<string|int, mixed>
-
Extension name. Eg: css
- $filter : object
-
Collection of files to combine.
Return values
self —resetAliases()
Clears any registered aliases.
public
resetAliases([string $extension = null ]) : self
Parameters
- $extension : string = null
-
Extension name. Eg: css
Return values
self —resetCache()
Resets the combiner cache
public
static resetCache() : void
Return values
void —resetFilters()
Clears any registered filters.
public
resetFilters([string $extension = null ]) : self
Parameters
- $extension : string = null
-
Extension name. Eg: css
Return values
self —__construct()
Constructor.
protected
final __construct() : mixed
Return values
mixed —getCache()
Look up information about a cache identifier.
protected
getCache(string $cacheKey) : array<string|int, mixed>
Parameters
- $cacheKey : string
-
Cache identifier
Return values
array<string|int, mixed> —Cache information
getCacheKey()
Builds a unique string based on assets
protected
getCacheKey(array<string|int, mixed> $assets) : string
Parameters
- $assets : array<string|int, mixed>
-
Asset files
Return values
string —Unique identifier
getCombinedUrl()
Returns the URL used for accessing the combined files.
protected
getCombinedUrl([string $outputFilename = 'undefined.css' ]) : string
Parameters
- $outputFilename : string = 'undefined.css'
-
A custom file name to use.
Return values
string —getDeepHashFromAssets()
Returns a deep hash on filters that support it.
protected
getDeepHashFromAssets(array<string|int, mixed> $assets) : void
Parameters
- $assets : array<string|int, mixed>
-
List of asset files.
Return values
void —getTargetPath()
Returns the target path for use with the combiner. The target path helps generate relative links within CSS.
protected
getTargetPath([string|null $path = null ]) : string
/combine returns combine/ /index.php/combine returns index-php/combine/
Parameters
- $path : string|null = null
Return values
string —The new target path
prepareAssets()
Prepares an array of assets by normalizing the collection and processing aliases.
protected
prepareAssets(array<string|int, mixed> $assets) : array<string|int, mixed>
Parameters
- $assets : array<string|int, mixed>
Return values
array<string|int, mixed> —prepareCombiner()
Returns the combined contents from a prepared cache identifier.
protected
prepareCombiner(array<string|int, mixed> $assets[, string $rewritePath = null ]) : string
Parameters
- $assets : array<string|int, mixed>
-
List of asset files.
- $rewritePath : string = null
Return values
string —Combined file contents.
prepareRequest()
Combines asset file references of a single type to produce a URL reference to the combined contents.
protected
prepareRequest(array<string|int, mixed> $assets[, string $localPath = null ]) : string
Parameters
- $assets : array<string|int, mixed>
-
List of asset files.
- $localPath : string = null
-
File extension, used for aesthetic purposes only.
Return values
string —URL to contents.
putCache()
Stores information about a asset collection against a cache identifier.
protected
putCache(string $cacheKey, array<string|int, mixed> $cacheInfo) : bool
Parameters
- $cacheKey : string
-
Cache identifier.
- $cacheInfo : array<string|int, mixed>
-
List of asset files.
Return values
bool —Successful
putCacheIndex()
Adds a cache identifier to the index store used for performing a reset of the cache.
protected
putCacheIndex(string $cacheKey) : bool
Parameters
- $cacheKey : string
-
Cache identifier
Return values
bool —Returns false if identifier is already in store
setHashOnCombinerFilters()
Busts the cache based on a different cache key.
protected
setHashOnCombinerFilters(mixed $hash) : void
Parameters
- $hash : mixed