Minimee² is out!

New documentation can be found here: http://johndwells.github.com/Minimee

Over the coming days this site will be updated to reflect the wealth of changes brought in Version 2. For the time being, the User Guide found here pertains to Version 1.x only.

Thanks for your patience during the transition. If you have any troubles, as always please post to the devot-ee forums, or find me on twitter.

The following User Guide is for Minimee 1.x only
Please see here for Version 2.x documentation: http://johndwells.github.com/Minimee

Inspiration/License

Minimee is inspired and influenced by SL Combinator from Experience Internet, and Carabiner Asset Management Library from Tony Dewan. It is released under a BSD License.

Requirements

• PHP5
• ExpressionEngine 2.1 or later
• For HTML Minification, EE2.4 or later is required

Optional Requirements:

• If using {stylesheet=} or external URLs, either cURL or file_get_contents() is required
• If using file_get_contents(), PHP must be compiled with support for fopen wrappers (allow_url_fopen must be set to true in PHP.ini)
• If using file_get_contents() and combining/minifying files over https, PHP must be compiled with OpenSSL support

Installation

1. copy the minimee folder to your third_party folder
2. create a cache folder on your server, accessible by a URL, and ensure permissions allow for reading & writing
3. optionally you may install the Minimee extension if you wish to save your settings in the database
4. follow “Configuration” steps below to finish installation

Updating

If updating from 1.0.2 or below, you are encouraged to update your configuration and tag parameter values from boolean (TRUE/FALSE and ‘true’/‘false’) to ‘yes’/‘no’ or ‘y’/‘n’.

If you are using the included extension for configuring Minimee, simply visit the Settings screen, double-check the form values and click “Save Settings”.

Configuration

To begin using Minimee, you must configure at least:

1. where the cache folder resides on your server
2. the URL to the cache folder

Basic Preferences

Once you have installed the Minimee extension (step 3 Installation), click on the settings link. Set values as follows:

Cache Path

e.g. /path/to/your/cache/folder

Cache URL:

e.g. http://yourwebsite.com/cache/folder

Advanced Preferences

If you click the 'Advanced Preferences' link you will see other options available to Minimee:

Disable plugin entirely?

If set to ‘Yes’, Minimee will be disabled across the site.

Turn on template debugging?

If you are having difficulty installing and using Minimee, turning this option on will output any error debugging messages directly into your HTML as comments. View source to see what messages appear.

Remote file mode?

‘Auto’ will try to use cURL first, file_get_contents() second; or you can specify the mode yourself.

Base Path

By default, Minimee looks for local assets relative to the root of your EE installation (set as "FCPATH", or "Front Controller Path", within EE). If for some reason your assets are not always relative to your Front Controller, you may specify your own base path here.

Base URL

When Minimee compresses and combines your CSS, it re-writes any relative path links to background images into absolute links. By default, your Site URL is used (e.g. http://mysite.com). However there are instances where you may need to specify a different base URL - use this setting for those times.

Alternative Configuration Methods

As an alternative to using the included Extension, you do have the option of configuring Minimee via two other methods: by setting global variables in your index.php file, or by adding to EE’s config object.

PLEASE NOTE: Do not mix configuration methods, or Minimee might not behave as expected.

Alternative 1: via global vars:

Pop open your index.php file and find the “CUSTOM CONFIG VALUES” section. Read the instructions if you are unfamiliar with this approach, and then add the following:

// basic preferences
$assign_to_config['global_vars']['minimee_cache_path']	= '/path/to/your/cache';
$assign_to_config['global_vars']['minimee_cache_url']	= 'http://website.com/cache';
// advanced preferences
$assign_to_config['global_vars']['minimee_base_path'] = '';
$assign_to_config['global_vars']['minimee_base_url'] = '';
$assign_to_config['global_vars']['minimee_debug'] = 'n'; // 'n' or 'y'
$assign_to_config['global_vars']['minimee_disable'] = 'n'; // 'n' or 'y'
$assign_to_config['global_vars']['minimee_remote_mode'] = 'auto'; // 'auto', 'curl' or 'fgc'

Alternative 2: via EE’s config object

Minimee also supports adding settings directly to EE’s config object. Take a look at Leevi Graham’s NSM Config Bootstrap for a handy way to get started down this route (NSM Config Bootstrap could also be used as a part of Option 2 above).

Similar to the global vars method, your config key/vars will be:

// basic preferences
$config['minimee_cache_path'] = '/path/to/your/cache';
$config['minimee_cache_url'] = 'http://website.com/cache';
// advanced prefernces
$config['minimee_base_path'] = '';
$config['minimee_base_url'] = '';
$config['minimee_debug'] = 'n'; // 'n' or 'y'
$config['minimee_disable'] = 'n'; // 'n' or 'y'
$config['minimee_remote_mode'] = 'auto'; // 'auto', 'curl' or 'fgc'

Basic Usage

Simply wrap your normal <link> or <script> HTML tags with Minimee’s tag pair,
and it will do it’s magic.

Note: Minimee uses the first tag it encounters as a template for output.

CSS:

{exp:minimee:css}
	<link type="text/css" rel="stylesheet" media="screen" href="http://yui.yahooapis.com/2.8.1/build/reset/reset-min.css" />
	<link type="text/css" rel="stylesheet" media="screen" href="{stylesheet=css/screen}" />
	<link type="text/css" rel="stylesheet" media="screen" href="/grid.css" />
{/exp:minimee:css}

JS:

{exp:minimee:js}
	<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
	<script src="/jquery.easing.1.3.js"></script>
{/exp:minimee:js}

Parameters

disable=“n” – set to “y” if you wish to temporarily disable this usage of plugin

minify=“y” – tells the plugin whether to minify files when caching; if set to ‘n’, it will not run files through minify engine

combine=“y” – tells plugin whether to combine files when caching; if set to ‘n’, it will cache each file separately

queue=“name” – Allows you to create a queue of assets to be output at a later stage in code. – The string passed to the queue parameter can later be used in the exp:minimee:display single tags.

Note: if minify & combine are both set to false, it performs no caching, effectively disabling plugin

Advanced Usage – Queueing

The “queue” function allows you to collect a list of files to be compressed, minified and cached at a later point in the template parsing. This feature relies on a clear understanding of EE’s parsing order. In particular, keep this in mind:

*EE’s parsing engine processes sub-templates (e.g. embeds) LAST, each in turn. Read more of EE’s parsing order at: http://expressionengine.com/wiki/Parse_Order/*

The “queue” function therefore is really only useful when your setup involves the following:

1. one or more embeds, as well as the original template file, includes queue calls to minimee
2. the exp:minimee:display tag is called within an EMBED that follows AFTER all other embeds that might add to the queue

Practically speaking, this feature was built specifically with JS in mind – we know it’s best practice to include JS at the end of our source, but with normal embedding this is sometimes not as simple to achieve.

So for example, you might have a header embed that queues a few JS & CSS files:

{exp:minimee:js queue="main"}
	<script src="/jquery.1.4.2.js"></script>
	<script src="/jquery.easing.1.3.js"></script>
{/exp:minimee:js}
{exp:minimee:css queue="screen"}
	<link type="text/css" rel="stylesheet" media="screen" href="/screen.css" />
{/exp:minimee:css}

Later on in another embed, you may need to call up other files:

{exp:minimee:js queue="main"}
	<script src="/jquery.cycle.js"></script>
{/exp:minimee:js}
{exp:minimee:css queue="screen"}
	<link type="text/css" rel="stylesheet" media="screen" href="/uniform.css" />
{/exp:minimee:css}

Then you have a footer embed that finally outputs your files. You can either combine the output, or call one queue at a time:

{exp:minimee:display js="main" css="screen"}

- or –

{exp:minimee:display js="main"}
{exp:minimee:display css="screen"}

Advanced Usage - Embedding Inline

New to version 1.1.3, Minimee can now return the contents of your combined & minified files, directly back to your template. Usage is similar to the queuing method outline above. This feature is split into two steps (queue + embed) so that you maintain full control over your tag output. Details are as follows:

Step 1: Queue your files for output

First you need to tell Minimee to queue your files. As an example, we will queue 3 JS files for later:

{exp:minimee:js queue="embedjs"}
	<script src="/jquery.js"></script>
	<script src="/jquery.cycle.js"></script>
	<script src="/startup.js"></script>
{/exp:minimee:js}

Then later in our template (or within a subsequent embedded template), we will retrieve this queued content, but embed it inline.  To do so, we need to remember to wrap our returned content with <script> tags:

<script type="text/javascript">
    {exp:minimee:embed js="embedjs"}
</script>

Note that we call our queue based on the name we provided earlier, "embedjs".  For clarity, let's look at this approach with CSS:

//Step 1: Queue your files for output
{exp:minimee:css queue="my_embedded_css"}
    <link type="text/css" rel="stylesheet" media="screen" href="/reset.css" />
    <link type="text/css" rel="stylesheet" media="screen" href="/screen.css" />
{/exp:minimee:css}

// Step 2: Embed your queued content, wrapped in appropriate HTML tag
<style type="text/css">
    {exp:minimee:embed css="my_embedded_css"}
</style> 

A Warning regarding external URLs

If you specify fully-qualified URLs (e.g. http://yourdomain.com/css/screen.css), Minimee will not check for updates. This is because the check would be far too expensive and time consuming.  Therefore if you are passing local CSS and JS files to Minimee, you're recommended to use absolute paths like so:

{exp:minimee:css}
	<link type="text/css" rel="stylesheet" href="/css/screen.css" /> 
{/exp:minimee:css}

Alternative Add-Ons

There are currently two alternative add-ons that help you compress your CSS & JS (for EE2).  These are:

AutoMin - By Jesse Bunch, this has been recently re-written shares many similarities with Minimee.  Syntax is nearly identical, however AutoMin will only work for local css & js files; no support for {stylesheet=}, and no support for external files. Configuration requires updating the plugin code itself.

NSM Minify - By Leevi Graham, this too only works on local files, but actually runs very different from Minimee & AutoMin. The setup is more similar to SL Combinator, and in fact it's possible to use without any EE tags whatsoever. So if you're after the ultimate in lightweight compression of your assets, NSM Minify might suit your tastes.

→ Official support forum over on devot-ee.

Seeing that Minimee a freebie, the bundled “SLA” is essentially that of good faith – I’ll try to help when I can. Hopefully some of what follows will help you if you get in a bind…

Can Minimee gzip its CSS and JS files?

No, and that's by design. If you're interested in gzip, I'd recommend setting some .htaccess directives (if running on Apache).  Google is your friend here.

Does Minimee work with EE’s {stylesheet} global variable?

Yes! Version 1.0.2 introduced support of the {stylesheet} global variable. It will look for a modification date in the DB, as well as if the template is saved as a file. It is therefore now recommended to not use the css trigger url method, since that method does not give Minimee a chance to check timestamps.

Does Minimee parse global variables?

Yes! As of version 1.1.0, Minimee also detects the presence of global variables and, if found, runs the template data through EE's global variable parsing routine.

Does Minimee clean up old cache files?

Nope, that’s up to you. Any time Minimee detects a file modification, a new cached file is generated and it moves swiftly on. So while you’re building your site, expect your cache folder to fill up fast.

I’ve changed a parameter passed to Minimee (e.g. minify=‘n’), but the cache doesn’t change. What’s up?

Minimee creates a cache file based on the timestamp of the most recently updated file, and an md5() string of all files being processed – it does not incorporate any parameters passed to Minimee. So you will need to manually delete the cache file to generate a new one based on your new parameter settings.

Version 2.1.12 (download), released July 06, 2014

• New: added 'gzip' setting to create a gzip copy of cache
• Improvement: Add icon to improve appearance with some EE Debug Toolbar themes
• Bugfix: Compare filesize reduction against contents when returned from pre- hooks

Version 2.1.11 (download), released June 30, 2014

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

Version 2.1.10 (download), released February 10, 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 (download), released July 02, 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.7 (download), released January 23, 2013

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

Version 2.1.6 (download), released January 17, 2013

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

Version 2.1.3 (download), released November 13, 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 (download), released November 13, 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 (download), released October 11, 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 (download), released October 09, 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
• 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=
• For EE2.4 and above, assets are queue'd and sorted after all templates have been parsed (the "Croxton Queue")
• New cleanup=
• Verbose template debugging messages to help easily track down errors
• Hooks for 3rd party integration (see Minimee+LESS, MSMinimee)
• Plus bug fixes, more fine-grained control, and other improvements!

Version 1.1.7 (download), released April 16, 2012

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

Version 1.1.6 (download), released February 03, 2012

• Play nice with other hooks (sloppy)

Version 1.1.5 (download), released January 30, 2012

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

Version 1.1.3 (download), released 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 (download), released February 22, 2011

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

Version 1.1.1 (download), released January 19, 2011

• Fix nasty bug that was erasing URLs from CSS files

Version 1.1.0 (download), released 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 (download), released 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 (download), released 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 (download), released October 09, 2010

• Initial release