forked from a64f7bb4-7358-4778-9fbe-3b882c34cc1d/v1
462 lines
17 KiB
Markdown
462 lines
17 KiB
Markdown
# A PHP port of the YUI CSS compressor
|
|
|
|
[](https://packagist.org/packages/tubalmartin/cssmin) [](https://packagist.org/packages/tubalmartin/cssmin) [](https://packagist.org/packages/tubalmartin/cssmin) [](https://packagist.org/packages/tubalmartin/cssmin)
|
|
|
|
This port is based on version 2.4.8 (Jun 12, 2013) of the [YUI compressor](https://github.com/yui/yuicompressor).
|
|
This port contains fixes & features not present in the original YUI compressor.
|
|
|
|
**Table of Contents**
|
|
|
|
1. [Installation & requirements](#install)
|
|
2. [How to use](#howtouse)
|
|
3. [Tests](#tests)
|
|
4. [API Reference](#api)
|
|
5. [Who uses this?](#whousesit)
|
|
6. [Changelog](#changelog)
|
|
|
|
<a name="install"></a>
|
|
|
|
## 1. Installation & requirements
|
|
|
|
### Installation
|
|
|
|
Use [Composer](http://getcomposer.org/) to include the library into your project:
|
|
|
|
$ composer.phar require tubalmartin/cssmin
|
|
|
|
Require Composer's autoloader file:
|
|
|
|
```php
|
|
<?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.
|
|
|
|
<a name="howtouse"></a>
|
|
|
|
## 2. How to use
|
|
|
|
There are three ways you can use this library:
|
|
|
|
1. [PHP](#php)
|
|
2. [CLI](#cli)
|
|
3. [GUI](#gui)
|
|
|
|
<a name="php"></a>
|
|
|
|
### PHP
|
|
|
|
```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;
|
|
```
|
|
|
|
<a name="cli"></a>
|
|
|
|
### 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.
|
|
|
|
<a name="gui"></a>
|
|
|
|
### 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.
|
|
|
|
<a name="tests"></a>
|
|
|
|
## 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>]
|
|
```
|
|
|
|
<a name="api"></a>
|
|
|
|
## 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](http://php.net/manual/en/info.configuration.php#ini.max-execution-time)
|
|
|
|
### setMemoryLimit (mixed *$limit*)
|
|
|
|
Sets the `memory_limit` configuration option for this script
|
|
|
|
CSSmin default value: `128M`
|
|
Values & notes: [memory_limit documentation](http://php.net/manual/en/ini.core.php#ini.memory-limit)
|
|
|
|
### setPcreBacktrackLimit (int *$limit*)
|
|
|
|
Sets the `pcre.backtrack_limit` configuration option for this script
|
|
|
|
CSSmin default value: `1000000`
|
|
Values & notes: [pcre.backtrack_limit documentation](http://php.net/manual/en/pcre.configuration.php#ini.pcre.backtrack-limit)
|
|
|
|
### setPcreRecursionLimit (int *$limit*)
|
|
|
|
Sets the `pcre.recursion_limit` configuration option for this script.
|
|
|
|
CSSmin default value: `500000`
|
|
Values & notes: [pcre.recursion_limit documentation](http://php.net/manual/en/pcre.configuration.php#ini.pcre.recursion-limit)
|
|
|
|
|
|
<a name="whousesit"></a>
|
|
|
|
## 5. Who uses this port
|
|
|
|
* [Magento](https://magento.com/) eCommerce platforms and solutions for selling online.
|
|
* [Minify](https://github.com/mrclay/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](http://wordpress.org/plugins/autoptimize/) is a Wordpress plugin. Autoptimize speeds up your website and helps you save bandwidth by aggregating and minimizing JS, CSS and HTML.
|
|
* [IMPRESSPAGES](http://www.impresspages.org/) PHP framework with content editor.
|
|
* [Other dependent Composer packages](https://packagist.org/packages/tubalmartin/cssmin/dependents).
|
|
|
|
<a name="changelog"></a>
|
|
|
|
## 6. Changelog
|
|
|
|
### v4.1.1 15 Jan 2018
|
|
|
|
FIXED:
|
|
* Breakage when minifying at-import rule with unquoted urls containing semicolons [#45](https://github.com/tubalmartin/YUI-CSS-compressor-PHP-port/issues/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](https://github.com/tubalmartin/YUI-CSS-compressor-PHP-port/issues/39)
|
|
* Huge performance improvement after code profiling. See table below for results when running the whole test suite:
|
|
|
|
PHP version used: 5.3.29
|
|
|
|
| chunkLength | v3.1.1 | v3.1.2 |
|
|
| --- | --- | --- |
|
|
| 100 | 6.8s | 2.6s |
|
|
| 1000 | 5.3s | 2s |
|
|
| 2000 | 5.2s | 1.95s |
|
|
| 5000 | 5.1s | 1.9s |
|
|
|
|
PHP version used: 7.0.8
|
|
|
|
| chunkLength | v3.1.1 | v3.1.2 |
|
|
| --- | --- | --- |
|
|
| 100 | 2s | 0.72s |
|
|
| 1000 | 1s | 0.37s |
|
|
| 2000 | 0.8s | 0.33s |
|
|
| 5000 | 0.7s | 0.3s |
|
|
|
|
|
|
### 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
|
|
|
|
| chunkLength | v3.0.0 | v3.1.0 |
|
|
| --- | --- | --- |
|
|
| 100 | 38s | 6.9s |
|
|
| 1000 | 8.5s | 5.4s |
|
|
| 2000 | 7.3s | 5.3s |
|
|
| 5000 | 5.8s | 5.2s |
|
|
|
|
PHP version used: 7.0.8
|
|
|
|
| chunkLength | v3.0.0 | v3.1.0 |
|
|
| --- | --- | --- |
|
|
| 100 | 22.8s | 2.1s |
|
|
| 1000 | 2.9s | 1.1s |
|
|
| 2000 | 2s | 0.9s |
|
|
| 5000 | 1.3s | 0.8s |
|
|
|
|
### 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](https://github.com/tubalmartin/YUI-CSS-compressor-PHP-port/issues/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](https://github.com/tubalmartin/YUI-CSS-compressor-PHP-port/pull/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](https://github.com/tubalmartin/YUI-CSS-compressor-PHP-port/issues/20), [#22](https://github.com/tubalmartin/YUI-CSS-compressor-PHP-port/issues/22), [#24](https://github.com/tubalmartin/YUI-CSS-compressor-PHP-port/issues/24), [#25](https://github.com/tubalmartin/YUI-CSS-compressor-PHP-port/issues/25), [#26](https://github.com/tubalmartin/YUI-CSS-compressor-PHP-port/issues/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](https://github.com/tubalmartin/YUI-CSS-compressor-PHP-port/pull/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](https://packagist.org/packages/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
|
|
|
|
[#11]: https://github.com/tubalmartin/YUI-CSS-compressor-PHP-port/issues/11
|
|
[#13]: https://github.com/tubalmartin/YUI-CSS-compressor-PHP-port/issues/13
|
|
[#14]: https://github.com/tubalmartin/YUI-CSS-compressor-PHP-port/issues/14
|
|
[#17]: https://github.com/tubalmartin/YUI-CSS-compressor-PHP-port/issues/17
|