README

This port is based on version 2.4.8 (Jun 12, 2013) of the YUI compressor.
This port contains fixes & features not present in the original YUI compressor.

Table of Contents

1. Installation & requirements
2. How to use
3. Tests
4. API Reference
5. Who uses this?
6. Changelog

1. Installation & requirements

Installation

Use Composer to include the library into your project:

$ composer.phar require tubalmartin/cssmin

Require Composer's autoloader file:

<?php

require './vendor/autoload.php';

use tubalmartin\CssMin\Minifier as CSSmin;

// Use it!
$compressor = new CSSmin;

Requirements

• PHP 5.3.2 or newer with PCRE extension.

2. How to use

There are three ways you can use this library:

1. PHP
2. CLI
3. GUI

PHP

<?php

// Autoload libraries
require './vendor/autoload.php';

use tubalmartin\CssMin\Minifier as CSSmin;

// Extract the CSS code you want to compress from your CSS files
$input_css = file_get_contents('test.css');

// Create a new CSSmin object.
// By default CSSmin will try to raise PHP settings.
// If you don't want CSSmin to raise the PHP settings pass FALSE to
// the constructor i.e. $compressor = new CSSmin(false);
$compressor = new CSSmin;

// Set the compressor up before compressing (global setup):

// Keep sourcemap comment in the output.
// Default behavior removes it.
$compressor->keepSourceMapComment();

// Remove important comments from output.
$compressor->removeImportantComments();

// Split long lines in the output approximately every 1000 chars.
$compressor->setLineBreakPosition(1000);

// Override any PHP configuration options before calling run() (optional)
$compressor->setMemoryLimit('256M');
$compressor->setMaxExecutionTime(120);
$compressor->setPcreBacktrackLimit(3000000);
$compressor->setPcreRecursionLimit(150000);

// Compress the CSS code!
$output_css = $compressor->run($input_css);

// You can override any setup between runs without having to create another CSSmin object.
// Let's say you want to remove the sourcemap comment from the output and
// disable splitting long lines in the output.
// You can achieve that using the methods `keepSourceMap` and `setLineBreakPosition`:
$compressor->keepSourceMapComment(false);
$compressor->setLineBreakPosition(0);
$output_css = $compressor->run($input_css); 

// Do whatever you need with the compressed CSS code
echo $output_css;

CLI

A binary file named cssmin will be created after installation in ./vendor/bin folder.

Output help:

./vendor/bin/cssmin -h

Output compression result to the command line:

./vendor/bin/cssmin -i ./my-css-file.css

Output compression result to another file:

./vendor/bin/cssmin -i ./my-css-file.css -o ./my-css-file.min.css

Output compression result to another file and keep sourcemap comment in the output:

./vendor/bin/cssmin -i ./my-css-file.css -o ./my-css-file.min.css --keep-sourcemap

See the binary help for all available CLI options.

GUI

We've made a simple web based GUI to use the compressor, it's in the gui folder.

GUI features:

• Optional on-the-fly LESS compilation before compression with error reporting included.
• Absolute control of the library.

How to use the GUI:

• You need a server with PHP 5.3.2+ installed.
• Download the repository and upload it to a folder in your server.
• Run php composer.phar install in project's root to install dependencies.
• Open your favourite browser and enter the URL to the /gui folder.

3. Tests

Tests from YUI compressor have been modified to fit this port.

How to run the test suite:

• Run php composer.phar install in project's root to install dependencies. phpunit will be installed locally.
• After that, run phpunit in the command line:

./vendor/bin/phpunit

PHPUnit diffing is too simple so when a test fails it's hard to see the actual diff, that's why I've created a test runner that displays inline coloured diffs for a failing test. Only one test can be run at a time.

Here's how to use it:

./tests/bin/runner -t <expectation-name> [-f <fixture-name>] [--keep-sourcemap] [--remove-important-comments] [--linebreak-position <pos>]

4. API Reference

__construct ([ bool $raisePhpLimits ])

Class constructor, creates a new CSSmin object.

Parameters

raisePhpLimits

If TRUE, CSSmin will try to raise the values of some php configuration options. Set to FALSE to keep the values of your php configuration options. Defaults to TRUE.

run (string $css)

Minifies a string of uncompressed CSS code. run() may be called multiple times on a single CSSmin instance.

Parameters

css

A string of uncompressed CSS code. CSSmin default value: '' (empty string).

Return Values

A string of compressed CSS code or an empty string if no string is passed.

keepSourceMapComment (bool $keepSourceMap)

Sets whether to keep sourcemap comment /*# sourceMappingURL=<path> */in the output.
CSSmin default behavior: Sourcemap comment gets removed from output.

removeImportantComments (bool $removeImportantComments)

Sets whether to remove important comments from output.
CSSmin default behavior: Important comments outside declaration blocks are kept in the output.

setLinebreakPosition (int $position)

Some source control tools don't like it when files containing lines longer than, say 8000 characters, are checked in. The linebreak option is used in that case to split long lines after a specific column.

CSSmin default value: 0 (all CSS code in 1 long line).
Minimum value supported: 1.

setMaxExecutionTime (int $seconds)

Sets the max_execution_time configuration option for this script

CSSmin default value: 60
Values & notes: max_execution_time documentation

setMemoryLimit (mixed $limit)

Sets the memory_limit configuration option for this script

CSSmin default value: 128M
Values & notes: memory_limit documentation

setPcreBacktrackLimit (int $limit)

Sets the pcre.backtrack_limit configuration option for this script

CSSmin default value: 1000000
Values & notes: pcre.backtrack_limit documentation

setPcreRecursionLimit (int $limit)

Sets the pcre.recursion_limit configuration option for this script.

CSSmin default value: 500000
Values & notes: pcre.recursion_limit documentation

5. Who uses this port

• Magento eCommerce platforms and solutions for selling online.
• Minify Minify is an HTTP content server. It compresses sources of content (usually files), combines the result and serves it with appropriate HTTP headers.
• Autoptimize is a Wordpress plugin. Autoptimize speeds up your website and helps you save bandwidth by aggregating and minimizing JS, CSS and HTML.
• IMPRESSPAGES PHP framework with content editor.
• Other dependent Composer packages.

6. Changelog

v4.1.1 15 Jan 2018

FIXED:

• Breakage when minifying at-import rule with unquoted urls containing semicolons #45

v4.1.0 16 May 2017

• NEW:
  • --dry-run CLI argument to perform a dry run and display statistics.
• IMPROVED:
  • Performance: 2x times faster than v4.0.0 after code profiling:
    • A 1MB file takes 1.8s with PHP 5.3.29 and 350ms with PHP 7.0.18 (on average).
    • A full Bootstrap v3.3.7 CSS suite takes 330ms with PHP 5.3.29 and 50ms with PHP 7.0.18 (on average).

v4.0.0 15 May 2017

NEW:

• API:
  • Removed: setChunkLength() method and --chunk-length CLI argument.
  • Modified: keepSourceMap() method is now named keepSourceMapComment(). CLI argument --keep-sourcemap stays the same but we've added --keep-sourcemap-comment too.
  • Modified: run() method signature. It only accepts one argument now.
  • Added: removeImportantComments() method & --keep-important-comments CLI argument.
• Important comments /*! ... */ can be optionally removed from output too calling removeImportantComments() method.

v3.3.1 16 May 2017

• Backported performance improvements made in v4.1.0

v3.3.0 13 May 2017

NEW:

• CLI binary displays some useful stats after execution.
• A concatenated file can be safely compressed now: @charset, @import & @namespace at-rules will be placed correctly.
• Conditional group rules fully and safely supported, that is, unlimited rule nesting levels. Previously only one nesting level was fully supported.

NOTES:

• Pretty big refactor done for two main reasons:
  • Make minified output even more reliable even when a potential scenario has not been tested beforehand.
  • Make development, testing and contribution a bit easier due to simplified logic.
• As a consequence of this refactor, stylesheet chunking is not needed anymore. setChunkLength method and --chunk-length CLI argument still exist for backwards compatibility reasons but have no effect at all.

v3.2.0 10 May 2017

NEW:

• PHPUnit added as test runner.
• CLI binary provided.
• CSS Sourcemap special comment supported.
• ms unit compression: from 300ms to .3s.
• Shortable double colon (CSS3) pseudo-elements are now shortened to single colon (CSS2): from ::after to :after.
• background: none & background: transparent are shortened to background:0 0.

IMPROVED:

• Some regular expressions.
• Long line splitting algorithm.
• Lowercasing pseudo-classes, pseudo-elements and functions to cover more cases.
• Shortening of suitable shorthand properties with repeated values. All cases are covered now.
• Tests.

FIXED:

• When splitting long lines in the output, if a comment or string contained closing curly braces }, the curly brace could be recognised as a selector or at-rule closing curly brace resulting in an unexpected newline being added.

v3.1.2 17 Apr 2017

• Improved compression of long named colors: now all long named colors get compressed to their shorter HEX counterpart.
• Fixes cases such as #39
• Huge performance improvement after code profiling. See table below for results when running the whole test suite:

PHP version used: 5.3.29

PHP version used: 7.0.8

v3.1.1 11 Apr 2017

• Regexes improved.
• Small performance improvements.
• Blocks such as @media blocks with empty rules are removed too.
• Quoted unquotable attribute selectors get unquoted now i.e. from col[class*="col-"] to col[class*=col-]. Covers most common cases. Safe approach.

v3.1.0 9 Apr 2017

• Code deeply analyzed. Some areas rewritten from the ground up with maximum performance in mind. No change in compressor behavior.
• Fixed some hidden bugs discovered along the way that affected performance negatively.
• IE5/Mac comment hack removed from minifier logic. Those comments will no longer be preserved.
• The table below displays the performance optimization done in this version in comparison with the previous one running the whole test suite:

PHP version used: 5.3.29

PHP version used: 7.0.8

v3.0.0 4 Apr 2017

• New API compliant with PSR-1, PSR-2 & PSR-4. PHP 5.3.2+ required. I think it was time!
• Many tests added, strengthened and fixed. Big, real life, stylesheets included such as Bootstrap or Foundation.
• Fixed some critical and minor issues, such as:
  • Chunking system breaking some stylesheets (broken at rules block) or leaving some bits off.
  • Backreferences in replacement strings breaking stylesheets.
  • #23
  • Others...
• Color compression improved. Now all named colors are supported i.e. from white to #fff.
• Shortening zero values is back but in a safe manner, shortening values assigned to "safe" properties only i.e. from margin: 1px 0.0em 0rem 0% to margin:1px 0 0. Check the code to see the list of "safe" properties.
• padding and margin properties are shortened to the bare minimum i.e. from margin: 3px 2.1em 3px 2.1em => margin:3px 2.1em
• Upgrading to v3 is strongly recommended for users enjoying PHP 5.3.2+.

v2.4.8-p10 4 Apr 2017

• This is the last v2 release. v3 onwards will only support PHP 5.3.2+.
• This patch has all improvements and fixes v3.0.0 has. See v3.0.0 notes for further info (no API change in this version of course).
• Updating to this patch is strongly recommended for users stuck with PHP versions lower than PHP 5.3.

v2.4.8-p9 28 Mar 2017

• Rolling back property declaration with scalar expressions (>= PHP 5.6) introduced in v2.4.8-p8 to support PHP 5.0. No change in compressor behavior.

v2.4.8-p8 27 Mar 2017

• Fixed issue #18
• Added set_chunk_length method.
• bold & normal values get compressed to 700 & 400 respectively for font-weight property.
• GUI updated.
• FineDiff library loaded through Composer.
• README updated.

v2.4.8-p7 26 Mar 2017

• Fixed many issues #20, #22, #24, #25, #26 reported by contributors and others that I'm sure haven't been reported, at least yet. Sorry for the long delay guys.
• This release is all about stability and reliability and as such I've had to take some controversial decisions such as:
  • Not minifying none property value to 0 because in some subtle scenarios the resulting output may render some styles differently.
  • Not removing units from zero length values because in many cases the output will break the intended behavior. Patching every single case after someone finds a new breaking case is not good IMHO taking into account CSS is a live spec and browsers differ in some cases.
• Hope you agree with me removing those conflicting parts. Enjoy this release :)

v2.4.8-p6 21 Mar 2017

• Fixed PHP CLI issues. See #36

v2.4.8-p5 27 Feb 2017

• Fixed PHP 7 issues.

v2.4.8-p4 22 Sep 2014

• Composer support. The package is tubalmartin/cssmin
• Fixed issue #17

v2.4.8-p3 26 Apr 2014

• Fixed all reported bugs: See issues #11, #13 (first case only) and #14.
• LESS compiler upgraded to version 1.7.0

v2.4.8-p2 13 Nov 2013

• Chunk length reduced to 5000 chars (previously 25.000 chars) in an effort to avoid PCRE backtrack limits (needs feedback).
• Improvements for the @keyframes 0% step bug. Tests improved.
• Fix IE7 issue on matrix filters which browser accept whitespaces between Matrix parameters
• LESS compiler upgraded to version 1.4.2

v2.4.8-p1 8 Aug 2013

• Fix for the @keyframes 0% step bug. Tests added.
• LESS compiler upgraded to version 1.4.1