MediaWiki 1.30.2

[autoinstallsdev/mediawiki.git] / vendor / wikimedia / css-sanitizer / README.md

diff --git a/vendor/wikimedia/css-sanitizer/README.md b/vendor/wikimedia/css-sanitizer/README.md
new file mode 100644 (file)
index 0000000..225c320
--- /dev/null
+++ b/vendor/wikimedia/css-sanitizer/README.md
@@ -0,0 +1,82 @@
+[![Latest Stable Version]](https://packagist.org/packages/wikimedia/css-sanitizer) [![License]](https://packagist.org/packages/wikimedia/css-sanitizer)
+
+Wikimedia CSS Parser & Sanitizer
+================================
+
+This library implements a CSS tokenizer, parser and grammar matcher in PHP that
+mostly follows the [CSS Syntax Module Level 3 candidate recommendation dated 20
+February 2014][CSSSYN], the [CSS Values and Units Module Level 3][CSSVAL], and the
+[CSS Selectors Level 3][CSSSEL] grammar. It also provides a sanitizer that
+recognizes various [CSS3 modules][CSSWORK].
+
+Usage
+-----
+
+```php
+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 stylehseet **/
+
+// 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 ] );
+```
+
+Running tests
+-------------
+
+    composer install --prefer-dist
+    composer test
+
+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.
+
+
+---
+[Latest Stable Version]: https://poser.pugx.org/wikimedia/css-sanitizer/v/stable.svg
+[License]: https://poser.pugx.org/wikimedia/css-sanitizer/license.svg
+[CSSSYN]: https://www.w3.org/TR/2014/CR-css-syntax-3-20140220/
+[CSSVAL]: https://www.w3.org/TR/2016/CR-css-values-3-20160929/
+[CSSSEL]: https://www.w3.org/TR/2011/REC-css3-selectors-20110929/
+[CSSWORK]: https://www.w3.org/Style/CSS/current-work