This bundle integrates HTMLPurifier into Symfony.

Require the bundle in your composer.json file:

{
    "require": {
        "exercise/htmlpurifier-bundle": "*"
    }
}

Install the bundle:

$ composer require exercise/htmlpurifier-bundle

Register the bundle in Symfony 3:

// app/AppKernel.php

public function registerBundles()
{
    return [
        // ...
        new Exercise\HTMLPurifierBundle\ExerciseHTMLPurifierBundle(),
    ];
}

If you do not explicitly configure this bundle, an HTMLPurifier service will be defined as exercise_html_purifier.default. This behavior is the same as if you had specified the following configuration:

# app/config.yml

exercise_html_purifier:
    default_cache_serializer_path: '%kernel.cache_dir%/htmlpurifier'

The default profile is special in that it is used as the configuration for the exercise_html_purifier.default service as well as the base configuration for other profiles you might define.

# app/config.yml

exercise_html_purifier:
    default_cache_serializer_path: '%kernel.cache_dir%/htmlpurifier'
    html_profiles:
        custom:
            config:
                Core.Encoding: 'ISO-8859-1'

In this example, a exercise_html_purifier.custom service will also be defined, which includes both the cache and encoding options. Available configuration options may be found in HTMLPurifier's configuration documentation.

Note: If you define a default profile but omit Cache.SerializerPath, it will still default to the path above. You can specify a value of null for the option to suppress the default path.

If you do not explicitly configure this bundle, an HTMLPurifier service will be defined as exercise_html_purifier.default. This behavior is the same as if you had specified the following configuration:

# config/packages/exercise_html_purifier.yaml

exercise_html_purifier:
    default_cache_serializer_path: '%kernel.cache_dir%/htmlpurifier'

The default profile is special, it is always defined and its configuration is inherited by all custom profiles. exercise_html_purifier.default is the default service using the base configuration.

# config/packages/exercise_html_purifier.yaml

exercise_html_purifier:
    default_cache_serializer_path: 'tmp/htmlpurifier'
    html_profiles:
        default:
            config:
                Cache.SerializerPermissions: 777 
        custom:
            config:
                Core.Encoding: 'ISO-8859-1'

By default type hinting \HtmlPurifier in your services will autowire the exercise_html_purifier.default service. To override it and use your own config as default autowired services just add this in you app/config/services.yml in you use symfony 3 or config/services.yaml if you use symfony 4:

# config/services.yaml
services:
    #...
    
    exercise_html_purifier.default: '@exercise_html_purifier.custom'

If you want to use your own class as default purifier, define a new alias:

# config/services.yaml
services:
    # ...

    exercise_html_purifier.default: '@App\Html\CustomHtmlPurifier'

In such case, the custom purifier will use its own defined configuration, ignoring the bundle configuration.

The bundle also leverages the alias argument binding for each profile. So the following config:

    html_profiles:
        blog:
            # ...
        gallery:
            # ...

will register the following binding:

 // default config is bound whichever argument name is used
public function __construct(\HTMLPurifier $purifier) {}
public function __construct(\HTMLPurifier $htmlPurifier) {}
public function __construct(\HTMLPurifier $blogPurifier) {} // blog config
public function __construct(\HTMLPurifier $galleryPurifier) {} // gallery config

This bundles provides a form type extension for filtering form fields with HTMLPurifier. Purification is done during the PRE_SUBMIT event, which means that client data will be filtered before binding to the form.

The following example demonstrates one possible way to integrate an HTMLPurifier transformer into a form by way of a custom field type:

<?php

namespace App\Form\Type;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\Extension\Core\Type\TextareaType;
use Symfony\Component\Form\FormBuilderInterface;

class ArticleType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('content', TextareaType::class, ['purify_html' => true]) // will use default profile 
            ->add('sneek_peak', TextType::class, ['purify_html' => true, 'purify_html_profile' => 'sneak_peak'])
            // ...
        ;
    }
    
    // ...
}

Every type extending TextType (i.e: TextareaType) inherit these options. It also means that if you use a type such as CKEditorType, you will benefit from these options without configuring anything.

This bundles registers a purify filter with Twig. Output from this filter is marked safe for HTML, much like Twig's built-in escapers. The filter may be used as follows:

{# Filters text's value through the "default" HTMLPurifier service #}
{{ text|purify }}

{# Filters text's value through the "custom" HTMLPurifier service #}
{{ text|purify('custom') }}

A Exercise\HtmlPurifierBundle\HtmlPurifiersRegistry class is registered by default as a service. To add your custom instance of purifier, and make it available to the form type and Twig extensions through its profile name, you can use the tag exercise.html_purifier as follow:

# config/services.yaml

services:
    # ...
    
    App\HtmlPurifier\CustomPurifier:
        tags:
            - name: exercise.html_purifier
              profile: custom

Now your purifier can be used when:

// In a form type
$builder
    ->add('content', TextareaType::class, [
        'purify_html' => true,
        'purify_html_profile' => 'custom',
    ])
    // ...

{# in a template #}
{{ html_string|purify('custom') }}

In some case, you might want to set some rules for a specific tag. This is what the following config is about:

# config/packages/exercise_html_purifier.yaml
exercise_html_purifier:
    html_profiles:
        default:
            config:
                HTML.Allowed: <
                    *[id|class|name],
                    a[href|title|rel|target],
                    img[src|alt|height|width],
                    br,div,embed,object,u,em,ul,ol,li,strong,span
            attributes:
                img:
                    # attribute name, type (Integer, Color, ...)
                    data-id: ID
                    data-image-size: Text
                span:
                    data-link: URI

See HTMLPurifier_AttrTypes for more options.

In some case, you might want to set some rules for a specific tag. This is what the following config is about:

# config/packages/exercise_html_purifier.yaml
exercise_html_purifier:
    html_profiles:
        default:
            # ...
            elements:
                video:
                    - Block
                    - 'Optional: (source, Flow) | (Flow, source) | Flow'
                    - Common # allows a set of common attributes
                    # The 4th and 5th arguments are optional
                    - src: URI # list of type rules by attributes
                      type: Text
                      width: Length
                      height: Length
                      poster: URI
                      preload: 'Enum#auto,metadata,none'
                      controls: Bool
                source:
                    - Block
                    - Flow
                    - Common
                    - { src: URI, type: Text }
                    - [style] # list of forbidden attributes

Would be equivalent to:

$def = $config->getHTMLDefintion(true);
$def->addElement('video', 'Block', 'Optional: (source, Flow) | (Flow, source) | Flow', 'Common', [
    'src' => 'URI',
    'type' => 'Text',
    'width' => 'Length',
    'height' => 'Length',
    'poster' => 'URI',
    'preload' => 'Enum#auto,metadata,none',
    'controls' => 'Bool',
]);
$source = $def->addElement('source', 'Block', 'Flow', 'Common', [
    'src' => 'URI',
    'type' => 'Text',
]);
$source->excludes = ['style' => true];

See HTMLPurifier documentation for more details.

It might happen that you need a tag clean from any attributes. Then just add it to the list:

# config/packages/exercise_html_purifier.yaml
exercise_html_purifier:
    html_profiles:
        default:
            # ...
            blank_elements: [legend, figcaption]

What can really convenient is to reuse some profile definition to build other custom definitions.

# config/packages/exercise_html_purifier.yaml
exercise_html_purifier:
    html_profiles:
        base:
            # ...
        video:
            # ...
        all:
            parents: [base, video]

In this example the profile named "all" will inherit the "default" profile, then the two custom ones. The order is important as each profile overrides the previous, and "all" could define its own rules too.

PRs are welcomed :). Please target the 2.0 branch for bug fixes and master for new features.