---

Installing Minimee

1. Create a cache folder on your server, accessible by a URL, and ensure permissions allow for reading & writing.
2. Copy the minimee folder to your system/expressionengine/third_party folder
3. Follow Configuration steps below

---

Upgrading from 1.x

Despite Minimee2's significant changes, it has been built to ensure full backwards-compatibility with Minimee 1.x. So if you're a cow(boy|girl) and like to upgrade add-ons before reading upgrade notes, then we've got you covered. But to get the most out of Minimee's new abilities and performance, be sure to make it past Step 1.

Step 1: Update third_party/minimee folder

It's obvious, and it just works. Replace your old system/ee/third_party/minimee folder with the new, and you're in business.

Step 2a: Visit the Extensions CP

If you have Minimee's Extension installed, you will want to visit the Extensions page so that Minimee can upgrade its settings the new architecture.

Step 2b: Update Config.php

In lieu of Minimee's Extension, you may have Minimee configured via EE's config option, or via EE's Global Variables. If so, please note:

• EE's Global Variables are deprecated. Please switch to using EE's config instead.

Additionally, when configuring via EE's $config, setting keys have changed to be a single array. See the Configuration section below for more.

Step 3: Filename Case Sensitivity

Two files' names have changed case, which may go unrecognised with versioning systems such as SVN/Git, and may cause trouble on case-sensitive filesystems. While a check is in place to account for this, it is recommended that you double-check that the names have been properly maintained, as subsequent versions of Minimee may drop this check to save time. The files are:

// correct:
/system/expressionengine/third_party/minimee/libraries/JSMin.php
// incorrect:
/system/expressionengine/third_party/minimee/libraries/jsmin.php

// and

// correct:
/system/expressionengine/third_party/minimee/libraries/CSSmin.php
// incorrect:
/system/expressionengine/third_party/minimee/libraries/CSSMin.php

Step 4: Cache folder cleanup

Minimee 2.x's naming convention differs from 1.x, and therefore upon first run will create new cache files. If you'd like to tidy up your cache folder, now would be a good time. Also see Minimee's new cleanup= setting to automatically delete expired caches.

To get the most out of Minimee's performance offering, configure via EE's $config variable; use the Extension for simplicity and convenience, but at the cost of an extra database call.

Config via Extension

Each field of Minimee's Extension screen contains helpful hints and instructions. Screenshots of the page follow:

• 

  Basic Preferences

  The first panel allows for basic configuration of Minimee, including whether to combine and/or minify each asset type.

  If no values are supplied for Cache Path or Cache URL, Minimee will automatically look for a `cache` folder at your root.

  You may specify relative paths by ommitting a leading slash (e.g. `cache/path`).

• 

  Advanced Preferences

  For 90% of all setups, you will not need to edit the Advanced Preferences. If you do and encounter problems, these should be the first things you reset or change.

---

Config via EE's $config object

Configuring Minimee via EE's $config has the advantage of not requiring any DB calls to initialise or run, saving precious time on your page loads. Going this route requires editing your /system/expressionengine/config/config.php file; alternatively you are encouraged to adopt any of the community-developed "bootstrap" methods, such as:

• NSM Config Boostrap from EE-Garage
• EE Master Config from Focus Lab LLC
• This little-known gist from @airways

$config['minimee'] = array(

    /**
     * ==============================================
     * BASIC PREFERENCES (REQUIRED)
     * ==============================================
     */

    /**
     * The path to the cache folder.
     * Defaults to site's FCPATH + '/cache'
     */
    'cache_path'        => '/path/to/site.com/cache',

    /**
     * The URL to the cache folder.
     * Defaults to $EE->config->item('base_url') + '/cache'
     */
    'cache_url'         => 'http://site.com/cache',

    /**
     * ==============================================
     * BASIC PREFERENCES (OPTIONAL)
     * ==============================================
     */

    /**
     * Turn on or off combining of CSS assets only. 'yes' or 'no'.
     * Values: 'yes' or 'no'
     * Default: yes
     */
    'combine_css'       => 'yes',

    /**
     * Turn on or off combining of JS assets only. 'yes' or 'no'.
     * Values: 'yes' or 'no'
     * Default: yes
     */
    'combine_js'        => 'yes',

    /**
     * Turn on or off minifying of CSS assets. 'yes' or 'no'.
     * Values: 'yes' or 'no'
     * Default: yes
     */
    'minify_css'        => 'yes',

    /**
     * Turn on or off minifying of the template HTML.
     * Values: 'yes' or 'no'
     * Default: no
     */
    'minify_html'       => 'no',

    /**
     * Turn on or off minifying of JS assets.
     * Values: 'yes' or 'no'
     * Default: yes
     */
    'minify_js'         => 'yes',


    /**
     * ==============================================
     * DISABLING MINIMEE
     * ==============================================
     */

    /**
     * Disable Minimee entirely; aborts all activity
     * and returns all tags untouched.
     * Values: 'yes' or 'no'
     * Default: no
     */
    'disable'           => 'no',


    /**
     * ==============================================
     * ADVANCED PREFERENCES
     * It is recommended to not specify these unless
     * you are intending to override their default values.
     * ==============================================
     */

    /**
     * The base path of your local source assets.
     * Defaults to site's FCPATH
     */
    'base_path'         => '/path/to/site.com',

    /**
     * The base URL of your local source assets.
     * Defaults to $EE->config->item('base_url')
     */
    'base_url'          => 'http://site.com',

    /**
     * An optional unique 'cachebusting' string to force
     * Minimee to generate a new cache whenever updated.
     */
    'cachebust'         => '',

    /**
     * When 'yes', Minimee will attempt to delete caches
     * it has determined to have expired.
     * Values: 'yes' or 'no'
     * Default: no
     */
    'cleanup'       => 'no',

    /**
     * Specify which minification library to use for your CSS.
     * Values: 'minify' or 'cssmin'
     * Default: minify
     */
    'css_library'   => 'minify',

    /**
     * Whether or not to prepend the base URL to relative
     * @import and image paths in CSS. 'yes' or 'no'.
     * Values: 'yes' or 'no'
     * Default: yes
     */
    'css_prepend_mode'  => 'yes',

    /**
     * Override the URL used when prepending URL to relative
     * @import and image paths in CSS.
     * Defaults to Base URL.
     */
    'css_prepend_url'   => 'http://site.com',

    /**
     * Specify what algorithm to use when creating cache filenames.
     * 'sanitize' enforces a 200 character limit, and is
     * only recommended during development.
     * Values: 'md5', 'sha1', or 'sanitize'/'sanitise'
     * Default: sha1
     */
    'hash_method'   => 'sha1',

    /**
     * Specify which minification library to use for your JS.
     * Please note that JSMinPlus is VERY memory-intensive. Not recommended
     * unless you really know what you're doing. Seriously.
     *
     * Values: 'jsmin' or 'jsminplus'
     * Default: jsmin
     */
    'js_library'    => 'jsmin',

    /**
     * Specify the method with which Minimee should fetch external & {stylesheet=} assets.
     * Values: 'auto', 'fgc', or 'curl'
     * Default: auto
     */
    'remote_mode'       => 'auto'
);

Heads up! All Configuration values mentioned above can also be specified as tag parameters. Refer to the EE $config code sample for key/value combinations.

exp:minimee:css and exp:minimee:js

Parameter	Required?	Default	Values	Description
attribute:name="value"	no	none	String	By default Minimee uses the first tag it encounters as a template for the cache tag output (e.g. <link ... > or <script ... >). You may override this by specifying one or more tag attributes using this parameter format.
combine=	no	none	yes | no	Shorthand, runtime override of the combine_(css|js) config option
delimiter=	no	,	String	When not combining, this is the string to place between cache output
display=	no	tag	tag	Specify which format to display as the cache results; the default is "tag", returning the appropriate asset tag (e.g. <link ...> or <script...></script>).
			url	This option will only return the URL to the cache, e.g. http://site.com/cache/cachefile.name.ext. When specifying URL, be aware that if Minimee encounters an error, you may experience unexpected results.
			contents	Instruct Minimee to return the contents of the cache, for embedding inline in your template. By default, only the contents are returned; specify one or more attribute:name="type" values to instruct Minimee to wrap the contents in the appropriate HTML tag (e.g. <style>...</style> or <script>...</script>
minify=	no	none	yes | no	Shorthand, runtime override of the minify_(css|js) config option
priority=	no	0	Numeric	For use with queue feature. Value specified is a number; lower numbers are placed earlier in queue order.
queue=	no	none	String	To "queue" assets for output; receives a "key" value (e.g. "head_css"), which is used later to lookup and retrieve the queue'd cache Note: see the section below about Queue'ing incompatibility with EE's Advanced Conditionals.

---

exp:minimee:display

Parameter	Required?	Default	Values	Description
attribute:name="value"	no	none	String	By default Minimee uses the first tag it encounters as a template for the cache tag output (e.g. <link ... > or <script ... >). You may override this by specifying one or more tag attributes using this parameter format.
combine=	no	none	yes | no	Shorthand, runtime override of the combine_(css|js) config option
css= OR js=	yes	none	String	The "key" value of the queue, to fetch and return
delimiter=	no	,	String	When not combining, this is the string to place between cache output
display=	no	tag	tag	Specify which format to display as the cache results; the default is "tag", returning the appropriate asset tag (e.g. <link ...> or <script...></script>).
			url	This option will only return the URL to the cache, e.g. http://site.com/cache/cachefile.name.ext. When specifying URL, be aware that if Minimee encounters an error, you may experience unexpected results.
			contents	Instruct Minimee to return the contents of the cache, for embedding inline in your template. By default, only the contents are returned; specify one or more attribute:name="type" values to instruct Minimee to wrap the contents in the appropriate HTML tag (e.g. <style>...</style> or <script>...</script>
minify=	no	none	yes | no	Shorthand, runtime override of the minify_(css|js) config option

---

exp:minimee

Parameter	Required?	Default	Values	Description
attribute:name="value"	no	none	String	Override the tag output; useful if changing display="contents", since you will need to specify tag output to avoid contents being returned without a containing tag. See Advanced Usage section below.
combine=	no	none	yes | no	Shorthand, runtime override of the combine_(css|js) config option
css= OR js=	yes	none	String	filename(s) of assets to cache. Cannot specify both in same call.
delimiter=	no	,	String	When not combining, this is the string to place between cache output
display=	no	tag	tag	Specify which format to display as the cache results; the default is "tag", returning the appropriate asset tag (e.g. <link ...> or <script...></script>).
			url	This option will only return the URL to the cache, e.g. http://site.com/cache/cachefile.name.ext. When specifying URL, be aware that if Minimee encounters an error, you may experience unexpected results.
			contents	Instruct Minimee to return the contents of the cache, for embedding inline in your template. By default, only the contents are returned; specify one or more attribute:name="type" values to instruct Minimee to wrap the contents in the appropriate HTML tag (e.g. <style>...</style> or <script>...</script>
minify=	no	none	yes | no	Shorthand, runtime override of the minify_(css|js) config option
priority=	no	0	Numeric	For use with queue feature. Value specified is a number; lower numbers are placed earlier in queue order.
queue=	no	none	String	To "queue" assets for output; receives a "key" value (e.g. "head_css"), which is used later to lookup and retrieve the queue'd cache Note: see the section below about Queue'ing incompatibility with EE's Advanced Conditionals.

---

exp:minimee:html

Description
This tag is required only when all are true: You have configured Minimee via EE's $config object Minimee's extension is disabled You are not using any of Minimee's other tags for CSS or JS processing When the above are all true, then Minimee needs to be called once during template parsing to know to minify your HTML. Placing this tag somewhere in your template will do just that.

Basic Usage

Once configured, basic use of Minimee is as simple and beautiful as:

CSS:

{exp:minimee:css}
    <link rel="stylesheet" href="css/reset.css">
    <link rel="stylesheet" href="{stylesheet='css/webfonts'}">
    <link rel="stylesheet" href="http://site.com/css/global.css">
    <link rel="stylesheet" href="css/forms.css">
{/exp:minimee:css}

{!-- will render something like: --}
<link rel="stylesheet" href="http://site.com/cache/b488f65d0085dcc6b8f536f533b5f2da.1345797433.css">

JS:

{exp:minimee:js}
    <script type="text/javascript" src="/js/mylibs/jquery.easing.js"></script>
    <script type="text/javascript" src="/js/mylibs/jquery.cycle.js"></script>
    <script type="text/javascript" src="/js/mylibs/jquery.forms.js"></script>
    <script type="text/javascript" src="/js/scripts.js"></script>
    <script type="text/javascript" src="/js/plugins.js"></script>
{/exp:minimee:js}

{!- will render something like: --}
<script type="text/javascript" src="http://site.com/cache/16b6345ae6f4b24dd2b1cba102cbf2fa.1298784512.js"></script>

---

Advanced Usage

There is a wealth of power and flexibility at your fingertips should you choose to go beyond Minimee's basic setup. This section will continue to grow with more examples as time goes on.

---

Queueing + Display

Since Minimee 1.x there has been the ability to "queue" assets and then display the final cache later in your EE template. It's a simple two-step process:

Step 1: Add queue= parameter to your exp:minimee:css or exp:minimee:js opening tag:

{exp:minimee:css queue="head_css"}
    <link rel="stylesheet" href="css/reset.css">
{/exp:minimee:css}

For subsequent queue'ing, continue to use the same parameter value:

{exp:minimee:css queue="head_css"}
    <link rel="stylesheet" href="{stylesheet='css/webfonts'}">
{/exp:minimee:css}
    ...

{exp:minimee:css queue="head_css"}
    <link rel="stylesheet" href="http://site.com/css/global.css">
    <link rel="stylesheet" href="css/forms.css">
{/exp:minimee:css}

Step 2: Once all assets have been queue'd, you can finally display your tag output with the exp:minimee:display tag; use css= or js= as your tag parameter depending on the type of asset, and specify the name of the queue:

{exp:minimee:display css="head_css"}

{!-- will render something like: --}
<link rel="stylesheet" href="http://site.com/cache/b488f65d0085dcc6b8f536f533b5f2da.1345797433.css">

Note that Queue'ing is incompatible with EE's Advanced Conditionals

If you are attempting to conditionally queue an asset, be warned that Queue'ing is incompatible with EE's Advanced Conditionals. This is due to the EE's parse order, where the evaluation of any Advanced Conditionals happens after the Minimee queue tags have already been parsed and processed.

You have a few options to work around this parse order conflict:

• Refactor your template to use Simple Conditionals instead.
• Use the Switchee or IfElse plugins from Mark Croxton

---

The 'Croxton Queue' for EE2.4+

Mark Croxton submitted this feature request to delay the processing of exp:minimee:display until all other template parsing has been completed, by way of leveraging EE2.4's new template_post_parse hook. It was a brilliant idea and indication of his mad scientist skills. In his wise words:

"Then you would never need worry about parse order when injecting assets into the header or footer of your page using queues."

This, combined with the new priority="" parameter, means you can do something like:

{exp:minimee:display css="header_css"}

{!-- sometime LATER in EE's parse order --}

{exp:minimee:css queue="header_css" priority="10"}
    <link href="css/forms.css" rel="stylesheet" type="text/css" />
{/exp:minimee:css}

{!-- and even later in parse order, also note the priority --}

{exp:minimee:css queue="header_css" priority="0"}
    <link href="css/reset.css" rel="stylesheet" type="text/css" />
{/exp:minimee:css}

And then what ends up happening is that exp:minimee:display outputs a cached css that contains, in this order:

1. css/reset.css (first because of priority="0")
2. css/forms.css (second because of priority="10")

---

Embedding Cache Contents Inline

There are now multiple approaches to "embedding" the contents of your cache inline with the rest of your HTML content. Let's cover 2 basic options:

Option 1: Using a Queue + Display method

Begin with Step 1 above under Queueing + Display. This will queue one or more assets for display.

As a Step 2, specify a display output of contents. Just as with Minimee 1.x, be sure to wrap it within the appropriate HTML tag:

<style type="text/css">
    {exp:minimee:display css="head_css" display="contents"}
</style>

However, by also specifying one or more attribute:name="value" parameters to exp:minimee:display, Minimee will automatically wrap the contents of the cache in the appropriate HTML tag for you, using the attributes you specified:

{exp:minimee:display css="head_css" display="contents" attribute:type="text/css"}

{!-- Will output something like: --}
<style type="text/css">
    /* your CSS here */
</style>

Option 2: Directly changing display mode

The return mode of exp:minimee:js and exp:minimee:css tags can now be altered in a single call, by specifying the display value at the same time. When doing so, it is recommended to also provide the appropriate attribute:name="value" parameters as well, so that the contents are automatically wrapped in tags:

{exp:minimee:css display="contents" attribute:type="text/css"}
    <link rel="stylesheet" href="css/reset.css">
    <link rel="stylesheet" href="{stylesheet='css/webfonts'}">
    <link rel="stylesheet" href="http://site.com/css/global.css">
    <link rel="stylesheet" href="css/forms.css">
{/exp:minimee:css}

{!-- Will output something like: --}
<style type="text/css">
    /* your CSS here */
</style>

---

Integration with LABjs

If using the LABjs script loading library, you can use the exp:minimee API tag to seamlessly integrate with your application:

<script>
    $LAB
    .script("{exp:minimee js='framework.js'}").wait()
    .script("{exp:minimee js='plugin.framework.js'}")
    .script("{exp:minimee js='myplugin.framework.js'}").wait()
    .script("{exp:minimee js='init.js'}").wait();
</script>

What's more, you can still combine & cache JS assets using a similar syntax. When doing so, consider setting it up so that should Minimee encounter an error - or be disabled manually - the resulting output can still work with LABjs.

Consider the follwing example from LABjs:

<script>
    $LAB
    .script("script1.js", "script2.js", "script3.js")
    .wait(function(){
         // wait for all scripts to execute first
    });
</script>

By modifying the delimiter which Minimee uses to parse assets, we can do the following:

<script>
    $LAB
    .script("{exp:minimee js='script1.js", "script2.js", "script3.js' delimiter='", "'}")
    .wait(function(){
        // wait for all scripts to execute first
    });
</script>

If all goes well, $LAB.script() will receive a single cache file; if not - or if Minimee has been temporarily disabled - it receives the original example's equivalent.

Version 2.1.13 5 September 2014

• Avoid PHP notice because Minimee::usage() was not defined as static (thanks @johanneslamers)

Version 2.1.12 6 July 2014

• New: added 'gzip' setting to create a gzip copy of cache (use with this .htaccess recipe) (hat tip robsonsobral)
• Improvement: Add icon to improve appearance with some EE Debug Toolbar themes
• Bugfix: Compare filesize reduction against contents when returned from pre- hooks (hat tip wiseloren)

Version 2.1.11 30 June 2014

• Improvement: Conditionally append semicolon to end of JS files, which should aid in concatenation of certain 3rd party scripts.

Version 2.1.10 10 February 2014

• Improvement: use version_compare()
• Improvement: remove reliance on updating PHP's include_path
• Bug fix: a remote, relative protocol url might sanitise into a cache filename with a leading period.
• Bug fix: reset properties to defaults after calling display() each time.
• Upgrade Minify 2.1.7, fixing a severe vulnerability.

Version 2.1.9 2 July 2013

• Improvement: Log bytes saved per file; track and log total bytes saved per run.
• Improvement: Translate all logging messages coming from classes/Minimee_config.php.
• Improvement: Update EpiCurl via https://github.com/jmathai/twitter-async.
• Bugfix: Add Minimee_lib::reset() to ensure on multiple runs we are not mixing with stale data.

Version 2.1.8 22 March 2013

• Add compatibility with EE Debug Toolbar

Version 2.1.7 23 January 2013

• Re-apply fix from 2.1.4, which was inadvertently lost in 2.1.5. :(

Version 2.1.6 17 January 2013

• Fix edge case where 3rd party pre-processed contents were not being written in cache.

Version 2.1.5 8 January 2013

• Refactor changes in 2.1.4 to streamline logic and avoid edge case PHP notice.

Version 2.1.4 2 January 2013

• Fix edge case where CSS URL is not being re-written.

Version 2.1.3 13 November 2012

• This time I mean it: Hide Advanced Settings panel only if a value exists that is different from a factory setup.

Version 2.1.2 13 November 2012

• Check if minification actually reduced file size; if not, keep original contents.
• Hide Advanced Settings panel only if a value exists that is different from a factory setup.

Version 2.1.1 11 October 2012

• NEW: hash_method with ability to sanitize, rather than hash, cache filenames. Useful for debugging, not recommended during development.
• Case-sensitivity precaution for CSSmin.php filename

Version 2.1.0 9 October 2012

• ALL settings can be specified via config or extension, as well as via tag parameters
• Ability to turn on and off minification and/or combining per asset type
• Better, more verbose debugging with EE's Template Debugging
• New API available for 3rd party add-ons
• Path & URL settings can now be relative to site
• Out-of-the-box default configuration means near zero setup
• New shorthand exp:minimee tag allows for quick caching, plus access to a powerful API "interface"
• New ways to display your cache: in a tag, embedded inline, or just the URL
• Purpose-built compatibility with RequireJS, LABjs, etc
• Disable or override the URLs which are prepended to image & @import paths in CSS
• New priority="" parameter allows you to queue assets into a specific order
• For EE2.4 and above, assets are queue'd and sorted after all templates have been parsed (see the "Croxton Queue" below)
• New cleanup="" setting for automatically deleting expired caches
• Verbose template debugging messages to help easily track down errors
• Hooks for 3rd party integration (see MSMinimee)
• Plus bug fixes, more fine-grained control, and other improvements!

Version 1.1.7 April 16, 2012

• Skip HTML minification of template type is not webpage or static.

Version 1.1.6 February 03, 2012

• Play nice with other hooks (sloppy)

Version 1.1.5 January 30, 2012

• HTML Minification (requires EE2.4)
• Bug Fix: upgrade scripts may have been skipped in certain edge cases

Version 1.1.3 June 23, 2011

• New: embed cached contents inline to your template
• Improved: Alter how error & debug logging is performed
• Improved: Unset variables along way to keep memory usage down

Version 1.1.2 February 22, 2011

• Add new Base Path and Base URL advanced settings
• Split settings form into basic/advanced

Version 1.1.1 January 19, 2011

• Fix nasty bug that was erasing URLs from CSS files

Version 1.1.0 January 03, 2011

• Big rewrite to embrace PHP5!
• Support cURL and file_get_contents()
• rely on processed markup as template for output (see http://bit.ly/dngqjK)
• parse for global variables if necessary
• change boolean config/param values to 'yes' or 'no'
• remove STRICT option - all files must exist for Minimee to work
• add new DEBUG option to output error messages as HTML comments

Version 1.0.2 October 15, 2010

• Support of {stylesheet} super global (thanks @winterstetter)
• Enable settings via config.php (thanks @wesbaker)
• Improved stability of strict mode & queue function
• Improved debug & error messaging
• Avoids DB query if configured via globals or config

Version 1.0.1 October 11, 2010

• Check for OpenSSL support
• Improved logging messages
• Fixed bug in "strict" mode
• Support for NSM Addon Updater
• Thanks to @gohearsay and @simoncox for help testing

Version 1.0.0 October 09, 2010

• Initial release