Configuration

Asset Compress is configured with an ini file. You can also define configuration data programmatically, but that requires deeper application integration.

The ini file is broken into a number of sections that allow you to define general behavior for file extensions as well as define build files, and provide filter configuration.

A sample ini file would look like:

; Define an extension type.
; build targets are prefixed with this value
; are connected when the ini file is parsed.
[js]
baseUrl = http://cdn.example.com
timestamp = true
paths[] = WEBROOT/js/*
cachePath = WEBROOT/cache_js/
filters[] = Sprockets
filters[] = YuiJs

; filters can have configuration as well.
[filter_YuiJsFilter]
path = /path/to/yuicompressor

[filter_Uglifyjs]
uglify = /path/to/uglify-js

[base.js]
files[] = jquery.js
files[] = jquery-ui.js

; Each target should have a section defining the files
; everything after js_ is considered the build file.
; all files included in the build are relative to the parent
; paths key.
;
; targets can include their own filters, or extend
; other assets. By extending assets you can keep configuration
; DRY
[libs.js]
extend = base.js
files[] = class.js
filters[] = Uglifyjs

; Create the CSS extension
[css]
baseUrl = http://cdn.example.com
paths[] = WEBROOT/css/
cachePath = WEBROOT/cache_css/

[all.css]
files[] = layout.css
filters[] = cssmin

There are a number of sections to a configuration file, so we'll go through them one at a time.

Extension sections, js and css

Extension settings allow you to define the basic behavior for file extensions AssetCompress will be handling. Normally there are sections for [js] and [css]. The section name should match the extension of the files being built. Each section can define the following keys:

• baseUrl Defines a base url that all assets should be included from, useful when you want to include assets from a CDN or static file domain. Should include the full domain name of the alternative server. e.g. http://cdn.example.com. No trailing slash is needed, it is also assumed that the complete static build files will be available on this alternate domain.
• timestamp Should generated assets of the given extension have timestamps included in their filenames. This is useful when you want to bust browser caches when files change. See the section on timestamps for more information.
• paths[] The paths that Mini-Asset will find the component files for a build file. You can have as many paths as necessary and they will be searched in the order defined. Any application constants that contain paths will be available in the configuration file.
• cachePath The path assets should be 'cached' or saved to once built. This value needs to be set if you want to generate static build files with the plugin. A trailing slash is required
• filters[] Define any number of filters to be applied to the all the built assets with this extension. The filters will be applied in the order they are defined.

Timestamping

If you set timestamp = true for an extension, MiniAsset will generate files with timestamps. In addition, it will create the file TMP/mini_asset_build_time. This file contains an array of build files and their timestamps. It should be deployed with your application, as it contains information used by the library to locate and correctly link to build files.

Build file sections

Build file sections contain the build file name. For example, in the sample file above [libs.js] defines a JavaScript build file named libs.js. Build files need to be unique across your entire application. Defining duplicate build files will result in the last defined one being used. Build file sections can have the following keys:

• baseUrl Defines a base url that all assets should be included from, useful when you want to include assets from a CDN or static file domain. Should include the full domain name of the alternative server. e.g. http://cdn.example.com. No trailing slash is needed, it is also assumed that the complete static build files will be available on this alternate domain.
• files[] The files that compose this build file. Files will be concatenated in the order they are defined in this setting. Files are located on the extensions paths[]. If a file is not found, an exception is raised. There are a few prefixes that can be used to use files outside the configured paths. See below for special file types.
• filters[] Additional filters that are applied to this build. Additional filters will be merged in with the extension wide filters, and be applied afterwards.

Special file types

Glob Files

Glob files are used by setting a files option to use a glob path. Using glob paths allows you to easily include a collection of files. For example:

[accounts.js]
files[] = WEBROOT/js/accounts/*.mustache
files[] = WEBROOT/js/accounts/*.js

The above would include all the mustache and js files in the accounts directory.

Callback Files

Callback files allow you to use a static class method, or a global function to generate files to include in a target.

[accounts.js]
files[] = 'AccountsAssets::getFiles()'

⚠️ Remember to quote callback names. If you forget you'll get a ini parse error.

Filter configuration sections

Filters can have settings defined for them. These settings are passed into the filters, settings() method. There is no list of generally supported keys, as each filter has different requirements. Filter sections are prefixed by filter_ and then the name of the filter. So [filter_Uglifyjs] defines the settings for the Uglifyjs filter.

Special file types

Theme assets

Before you can use themes make sure you enable the themes that have you want themed assets built for.

[General]
themes[] = red
themes[] = modern

The above will whitelist the the 'red' and 'modern' themes to have themed assets built for them when the CLI tool is used.

You can define build files that use assets in themes. When the shell is run, a build file will be generated for each theme installed. This assumes that each theme has the same set of assets that need to be compressed. The theme name will be prepended to the generated asset name. A build definition would look like:

[app.css]
theme = true
files[] = reset.css
files[] = theme:css/design.css

Files prefixed with theme: or t: will be found inside the active theme. In the development controller, the current request's theme will be used. In the shell, a build file for each installed theme will be generated if possible. Build files for themes will be prefixed with the theme name to ensure unique files after generation. If you had a red theme, the above build would create red-app.css when generated.

Note Theme asset paths are relative to the webroot directory of the theme.

Plugin Assets

Plugin assets can be included using the p or plugin prefix.

[app.css]
files[] = p:DebugKit:css/debug_toolbar.css
files[] = plugin:Blog:css/blog.css

The plugin and p prefixes are equivalent, and should be followed by the plugin name, and then the relative path from the plugin's webroot directory. Using plugin assets requires that the plugin is loaded via Plugin in your bootstrap.php file.

In addition to using plugin assets, each plugin in your application can provide an asset_compress.ini file in its config/ directory. When AssetCompress loads configuration all asset_compress.ini files in plugins will also be loaded and merged into the configuration data.

Filter configuration sections

Filters can have settings defined for them. These settings are passed into the filters, settings() method. There is no list of generally supported keys, as each filter has different requirements. Filter sections are prefixed by filter_ and then the name of the filter. So [filter_Uglifyjs] defines the settings for the Uglifyjs filter.

Installation specific configuration files

Applications, and plugins support .local files. Whenever an ini file is processed, AssetCompress will also load a .local.ini version of that file. The .local files are useful when you are dealing with multiple platforms that may have system tools like nodejs installed in different locations. Local configuration files can re-define any configuration section or property. Sections and properties defined in a local file will overwrite those defined in the base configuration file.