Configuration - markstory/mini-asset GitHub Wiki

Mini-Asset 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:

[general]
; Define the absolute path that the build timestamp created
; during production builds and is required for timestamped assets to work.
; This option can be used to store the timestamp file in a non-temp directory
; which is useful when deploying an application as a packaged artifact.
; If undefined, this will default to `sys_get_temp_dir()`
timestampPath = path/for/timestampfile

; 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()

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.