, (*1)
ExerciseHTMLPurifierBundle
This bundle integrates HTMLPurifier into Symfony., (*2)
Installation
Install the bundle:, (*3)
$ composer require exercise/htmlpurifier-bundle
Configuration
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:, (*4)
# config/packages/exercise_html_purifier.yaml
exercise_html_purifier:
default_cache_serializer_path: '%kernel.cache_dir%/htmlpurifier'
# 493 int => ocl "0755"
default_cache_serializer_permissions: 493
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., (*5)
# config/packages/exercise_html_purifier.yaml
exercise_html_purifier:
default_cache_serializer_path: '%kernel.cache_dir%/htmlpurifier'
html_profiles:
custom:
config:
Core.Encoding: 'ISO-8859-1'
HTML.Allowed: 'a[href|target],p,br'
Attr.AllowedFrameTargets: '_blank'
In this example, a exercise_html_purifier.custom service will also be defined,
which includes cache, encoding, HTML tags and attributes options. Available configuration
options may be found in HTMLPurifier's configuration documentation., (*6)
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., (*7)
Autowiring
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 configuration:, (*8)
# config/services.yaml
services:
#...
exercise_html_purifier.default: '@exercise_html_purifier.custom'
Using a custom purifier class as default
If you want to use your own class as default purifier, define the new alias as
below:, (*9)
# config/services.yaml
services:
# ...
exercise_html_purifier.default: '@App\Html\CustomHtmlPurifier'
Argument binding
The bundle also leverages the alias argument binding for each profile. So the
following config:, (*10)
html_profiles:
blog:
# ...
gallery:
# ...
will register the following binding:, (*11)
// 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 early during the PRE_SUBMIT event, which
means that client data will be filtered before being bound to the form., (*12)
Two options are automatically available in all TextType based types:, (*13)
<?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., (*14)
Twig Filter
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:, (*15)
{# Filters text's value through the "default" HTMLPurifier service #}
{{ text|purify }}
{# Filters text's value through the "custom" HTMLPurifier service #}
{{ text|purify('custom') }}
Purifiers Registry
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:, (*16)
# config/services.yaml
services:
# ...
App\HtmlPurifier\CustomPurifier:
tags:
- name: exercise.html_purifier
profile: custom
Now your purifier can be used when:, (*17)
// In a form type
$builder
->add('content', TextareaType::class, [
'purify_html' => true,
'purify_html_profile' => 'custom',
])
// ...
{# in a template #}
{{ html_string|purify('custom') }}
How to Customize a Config Definition
Whitelist Attributes
In some case, you might want to set some rules for a specific tag.
This is what the following config is about:, (*18)
# 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., (*19)
Whitelist Elements
In some case, you might want to set some rules for a specific tag.
This is what the following config is about:, (*20)
# 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:, (*21)
$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., (*22)
Blank Elements
It might happen that you need a tag clean from any attributes.
Then just add it to the list:, (*23)
# config/packages/exercise_html_purifier.yaml
exercise_html_purifier:
html_profiles:
default:
# ...
blank_elements: [legend, figcaption]
How to Reuse Profiles
What can really convenient is to reuse some profile definition
to build other custom definitions., (*24)
# 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., (*25)
Contributing
PRs are welcomed :). Please target the 4.x branch for bug fixes and master
for new features., (*26)
Wallogit.com
