Merge pull request #12 from snebes/composer

package version constraints
snebes · Apr 28, 2019 · a62d415 · a62d415
2 parents cbb2778 + a3b9d09
commit a62d415
Show file tree

Hide file tree

Showing 7 changed files with 129 additions and 201 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,6 @@
 vendor
 composer.lock
 .php_cs.cache
+.phpunit.result.cache
 .idea
 phpunit.xml
diff --git a/.travis.yml b/.travis.yml
@@ -1,13 +1,23 @@
 language: php
+
 php:
     - '7.1'
     - '7.2'
     - '7.3'
-before_install:
-    - 'composer selfupdate'
-install:
-    - 'composer install --prefer-dist --no-interaction $COMPOSER_FLAGS'
+
+matrix:
+    include:
+        - php: '7.1'
+          env: SYMFONY_VERSION="symfony/lts:^3"
+    fast_finish: true
+
+before_script:
+    - if [ "$SYMFONY_VERSION" != "" ]; then travis_wait composer require --no-update $SYMFONY_VERSION; fi;
+    - 'composer update --prefer-dist --no-interaction $COMPOSER_FLAGS'
+
 script:
+    - 'composer validate --no-check-lock --strict'
     - 'phpunit --configuration phpunit.xml.dist --coverage-text'
+
 notifications:
     email: '[email protected]'
diff --git a/composer.json b/composer.json
@@ -22,12 +22,12 @@
     "require": {
         "php": ">=7.1",
         "ext-dom": "*",
-        "masterminds/html5": "^2.4",
+        "ext-mbstring": "*",
+        "masterminds/html5": "^2.0",
         "psr/log": "^1.0",
-        "symfony/options-resolver": "^4.2"
+        "symfony/options-resolver": "^3.0|^4.0"
     },
     "require-dev": {
-        "phpunit/phpunit": "^7.5",
-        "symfony/var-dumper": "^4.1"
+        "phpunit/phpunit": "^7.5"
     }
 }
diff --git a/docs/1-getting-started.md b/docs/1-getting-started.md
@@ -3,9 +3,12 @@
 - [Installation](#installation)
 - [Basic usage](#basic-usage)
 - [Extensions](#extensions)
-- [Filtering links, images and iframes hosts](#filtering-links-images-and-iframes-hosts)
-- [Forcing HTTPS on links, images and iframes hosts](#forcing-https-on-images-and-iframes-source-hosts)
 - [Configuring allowed attributes](#configuring-allowed-attributes)
+- [Configuring blocked attributes](#configuring-blocked-attributes)
+- [Configuring allowed classes](#configuring-allowed-classes)
+- [Configuring blocked classes](#configuring-blocked-classes)
+- [Configuring childless tags](#configuring-childless-tags)
+- [Converting tags](#converting-tags)
 
 ## Installation
 
@@ -14,16 +17,16 @@ html-sanitizer requires PHP 7.1+.
 You can install the library using the following command:
 
 ```
-composer require tgalopin/html-sanitizer
+composer require snebes/html-sanitizer
 ```
 
 ## Basic usage
 
-The main entry point to the sanitizer is the `HtmlSanitizer\Sanitizer` class. It requires
+The main entry point to the sanitizer is the `SN\HtmlSanitizer\Sanitizer` class. It requires
 an array of configuration:
 
 ```php
-$sanitizer = HtmlSanitizer\Sanitizer::create(['extensions' => ['basic']]);
+$sanitizer = SN\HtmlSanitizer\Sanitizer::create(['extensions' => ['html5']]);
 $safeHtml = $sanitizer->sanitize($untrustedHtml);
 ```
 
@@ -36,150 +39,142 @@ enable to allow specific tags in the content (read the next part to learn more a
 ## Extensions
 
 Extensions are a way to quickly add sets of tags to the whitelist of allowed tags.
-There are 8 core extensions that you can enable by adding them in your configuration:
+There is 1 core extension that you can enable by adding them in your configuration:
 
 ```php
-$sanitizer = HtmlSanitizer\Sanitizer::create([
-    'extensions' => ['basic', 'code', 'image', 'list', 'table', 'iframe', 'details', 'extra'],
+$sanitizer = SN\HtmlSanitizer\Sanitizer::create([
+    'extensions' => ['html5'],
 ]);
 $safeHtml = $sanitizer->sanitize($untrustedHtml);
 ```
 
 Here is the list of tags each extension allow:
 
-- **basic** allows the insertion of basic HTML elements:
-  `a`, `b`, `br`, `blockquote`, `div`, `del`, `em`, `figcaption`, `figure`, `h1`, `h2`, `h3`, `h4`, `h5`, 
-  `h6`, `i`, `p`, `q`, `small`, `span`, `strong`, `sub`, `sup`
-- **list** allows the insertion of lists: 
-  `dd`, `dl`, `dt`, `li`, `ol`, `ul`
-- **table** allows the insertion of tables: 
-  `table`, `thead`, `tbody`, `tfoot`, `tr`, `td`, `th`
-- **image** allows the insertion of images: `img`
-- **code** allows the insertion of code blocks: `pre`, `code`
-- **iframe** allows the insertion of iframes: `iframe`
-- **details** allows the insertion of view/hide blocks: `details`, `summary`
-- **extra** allows the insertion of the following tags: `abbr`, `caption`, `hr`, `rp`, `rt`, `ruby`
+- **html5** allows the insertion of basic HTML elements:
+  `a`, `abbr`, `address`, `applet`, `area`, `article`, `aside`, `audio`, `b`, `base`, `bdi`, `bdo`, `blockquote`,
+  `body`, `br`, `button`, `canvas`, `caption`, `cite`, `code`, `col`, `colgroup`, `content`, `data`, `datalist`, `dd`,
+  `del`, `details`, `dfn`, `dialog`, `dir`, `div`, `dl`, `dt`, `element`, `em`, `embed`, `fieldset`, `figcaption`, 
+  `figure`, `footer`, `form`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `head`, `header`, `hgroup`, `hr`, `html`, `i`, 
+  `iframe`, `img`, `input`, `ins`, `kbd`, `label`, `legend`, `li`, `link`, `main`, `map`, `mark`, `menu`, `menuitem`, 
+  `meta`, `meter`, `nav`, `noembed`, `noscript`, `object`, `ol`, `optgroup`, `option`, `output`, `p`, `param`, 
+  `picture`, `pre`, `progress`, `q`, `rb`, `rp`, `rt`, `rtc`, `ruby`, `s`, `samp`, `script`, `section`, `select`, 
+  `shadow`, `slot`, `small`, `source`, `span`, `strong`, `style`, `sub`, `summary`, `sup`, `table`, `tbody`, `td`, 
+  `template`, `textarea`, `tfoot`, `th`, `thead`, `time`, `title`, `tr`, `track`, `tt`, `u`, `ul`, `var`, `video`, `wbr`
 
 > Note: sensible attributes are allowed by default for each tag (for instance, the `src` attribute is
 > allowed by default on images). You can also
 > [override these allowed attributes manually](#configuring-allowed-attributes) if you need to.
 
-## Filtering links, images and iframes hosts
-
-> Note: the Sanitizer does not allow relative URLs: they are always filtered out for security reasons.
+## Configuring allowed attributes
 
-The sanitizer basic, image and iframe extensions provide a feature to filter hosts, which can be useful 
-to avoid connecting to external websites that may, for instance, track your website views.
+The core extensions define sensible default allowed attributes for each tag, which mean you usually won't need
+to change them. However, if you want to customize which attributes are allowed on specific tags, you can use
+a tag-specific configuration for them. 
 
-To enable this feature, you need to configure the tags:
+For instance, to allow only the configured attributes on the `div` and `img` tags, you can use the following 
+configuration:
 
 ```php
 $sanitizer = HtmlSanitizer\Sanitizer::create([
-    'extensions' => ['basic', 'image', 'iframe'],
+    'extensions' => ['html5'],
     'tags' => [
-        'a' => [
-            /*
-             * If an array is provided, links targeting other hosts than one in this array
-             * will be disabled (the `href` attribute will be blank). This can be useful if you want
-             * to prevent links targeting external websites. Keep null to allow all hosts.
-             * Any allowed domain also includes its subdomains.
-             *
-             * Example:
-             *      'allowed_hosts' => ['trusted1.com', 'google.com'],
-             */
-            'allowed_hosts' => null,
-
-            /*
-             * If true, mailto links will be accepted.
-             */
-            'allow_mailto' => false,
+        'div' => [
+            'allowed_attributes' => ['class'],
         ],
-
         'img' => [
-            /*
-             * If an array is provided, images relying on other hosts than one in this array
-             * will be disabled (the `src` attribute will be blank). This can be useful if you want
-             * to prevent images contacting external websites. Keep null to allow all hosts.
-             * Any allowed domain also includes its subdomains.
-             *
-             * Example:
-             *      'allowed_hosts' => ['trusted1.com', 'google.com'],
-             */
-            'allowed_hosts' => null,
-
-            /*
-             * If true, images data-uri URLs will be accepted.
-             */
-            'allow_data_uri' => false,
-        ],
-
-        'iframe' => [
-            /*
-             * If an array is provided, iframes relying on other hosts than one in this array
-             * will be disabled (the `src` attribute will be blank). This can be useful if you want
-             * to prevent iframes contacting external websites.
-             * Any allowed domain also includes its subdomains.
-             *
-             * Example:
-             *      'allowed_hosts' => ['trusted1.com', 'google.com'],
-             */
-            'allowed_hosts' => null,
+            'allowed_attributes' => ['src', 'alt', 'title', 'class'],
         ],
     ],
 ]);
 ```
 
-## Forcing HTTPs on links, images and iframes hosts
+## Configuring blocked attributes
 
-The sanitizer basic, image and iframe extensions provide a feature to force HTTPs on targeted hosts.
+The core extensions by default allow any attribute to be used on a tag. However, if you want to customize which
+attributes are blocked on specific tags, you can use a tag-specific configuration for them. 
 
-To enable this feature, you need to configure the tags:
+For instance, to only disallow the `class` attribute on the `div` tags, you can use the following configuration:
 
 ```php
 $sanitizer = HtmlSanitizer\Sanitizer::create([
-    'extensions' => ['basic', 'image', 'iframe'],
+    'extensions' => ['html5'],
     'tags' => [
-        'a' => [
-            /*
-             * If true, all links targets using the HTTP protocol will be rewritten to use HTTPS instead.
-             */
-            'force_https' => false,
-        ],
-
-        'img' => [
-            /*
-             * If true, all images URLs using the HTTP protocol will be rewritten to use HTTPS instead.
-             */
-            'force_https' => false,
-        ],
-
-        'iframe' => [
-            /*
-             * If true, all iframes URLs using the HTTP protocol will be rewritten to use HTTPS instead.
-             */
-            'force_https' => false,
+        'div' => [
+            'blocked_attributes' => ['class'],
         ],
     ],
 ]);
 ```
 
-## Configuring allowed attributes
+## Configuring allowed classes
 
-The core extensions define sensible default allowed attributes for each tag, which mean you usually won't need
-to change them. However, if you want to customize which attributes are allowed on specific tags, you can use
+The core extensions by default allow any class to be used on a tag, which mean you usually won't need
+to change them. However, if you want to customize which classes are allowed on specific tags, you can use
 a tag-specific configuration for them. 
 
-For instance, to allow the `class` attribute on the `div` and `img` tags, you can use the following configuration:
+For instance, to only allow the `d-flex` class on the `div` tags, you can use the following configuration:
 
 ```php
 $sanitizer = HtmlSanitizer\Sanitizer::create([
-    'extensions' => ['basic'],
+    'extensions' => ['html5'],
     'tags' => [
         'div' => [
-            'allowed_attributes' => ['class'],
+            'allowed_classes' => ['d-flex'],
         ],
-        'img' => [
-            'allowed_attributes' => ['src', 'alt', 'title', 'class'],
+    ],
+]);
+```
+
+## Configuring blocked classes
+
+The core extensions by default allow any class to be used on a tag. However, if you want to customize which
+classes are blocked on specific tags, you can use a tag-specific configuration for them. 
+
+For instance, to only disallow the `float` class on the `div` tags, you can use the following configuration:
+
+```php
+$sanitizer = HtmlSanitizer\Sanitizer::create([
+    'extensions' => ['html5'],
+    'tags' => [
+        'div' => [
+            'blocked_classes' => ['float'],
+        ],
+    ],
+]);
+```
+
+## Configuring childless tags
+
+The core extensions by default sets the `area`, `base`, `br`, `col`, `img`, `input`, `hr`, `link`, `meta`,
+`param`, `track`,  `wbr` tags as childless tags, which mean you usually won't need to change them.
+However, if you want to customize which tags are childless, you can use a tag-specific configuration for them. 
+
+For instance, you can use the following configuration:
+
+```php
+$sanitizer = HtmlSanitizer\Sanitizer::create([
+    'extensions' => ['html5'],
+    'tags' => [
+        'hr' => [
+            'childless' => true,
+        ],
+    ],
+]);
+```
+
+## Converting tags
+
+There may be an instance where you want to prevent the use of a deprecated tag that may have been
+superseded by another tag.
+
+For instance, to convert `b` tags to `strong` tags, you can use the following configuration:
+
+```php
+$sanitizer = HtmlSanitizer\Sanitizer::create([
+    'extensions' => ['html5'],
+    'tags' => [
+        'strong' => [
+            'convert_elements' => ['b'],
         ],
     ],
 ]);