wikimedia / css-sanitizer
Classes to parse and sanitize CSS
v5.4.0
2024-10-30 14:04 UTC
Requires
- php: >=7.4.0
- ext-iconv: *
- ext-mbstring: *
- wikimedia/scoped-callback: 3.0.0 || 4.0.0 || 5.0.0
- wikimedia/utfnormal: ^3.0.1 || ^4.0.0
Requires (Dev)
- mediawiki/mediawiki-codesniffer: 44.0.0
- mediawiki/mediawiki-phan-config: 0.14.0
- mediawiki/minus-x: 1.1.3
- php-parallel-lint/php-console-highlighter: 1.0.0
- php-parallel-lint/php-parallel-lint: 1.4.0
- phpunit/phpunit: 9.6.16
- wikimedia/testing-access-wrapper: ~2.0.0 || ~3.0.0
- wikimedia/update-history: ^1.0.1
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:
- CSS Syntax Level 3, 2019-07-16
- CSS Values and Units Module Level 3, 2019-06-06
- CSS Selectors Level 3, 2018-11-06
The sanitizer recognizes the following CSS modules:
- Align Level 3, 2018-12-06
- Animations Level 1, 2018-10-11
- Backgrounds Level 3, 2017-10-17
- Break Level 3, 2018-12-04
- Cascade Level 4, 2018-08-28
- Color Level 3, 2018-06-19
- Compositing Level 1, 2015-01-13
- CSS Level 2, 2011-06-07
- Display Level 3, 2019-07-11
- Filter Effects Level 1, 2018-12-18
- Flexbox Level 1, 2018-11-19
- Fonts Level 3, 2018-09-20
- Grid Level 1, 2017-12-14
- Images Level 3, 2019-10-10
- Masking Level 1, 2014-08-26
- Multicol Level 1, 2019-10-15
- Overflow Level 3, 2018-07-31
- Page Level 3, 2018-10-18
- Position Level 3, 2016-05-17
- Shapes Level 1, 2014-03-20
- Sizing Level 3, 2019-05-22
- Text Level 3, 2019-11-13
- Text Decorations Level 3, 2019-08-13
- Easing Level 1, 2019-04-30
- Transforms Level 1, 2019-02-14
- Transitions Level 1, 2018-10-11
- UI 3 Level 3, 2018-06-21
- UI 4 Level 4, 2020-01-02
- Writing Modes Level 4, 2019-07-30
- Selectors Level 4, 2019-02-25
- Logical Properties and Values Level 1, 2018-08-27
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
.