wikimedia/css-sanitizer

Classes to parse and sanitize CSS

v5.5.0 2025-01-27 12:21 UTC

This package is auto-updated.

Last update: 2025-05-19 21:33:35 UTC


README

Latest Stable Version License

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;

/** Parse a stylesheet from a string **/

$parser = Parser::newFromString( $cssText );
$stylesheet = $parser->parseStylesheet();

/** Report any parser errors **/

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";
}

/** Apply sanitization to the stylesheet **/

// If you need to customize the defaults, copy the code of this method and
// modify it.
$sanitizer = StylesheetSanitizer::newDefault();
$newStylesheet = $sanitizer->sanitize( $stylesheet );

/** Report any sanitizer errors **/

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";
}

/** Convert the sanitized stylesheet back to text **/

$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,

Running tests

composer install --prefer-dist
composer test

Adding properties

CSS specifications typically contain a summary of value grammars in the property index section. These value grammars map directly to PHP code.

Component value types

Syntax css-sanitizer code
foo new KeywordMatcher( 'foo' )
foo | bar new KeywordMatcher( [ 'foo', 'bar' ] )
<string> $matcherFactory->string()
<url> $matcherFactory->url()
<integer> $matcherFactory->integer()
<number> $matcherFactory->number()
<ratio> $matcherFactory->ratio()
<percentage> $matcherFactory->percentage()
<length> $matcherFactory->length()
<frequency> $matcherFactory->frequency()
<angle> $matcherFactory->angle()
<time> $matcherFactory->time()
<resolution> $matcherFactory->resolution()

Component value combinators

Syntax css-sanitizer code
a b new Juxtaposition( [ a, b ] )
a && b UnorderedGroup::allOf( [ a, b ] )
a || b UnorderedGroup::someOf( [ a, b ] )
a | b new Alternative( [ a, b ] )

Component value multipliers

Syntax css-sanitizer code
a* Quantifier::star( a )
a+ Quantifier::plus( a )
a? Quantifier::optional( a )
a{3,4} Quantifier::count( a, 3, 4 )
a# Quantifier::hash( a )
a! new NonEmpty( a )

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.