CombineAssets
Combiner class used for combining JavaScript and StyleSheet files.
class System\Classes\CombineAssetsThis 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
= false
Cache untouched files.
public
$useDeepHashing
:
bool
= false
When true, cache will be busted when an import is modified. Enabling this feature will make page loading slower.
public
$useMinify
:
bool
= false
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
= ["css","less","scss","sass"]
A list of known StyleSheet extensions.
protected
$filters
:
array
= []
Filters to apply to each file.
protected
static
$jsExtensions
:
array
= ["js"]
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'));
| Property | Type | Description |
|---|---|---|
| $assets | array |
array
Collection of assets |
| $localPath | string |
string
Prefix all assets with this path (optional) |
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') );
| Property | Type | Description |
|---|---|---|
| $assets | array |
array
Collection of assets |
| $destination | string |
string
Write the combined file to this location |
| $localPath | string |
string
Prefix all assets with this path (optional) |
public
getAliases (string $extension = null)
: self
Returns aliases.
| Property | Type | Description |
|---|---|---|
| $extension | string |
string
Extension name. Eg: css |
public
getBundles (string $extension = null)
: self
Returns bundles.
| Property | Type | Description |
|---|---|---|
| $extension | string |
string
Extension name. Eg: css |
public getContents (string $cacheKey) : Response
Returns the combined contents from a prepared cache identifier.
| Property | Type | Description |
|---|---|---|
| $cacheKey | string |
string
Cache identifier. |
Combined file contents.
public
getFilters (string $extension = null)
: self
Returns filters.
| Property | Type | Description |
|---|---|---|
| $extension | string |
string
Extension name. Eg: css |
public init ()
Constructor
public
registerAlias (string $alias, string $file, string $extension = null)
: self
Register an alias to use for a longer file reference.
| Property | Type | Description |
|---|---|---|
| $alias | string |
string
Alias name. Eg: framework |
| $file | string |
string
Path to file to use for alias |
| $extension | string |
string
Extension name. Eg: css |
public
registerBundle (string | array $files, string $destination = null, string $extension = null)
: self
Registers bundle.
| Property | Type | Description |
|---|---|---|
| $files | string | array |
string | array
Files to be registered to bundle |
| $destination | string |
string
Destination file will be compiled to. |
| $extension | string |
string
Extension name. Eg: css |
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');
});
| Property | Type | Description |
|---|---|---|
| $callback | callable |
callable
A callable function. |
public registerFilter (string | array $extension, object $filter) : self
Register a filter to apply to the combining process.
| Property | Type | Description |
|---|---|---|
| $extension | string | array |
string | array
Extension name. Eg: css |
| $filter | object |
object
Collection of files to combine. |
public
resetAliases (string $extension = null)
: self
Clears any registered aliases.
| Property | Type | Description |
|---|---|---|
| $extension | string |
string
Extension name. Eg: css |
public static resetCache () : void
Resets the combiner cache
public
resetFilters (string $extension = null)
: self
Clears any registered filters.
| Property | Type | Description |
|---|---|---|
| $extension | string |
string
Extension name. Eg: css |
protected getCache (string $cacheKey) : array
Look up information about a cache identifier.
| Property | Type | Description |
|---|---|---|
| $cacheKey | string |
string
Cache identifier |
Cache information
protected getCacheKey (array $assets) : string
Builds a unique string based on assets
| Property | Type | Description |
|---|---|---|
| $assets | array |
array
Asset files |
Unique identifier
protected
getCombinedUrl (string $outputFilename = "undefined.css")
: string
Returns the URL used for accessing the combined files.
| Property | Type | Description |
|---|---|---|
| $outputFilename | string |
string
A custom file name to use. |
protected getDeepHashFromAssets (array $assets) : void
Returns a deep hash on filters that support it.
| Property | Type | Description |
|---|---|---|
| $assets | array |
array
List of asset files. |
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/
| Property | Type | Description |
|---|---|---|
| $path | string | null |
string | null
|
The new target path
protected prepareAssets (array $assets) : array
Prepares an array of assets by normalizing the collection and processing aliases.
| Property | Type | Description |
|---|---|---|
| $assets | array |
array
|
protected
prepareCombiner (array $assets, string $rewritePath = null)
: string
Returns the combined contents from a prepared cache identifier.
| Property | Type | Description |
|---|---|---|
| $assets | array |
array
List of asset files. |
| $rewritePath | string |
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.
| Property | Type | Description |
|---|---|---|
| $assets | array |
array
List of asset files. |
| $localPath | string |
string
File extension, used for aesthetic purposes only. |
URL to contents.
protected putCache (string $cacheKey, array $cacheInfo) : bool
Stores information about a asset collection against a cache identifier.
| Property | Type | Description |
|---|---|---|
| $cacheKey | string |
string
Cache identifier. |
| $cacheInfo | array |
array
List of asset files. |
Successful
protected putCacheIndex (string $cacheKey) : bool
Adds a cache identifier to the index store used for performing a reset of the cache.
| Property | Type | Description |
|---|---|---|
| $cacheKey | string |
string
Cache identifier |
Returns false if identifier is already in store
protected setHashOnCombinerFilters ($hash) : void
Busts the cache based on a different cache key.
| Property | Type | Description |
|---|---|---|
| $hash | mixed |
mixed
|
inherited public __clone ()
inherited public __wakeup ()
inherited
public
static
final
forgetInstance ($container = null)
: void
Forget this singleton's instance if it exists
| Property | Type | Description |
|---|---|---|
| $container | mixed |
mixed
|
inherited
public
static
final
instance ($container = null)
: static
Create a new instance of this singleton.
| Property | Type | Description |
|---|---|---|
| $container | mixed |
mixed
|
inherited protected final __construct ()
Constructor.