A Craft CMS port of the popular Minimee add-on for ExpressionEngine.
Minimize, combine & cache your CSS and JS files. Because size (still) DOES matter.
- Config settings will parse Environment Variables
- Use as a Twig Filter or Craft Variable
- Can save caches either above or below webroot
- Enable/disable minification of CSS & JS
- Enable/disable combination of CSS & JS
- When in
devMode
, Minimee will throwException
s if unable to run successfully - When in
devMode
, will automatically attempt to clean up what it can determine are expired caches - Override CP Settings via filesystem config (requires Craft 1.4), or at runtime
- Clear Minimee's cache from CP (Settings > Tools > Clear Caches)
- Ability to return contents of the cache to template
Looking to minify your HTML, or minify inline CSS/JS? You should check out https://github.com/khalwat/minify.
- Download latest release from github
- Copy
minimee
into yourapp/plugins
directory - Log into Craft and go to
Settings > Plugins
- Click
install
for Minimee - Visit Minimee plugin settings and optionally configure (see below)
Out of the box and when first installed, Minimee will be automatically enabled and set to combine & minify both your CSS and JS assets. It will use default settings to get you up and running immediately, but you can visit the Settings
page of the plugin to configure to suit your environment.
Note that all string settings will parse Craft's Environment Variables
To locate your assets on your web server, Minimee takes the path to the asset (e.g. /asset/css/normalize.css
), and appends this to $_SERVER['DOCUMENT_ROOT']
. This tends to work for most setups, and can be left as is.
However for a multi-lingual site, where you may have many index.php
files (and therefore differing values of $_SERVER['DOCUMENT_ROOT']
), but one location of CSS and JS assets, you will want to specify that singlular path location. This is when using Craft's Environment Variables might particularly come in handy.
When operating upon your CSS, Minimee needs to rewrite the paths to images & fonts, so that the cached file can still successfully link to those images & fonts, no matter where it may be saved. By default, the URL of your site is used, as defined in Settings > General.
Similar to the Filesystem Path
, this may need to be overriden in certain circumstances. In fact it's probably safe to say that if you need to override the Filesystem Path, you will want to also override the Base URL accordingly.
By default, Minimee stores cached assets in Craft's craft/storage
folder, which likely sits above webroot. The cache is then delivered by Craft itself, via a special "resource" url, e.g. http://domain.com/resources/minimee/filename.timestamp.ext
.
Alternatively, you can specify a cache path & URL which sits below webroot, so that the cached assets are delivered directly by your server. This is the recommended setup for optimal performance gains.
By default, Minimee returns the URL to the combined & minified asset. Also by default, if that asset is a CSS file, it is wrapped in a default template (<link rel="stylesheet" href="%s">
), where the URL replaces "%s%
using PHP's sprintf() function. If that asset is a JS file, the default template is <script src="%s"></script>
.
You may override this behaviour to do things such as load Javascript asynchronously, or embed CSS inline. These settings are especially useful being used at runtime (see below).
When Minimee processes CSS files, it will by default alter any relative @import and image URIs (e.g. url("../img/arrow.svg")
) to be a fully-qualified URL, using the asset's URL as the basis. This ensures that the links will remain intact regardless of where your might save the cached files.
You can opt to turn this feature off; additionally you can override the prepended URL to something custom. This is particularly useful if you would like to upload your static assets to a CDN, or link to assets through a cookie-less domain.
In addition to specifying configuration settings via the CP, you can also pass an array of settings when calling any of Minimee's tags below. For example, you can create this simple Twig hash, and then pass it as a parameter to either of Minimee's template tags:
{#
Tip: In your template you can access Craft's environment Variables like so:
craft.config.environmentVariables['variableName']
#}
{% set minimeeSettings = {
'enabled' : true,
'combineCssEnabled' : true,
'combineJsEnabled' : true,
'minifyCssEnabled' : true,
'minifyJsEnabled' : true,
'filesystemPath' : '/var/www/public/',
'baseUrl' : 'http://craft.dev/',
'cachePath' : '/var/www/public/cache/',
'cacheUrl' : 'http://craft.dev/cache/',
'cssReturnTemplate' : '<link rel="stylesheet" href="%s">',
'jsReturnTemplate' : '<script src="%s"></script>',
'returnType' : 'url',
'cssPrependUrlEnabled' : true,
'cssPrependUrl' : ''
} %}
As of Craft 2.0, Minimee supports the ability to override the CP Settings with filesystem configs. Note that this does NOT reduce any processing/DB overheads, but it may suit how you prefer to configure Minimee across multiple environments.
To use this feature, begin by copying the contents of the minimee/config.php
file into a new file named minimee.php
, and move it to your craft/config
folder. Then uncomment and set as few or as many settings as you wish.
For more on how multi-environment configs work in Craft, see https://craftcms.com/docs/multi-environment-configs.
Given all of the ways to configure Minimee, keep in mind the cascade or inheritance of these methods:
- CP settings are defaults
- Filesystem settings override CP settings
- Runtime settings override Filesystem settings
When overriding via any method, you only need to specify those setting values which need to be different.
When your site is running in devMode, Minimee will throw an Exception
containing any messages which indicate where an error may have occurred.
Also while in devMode, Minimee will continually try to clean your cache folder of what it can safely determine are expired caches.
There are currently two ways you can use Minimee:
-
Template Variable
-
Twig Filter
Both methods can be passed an optional parameter of runtime settings. Refer to the section above on how to define these.
Minimee's template variable is attached to Craft's global variable {{ craft }}
, and accessed via {{ craft.minimee.css() }}
and {{ craft.minimee.js() }}
. An array of asset paths is passed to each variable, with a second optional parameter containing an array of settings.
{{ craft.minimee.css([
'/assets/css/normalize.css',
'/assets/css/app.css'
])
}}
{# Optionally pass settings as 2nd parameter #}
{{ craft.minimee.css([
'/assets/css/normalize.css',
'/assets/css/app.css'
], minimeeSettings)
}}
{{ craft.minimee.js([
'/assets/js/jquery.js',
'/assets/js/app.js'
])
}}
{# Optionally pass settings as 2nd parameter #}
{{ craft.minimee.js([
'/assets/js/jquery.js',
'/assets/js/app.js'
], minimeeSettings)
}}
Minimee can also be used as a filter, providing the ability to parse and process complete HTML tags, similar to how Minimee operates as an EE plugin.
Minimee can detect which type of asset to process; you may optionally pass an array of settings to any filter.
{% filter minimee %}
<link href="/assets/css/normalize.css'" />
<link href="/assets/css/app.css'" />
{% endfilter %}
{# Optionally pass settings as parameter #}
{% filter minimee(minimeeSettings) %}
<link href="/assets/css/normalize.css'" />
<link href="/assets/css/app.css'" />
{% endfilter %}
{% filter minimee %}
<script src="/assets/js/jquery.js"></script>
<script src="/assets/js/app.js"></script>
{% endfilter %}
{# Optionally pass settings as parameter #}
{% filter minimee(minimeeSettings) %}
<script src="/assets/js/jquery.js"></script>
<script src="/assets/js/app.js"></script>
{% endfilter %}
The filter
will also work in conjunction with Craft's getFootHtml and getHeadHtml tags.
{% includeCssFile "/assets/css/normalize.css" %}
{% includeCssFile "/assets/css/app.css" %}
{{ getHeadHtml() | minimee }}
{% includeJsFile "/assets/js/jquery.js" %}
{% includeJsFile "/assets/js/app.js" %}
{{ getFootHtml() | minimee }}
{# Optionally pass settings as parameter #}
{% set minimeeSettings = {
'enabled' : craft.config.environmentVariables['minimeeEnabled']
} %}
{{ getHeadHtml() | minimee(minimeeSettings) }}
{{ getFootHtml() | minimee(minimeeSettings) }}
Note that any inline CSS or JS passed via
{% includeJs %}
,{% includeCss %}
and{% includeHiResCss %}
is currently not supported.
- improve/refactor internal abort()
- all messages/instructions translatable
- improved logging
- validation during settings save
- ensure using best practice for method names
- setX, getX
- isX
- doX
- useX
- protected has leading underscore?
- unit test
- create
*.gz
versions of cache, for serving precommpressed files automatically via Apache or nginx. - publish "map" js files during development
- tie the cache hash to settings and/or last date modified of settings/config and/or minimee version?
- support includeJs, includeCss and includeHiResCss?
- additional hooks/events
- try to resolve URL assets to local assets
Unit Testing of this plugin is in active, sporatic, trial-and-error development. If you see anything that can improve this process, I'd welcome your thoughts. I'm fairly confident I have no idea what I'm doing, as with most things.
To run Minimee, the following assumptions are made:
- you have PHP 5.3+ available to run from CLI
- optionally xdebug is configured for PHP if you'd like run PHPUnit's coverage reports.
- composer is installed globally (if installed locally, the commands below may have to be adjusted)
- you have a local copy of Craft running
With the assumptions taken care of, these steps should get you up and running:
- Fork, clone or download the
develop
branch of Minimee - Symlink the
minimee
folder to Craft'splugin
folder - Update line 7 of
minimee/tests/bootstrap.php
to point to your copy of Craft's boostrap.php file (e.g./path/to/your/craft/app/tests/bootstrap.php
) - In Terminal,
cd
tominimee/tests
- Run
composer install --dev
- Run
php vendor/bin/phpunit
Note that for testing, it's not necessary to have Minimee installed.
Within MAMP Pro I have downloaded a number of PHP versions to be able to test across; I have modified the php.ini
file of version 5.5.9 to turn on xdebug, so when wanting to run coverage reports, use this complete command: /Applications/MAMP/bin/php/php5.5.9/bin/php vendor/bin/phpunit
[http://opensource.org/licenses/mit-license.php](MIT License)