Wikimedia CSS Parser & Sanitizer

This library implements a CSS tokenizer, parser and grammar matcher in PHP.

Usage

use Wikimedia\CSS\Parser\Parser;
use Wikimedia\CSS\Sanitizer\StylesheetSanitizer;
 
$parser = Parser::newFromString( $cssText );
$stylesheet = $parser->parseStylesheet();
 
foreach ( $parser->getParseErrors() as list( $code, $line, $pos ) ) {
    // $code is a string that should be suitable as a key for an i18n library.
    // See errors.md for details.
    $error = lookupI18nMessage( "css-parse-error-$code" );
    echo "Parse error: $error at line $line character $pos\n";
}
 
// If you need to customize the defaults, copy the code of this method and
// modify it.
$sanitizer = StylesheetSanitizer::newDefault();
$newStylesheet = $sanitizer->sanitize( $stylesheet );
 
foreach ( $sanitizer->getSanitizationErrors() as list( $code, $line, $pos ) ) {
    // $code is a string that should be suitable as a key for an i18n library.
    // See errors.md for details.
    $error = lookupI18nMessage( "css-sanitization-error-$code" );
    echo "Sanitization error: $error at line $line character $pos\n";
}
 
$newText = (string)$newStylesheet;
 
// Or if you'd rather have it minified too
$minifiedText = Wikimedia\CSS\Util::stringify( $newStylesheet, [ 'minify' => true ] );

Conformance

The library follows the following grammar specifications:

The sanitizer recognizes the following CSS modules:

And also,

The touch-action property from Pointer Events Level 2, 2019-04-04
:dir() pseudo-class from Selectors Level 4, 2022-11-11

Running tests

composer install --prefer-dist
composer test

Releasing a new version

This package uses wikimedia/update-history and its conventions.

See https://www.mediawiki.org/wiki/UpdateHistory for details.

History

We required a CSS sanitizer with several properties:

Strict parsing according to modern standards.
Includes line and character position for all errors.
Configurable to limit unsafe constructs such as external URL references.
Errors are easily localizable.

We could not find a library that fit these requirements, so we created one.

Additional release history is in HISTORY.md.