README.md
94 lines
| 1 | # svg-sanitizer |
| 2 | |
| 3 | [](https://travis-ci.org/darylldoyle/svg-sanitizer](https://travis-ci.org/darylldoyle/svg-sanitizer](https://travis-ci.org/darylldoyle/svg-sanitizer) [](https://codeclimate.com/github/darylldoyle/svg-sanitizer/coverage](https://codeclimate.com/github/darylldoyle/svg-sanitizer/coverage](https://codeclimate.com/github/darylldoyle/svg-sanitizer/coverage) |
| 4 | |
| 5 | This is my attempt at building a decent SVG sanitizer in PHP. The work is largely borrowed from [](https://github.com/cure53/DOMPurifyDOMPurify](https://github.com/cure53/DOMPurify](https://github.com/cure53/DOMPurify). |
| 6 | |
| 7 | ## Installation |
| 8 | |
| 9 | Either require `enshrined/svg-sanitize` through composer or download the repo and include the old way! |
| 10 | |
| 11 | ## Usage |
| 12 | |
| 13 | Using this is fairly easy. Create a new instance of `enshrined\svgSanitize\Sanitizer` and then call the `sanitize` whilst passing in your dirty SVG/XML |
| 14 | |
| 15 | **Basic Example** |
| 16 | |
| 17 | ```php |
| 18 | use enshrined\svgSanitize\Sanitizer; |
| 19 | |
| 20 | // Create a new sanitizer instance |
| 21 | $sanitizer = new Sanitizer(); |
| 22 | |
| 23 | // Load the dirty svg |
| 24 | $dirtySVG = file_get_contents('filthy.svg'); |
| 25 | |
| 26 | // Pass it to the sanitizer and get it back clean |
| 27 | $cleanSVG = $sanitizer->sanitize($dirtySVG); |
| 28 | |
| 29 | // Now do what you want with your clean SVG/XML data |
| 30 | |
| 31 | ``` |
| 32 | |
| 33 | ## Output |
| 34 | |
| 35 | This will either return a sanitized SVG/XML string or boolean `false` if XML parsing failed (usually due to a badly formatted file). |
| 36 | |
| 37 | ## Options |
| 38 | |
| 39 | You may pass your own whitelist of tags and attributes by using the `Sanitizer::setAllowedTags` and `Sanitizer::setAllowedAttrs` methods respectively. |
| 40 | |
| 41 | These methods require that you implement the `enshrined\svgSanitize\data\TagInterface` or `enshrined\svgSanitize\data\AttributeInterface`. |
| 42 | |
| 43 | ## Remove remote references |
| 44 | |
| 45 | You have the option to remove attributes that reference remote files, this will stop HTTP leaks but will add an overhead to the sanitizer. |
| 46 | |
| 47 | This defaults to false, set to true to remove references. |
| 48 | |
| 49 | `$sanitizer->removeRemoteReferences(true);` |
| 50 | |
| 51 | ## Viewing Sanitization Issues |
| 52 | |
| 53 | You may use the `getXmlIssues()` method to return an array of issues that occurred during sanitization. |
| 54 | |
| 55 | This may be useful for logging or providing feedback to the user on why an SVG was refused. |
| 56 | |
| 57 | `$issues = $sanitizer->getXmlIssues();` |
| 58 | |
| 59 | ## Minification |
| 60 | |
| 61 | You can minify the XML output by calling `$sanitizer->minify(true);`. |
| 62 | |
| 63 | ## Demo |
| 64 | There is a demo available at: [](http://svg.enshrined.co.uk/http://svg.enshrined.co.uk/](http://svg.enshrined.co.uk/](http://svg.enshrined.co.uk/) |
| 65 | |
| 66 | ## WordPress |
| 67 | |
| 68 | I've just released a WordPress plugin containing this code so you can sanitize your WordPress uploads. It's available from the WordPress plugin directory: [](https://wordpress.org/plugins/safe-svg/https://wordpress.org/plugins/safe-svg/](https://wordpress.org/plugins/safe-svg/](https://wordpress.org/plugins/safe-svg/) |
| 69 | |
| 70 | ## Drupal |
| 71 | |
| 72 | [](https://github.com/heyMPMichael Potter](https://github.com/heyMP](https://github.com/heyMP) has kindly created a Drupal module for this library which is available at: [](https://www.drupal.org/project/svg_sanitizerhttps://www.drupal.org/project/svg_sanitizer](https://www.drupal.org/project/svg_sanitizer](https://www.drupal.org/project/svg_sanitizer) |
| 73 | |
| 74 | ## TYPO3 |
| 75 | |
| 76 | This SVG sanitizer library is used per default in the core of TYPO3 v9 and later versions. |
| 77 | See [](https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/9.5.x/Important-94492-IntroduceSVGSanitizer.htmlcorresponding changelog entry](https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/9.5.x/Important-94492-IntroduceSVGSanitizer.html](https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/9.5.x/Important-94492-IntroduceSVGSanitizer.html) for more details. |
| 78 | |
| 79 | ## Tests |
| 80 | |
| 81 | You can run these by running `vendor/bin/phpunit` from the base directory of this package. |
| 82 | |
| 83 | ## Standalone scanning of files via CLI |
| 84 | |
| 85 | Thanks to the work by [](https://github.com/gudmdharaldsgudmdharalds](https://github.com/gudmdharalds](https://github.com/gudmdharalds) there's now a standalone scanner that can be used via the CLI. |
| 86 | |
| 87 | Any errors will be output in JSON format. See [](https://github.com/darylldoyle/svg-sanitizer/pull/25the PR](https://github.com/darylldoyle/svg-sanitizer/pull/25](https://github.com/darylldoyle/svg-sanitizer/pull/25) for an example. |
| 88 | |
| 89 | Use it as follows: `php svg-scanner.php ~/svgs/myfile.svg` |
| 90 | |
| 91 | ## To-Do |
| 92 | |
| 93 | More extensive testing for the SVGs/XML would be lovely, I'll try and add these soon. If you feel like doing it for me, please do and make a PR! |
| 94 |