Skip to content
Mark Story edited this page Sep 29, 2023 · 25 revisions

Asset Compress is a plugin for CakePHP that can help you reduce the number of HTTP requests your application makes, as well as provide some nice sugar for JavaScript and CSS files. It's partly intended as a way to get a 'build' stage without actually making the effort to write build scripts. By using directives you can resolve dependencies in JavaScript and inline @import statements in CSS files.

Installation

Install the plugin with composer:

$ composer require markstory/asset_compress

Next, enable the plugin in your application's bootstrap:

// in src/Application.php
// in the bootstrap() method add
$this->addPlugin('AssetCompress');

Version Compatibility

AssetCompress CakePHP
5.x. 5.x.
4.x. 4.x.
3.x 3.x.

Getting started

AssetCompress borrows ideas from other asset packagers like Jammit, and webassets and brings them to CakePHP. AssetCompress offers an easy to use well integrated solution for optimizing assets in your CakePHP applications. AssetCompress uses a simple ini file to define the packages your application will use, and helper to integrate those packages into your views + layouts. A controller is provided to dynamically generate build files for easy development. A shell is provided to easily generate static files for deployment, so you get the fastest site possible.

Defining an ini file

Before you can use AssetCompress you'll need an ini file. This file defines how the plugin should behave, what filters you want to use, and what asset packages your application uses. The ini file should be put in config/asset_compress.ini. For now we'll start off simple and include the minimal amount needed to get started.

[General]
cacheConfig = false

[js]
cachePath = WEBROOT/cache_js/

[css]
cachePath = WEBROOT/cache_css/

This skeleton defines paths where static files will be saved when the shell is used to generate assets.

Creating your first build file

With the general settings taken care of you can start defining the asset packages or build files your application uses. Each file is added as a section to the ini file. We'll start off by adding a build file for jQuery and all the plugins we have for it:

[jquery-combined.js]
files[] = jquery.js
files[] = jquery.ui-core.js

The section name is used as the build file name. These need to be unique across your application. Each files[] line defines a file to include in the build file. Files are concatenated together in the order they are defined. Once you've added all the files for a build you can link the build file in your layout. But first, you'll need to add the helper. In your AppController add:

public $helpers = ['AssetCompress.AssetCompress'];

Or add the AssetCompress helper to your existing helpers array. Next, link the build file in your layout:

<?= $this->AssetCompress->script('jquery-combined'); ?>

After refreshing the page, you should get jQuery, and all your plugins as a single request.

Using filters

Filters let you modify the concatenated output or pre-process files before they are concatenated together. There are several built-in filters covering a range of uses. To set up the JsMinFilter, you should first install jsmin with composer:

$ composer require linkorb/jsmin-php

Then add the following to your asset_compress.ini file:

[js]
...
filters[] = JsMinFilter

Since JsMin is an output filter, it won't be applied during development, but will be applied when you generate static assets with the Shell. When applied, the JsMinFilter creates minified files.

In depth usage

  • Configuration Configuring Asset Compress. Defining build files and plugin behaviour.
  • Filters Filtering the concatenated output.
  • Shell The asset compress shell, used for generating and clearing build files.
  • Helper Usage Using the AssetCompress helper in your application.
  • Troubleshooting WTF, and how you might be able to fix it.