Developed with love by KnpLabs Hire us for your project!
61

html-sanitizer-bundle

by tgalopin

Sanitize untrustworthy HTML user input (Symfony integration for https://github.com/tgalopin/html-sanitizer)

html-sanitizer-bundle

Build Status

SymfonyInsight

html-sanitizer
is a library aiming at handling, cleaning and sanitizing HTML sent by external users
(who you cannot trust), allowing you to store it and display it safely. It has sensible defaults
to provide a great developer experience while still being entierely configurable.

This repository is a Symfony bundle integrating the html-sanitizer
library into Symfony applications. It provides helpful tools on top of the sanitizer to easily use it in Symfony.

Installation

html-sanitizer-bundle requires PHP 7.1+ and Symfony 3.4+.

You can install the bundle using Symfony Flex:

composer require tgalopin/html-sanitizer-bundle

Configuration

You can configure the bundle using the html_sanitizer configuration section:

# config/packages/html_sanitizer.yaml

html_sanitizer:
    default_sanitizer: 'default'
    sanitizers:
        default:
            extensions: ['basic', 'image', 'list']
            tags:
                img:
                    allowed_hosts: ['127.0.0.1', 'mywebsite.com', 'youtube.com']
                    force_https: true
        admin_content:
            extensions: ['basic', 'image', 'list']

As you see, you can have multiple sanitizers available at the same time in your application.
Have a look at the library documentation to learn all the available
configuration options for the sanitizers themselves.

Usage in services

This bundle provides the configured sanitizer for autowiring using the interface
HtmlSanitizer\SanitizerInterface. This autowiring will target the default sanitizer defined
in the bundle configuration.

This means that if you are using autowiring, you can simply typehint SanitizerInterface in any
of your services to get the default sanitizer:

use HtmlSanitizer\SanitizerInterface;

class MyService
{
    private $sanitizer;

    public function __construct(SanitizerInterface $sanitizer)
    {
        $this->sanitizer = $sanitizer;
    }

    // ...
}

The same goes for controllers:

use HtmlSanitizer\SanitizerInterface;

class MyController
{
    public function index(SanitizerInterface $sanitizer)
    {
        // ...
    }
}

If you are not using autowiring, you can inject the html_sanitizer service into your services
manually to get the default sanitizer.

If you need to access other sanitizers than the default one in your services, you can either:

  1. inject a specific sanitizer by injecting it with your services configuration as
    html_sanitizer.<santizer-name> (for instance, html_sanitizer.admin_content) ;

  2. use the sanitizers registry by injecting it with your services configuration as
    html_sanitizer.registry. It is a service locator mapping all the sanitizers available:

use Psr\Container\ContainerInterface;

class MyService
{
    public function __construct(ContainerInterface $sanitizers)
    {
        // $sanitizers->get('admin_content') ...
    }
}

Usage in forms

This applies only if you have installed the Symfony Form component.

The main usage of the html-sanitizer is in combination with forms. This bundle provides a TextType extension
which allows you to automatically sanitize HTML of any text field or any field based on the TextType
(TextareaType, SearchType, etc.).

To use it in any of your forms, you can use the sanitize_html option:

class MyFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('content', TextareaType::class, ['sanitize_html' => true])
        ;
    }
}

To use a different sanitizer than the default one, use the sanitizer option:

class MyFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('content', TextareaType::class, ['sanitize_html' => true, 'sanitizer' => 'admin_content'])
        ;
    }
}

Usage in Twig

This applies only if you have installed the Twig bundle.

A sanitize_html Twig filter is provided through an extension, letting you filter HTML inside your views.

<div>
    {{ html|sanitize_html }}
</div>

To use a different sanitizer than the default one, add an argument to the filter:

<div>
    {{ html|sanitize_html('admin_content') }}
</div>

Registering an extension

If you use autoconfiguration, classes implementing the HtmlSanitizer\Extension\ExtensionInterface interface
will be automatically registered and you can use them in your sanitizer configuration:

html_sanitizer:
    default_sanitizer: 'default'
    sanitizers:
        default:
            extensions: ['basic', 'my-extension']

If you don't use autoconfiguration, you need to register your extension as a service tagged html_sanitizer.extension:

services:
    app.sanitizer.my_extension:
        class: 'App\Sanitizer\MyExtension'
        tags: [{ name: 'html_sanitizer.extension' }]

Security Issues

If you discover a security vulnerability within the sanitizer bundle or library, please follow
our disclosure procedure.

Backward Compatibility promise

This library follows the same Backward Compatibility promise as the Symfony framework:
https://symfony.com/doc/current/contributing/code/bc.html

Note: many classes in this library are either marked @final or @internal.
@internal classes are excluded from any Backward Compatiblity promise (you should not use them in your code)
whereas @final classes can be used but should not be extended (use composition instead).

Copyright (c) 2018 Titouan Galopin

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
  • Merge pull request #15 from tgalopin/add-sf5-support
    By web-flow, 8 months ago
  • Add TravisCI config for Symfony 5
    By tgalopin, 8 months ago
  • Allow Symfony 5 components
    By tgalopin, 8 months ago
  • Merge pull request #12 from yceruto/patch-1
    By web-flow, 1 year ago
  • Fix compatibility with Symfony 5.0
    By yceruto, 1 year ago
  • Test the bundle with Symfony 4.2, 4.3 and dev-master in Travis (#13)
    By web-flow, 1 year ago
  • Fix the handling of the html_sanitizer service for the main serializer (#10)
    By tgalopin, 1 year ago
  • Fix custom extension wiring (#9)
    By web-flow, 1 year ago
  • Fix some deprecations (#5)
    By tgalopin, 1 year ago
  • Merge pull request #4 from tgalopin/logger
    By web-flow, 1 year ago
  • Upgrade library min
    By tgalopin, 1 year ago
  • Add logging feature
    By tgalopin, 1 year ago
  • Set Configuration as internal
    By tgalopin, 1 year ago
  • Merge pull request #3 from tgalopin/travis-cs
    By web-flow, 1 year ago
  • Add PHP-CS-Fixer and improve TravisCI configuration
    By tgalopin, 1 year ago
  • Fix typo in README
    By tgalopin, 1 year ago
  • Upgrade library version
    By tgalopin, 1 year ago
  • Bump library version
    By tgalopin, 1 year ago
  • Remove beta status
    By tgalopin, 1 year ago
  • Add Backward Compatibility promise
    By tgalopin, 1 year ago
  • Upgrade library version
    By tgalopin, 1 year ago
  • Allow multiple sanitizers
    By tgalopin, 1 year ago
  • Fix typo in README
    By tgalopin, 1 year ago
  • Add warning
    By tgalopin, 1 year ago
  • Add link to extension section in README
    By tgalopin, 1 year ago
  • Update dependencies and improve documentation
    By tgalopin, 1 year ago
  • Merge pull request #2 from tgalopin/use-lib-pre-release
    By web-flow, 1 year ago
  • Use library first pre-release
    By tgalopin, 1 year ago
  • Merge pull request #1 from tgalopin/tests-and-travis
    By web-flow, 1 year ago
  • Add Travis
    By tgalopin, 1 year ago