README

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,

The touch-action property from Pointer Events Level 2, 2019-04-04
:dir() pseudo-class from Selectors Level 4, 2022-11-11
Accessibility related media features from Media Queries Level 5 including prefers-reduced-motion, prefers-reduced-transparency, prefers-contrast and forced-colors.
light-dark() color function from Color Module Level 5, 2024-02-29

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.

wikimedia / css-sanitizer

Maintainers

Details