README

ExerciseHTMLPurifierBundle

此包将 HTMLPurifier 集成到 Symfony。

安装

安装包

$ composer require exercise/htmlpurifier-bundle

配置

如果您没有明确配置此包，将定义一个名为 exercise_html_purifier.default 的 HTMLPurifier 服务。这种行为与您指定以下配置相同

# 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

默认配置是特殊的，它总是定义，并且其配置由所有自定义配置继承。 exercise_html_purifier.default 是使用基本配置的默认服务。

# 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'

在此示例中，还将定义一个名为 exercise_html_purifier.custom 的服务，它包括缓存、编码、HTML 标签和属性选项。可在 HTMLPurifier 的配置文档中找到可用的配置选项。

注意：如果您定义了默认配置但省略了 Cache.SerializerPath，它将默认为上述路径。您可以通过指定 null 选项值来抑制默认路径。

自动装配

默认情况下，在您的服务中类型提示 \HtmlPurifier 将自动装配 exercise_html_purifier.default 服务。要覆盖它并使用自己的配置作为默认自动装配服务，请添加以下配置

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

使用自定义清理类作为默认

如果您想使用自己的类作为默认清理器，请按以下方式定义新别名

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

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

参数绑定

此包还利用每个配置文件的别名参数绑定。因此，以下配置

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

将注册以下绑定

 // 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

表单类型扩展

此包提供了一种表单类型扩展，用于使用 HTMLPurifier 过滤表单字段。净化是在 PRE_SUBMIT 事件早期进行的，这意味着客户端数据将在绑定到表单之前被过滤。

所有基于 TextType 的类型（例如：TextareaType）都自动提供以下选项

<?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'])
            // ...
        ;
    }
    
    // ...
}

所有扩展 TextType 的类型（即：TextareaType）继承这些选项。这也意味着如果您使用类似 CKEditorType 的类型，您将受益于这些选项而无需进行任何配置。

Twig 过滤器

此包在 Twig 中注册了一个名为 purify 的过滤器。此过滤器的输出标记为 HTML 安全，类似于 Twig 内置的转义器。以下是如何使用此过滤器

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

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

清理器注册表

默认情况下，将 Exercise\HtmlPurifierBundle\HtmlPurifiersRegistry 类注册为服务。要添加您的自定义清理器实例，并通过其配置文件名使其可用于表单类型和 Twig 扩展，请使用以下标签 exercise.html_purifier

# config/services.yaml

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

现在您可以在以下情况下使用清理器

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

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

如何自定义配置定义

白名单属性

在某些情况下，您可能希望为特定标签设置一些规则。以下配置就是这样做的

# 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

有关更多选项，请参阅 HTMLPurifier_AttrTypes

白名单元素

在某些情况下，您可能希望为特定标签设置一些规则。以下配置就是这样做的

# 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

与以下配置等价

$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];

有关更多详细信息，请参阅 HTMLPurifier 文档

空白元素

可能需要删除标签上的所有属性。只需将其添加到列表中即可。

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

如何重用配置文件

真正方便的是可以重用一些配置文件定义来构建其他自定义定义。

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

在这个例子中，名为 "all" 的配置文件将继承 "default" 配置文件，然后是两个自定义配置文件。顺序很重要，因为每个配置文件会覆盖前一个，"all" 也可以定义自己的规则。

贡献

欢迎提交 PR（Pull Requests）：）。请针对 4.x 分支提交错误修复，针对 master 分支提交新功能。

exercise / htmlpurifier-bundle

维护者

详情