README

ExerciseHTMLPurifierBundle

此扩展包将 HTMLPurifier 整合到 Symfony 中。

安装

Symfony 3.4 及以上版本（使用 Composer）

在您的 composer.json 文件中要求此包

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

安装此包

$ composer require exercise/htmlpurifier-bundle

在 Symfony 3 中注册此包

// app/AppKernel.php

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

Symfony 3 的配置

配置与以下部分相同，但路径应为 app/config.yml。

Symfony 4 及以上版本的配置

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

# config/packages/exercise_html_purifier.yaml

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

default 配置文件是特殊的，它始终被定义，其配置被所有自定义配置文件继承。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 的配置文档中找到。

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

自动装配

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

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

使用自定义 Purifier 类作为默认

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

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

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

参数绑定（Symfony >= 4.4）

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

    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 的类型都自动提供了两个选项

<?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 内置的 escapers。该过滤器可以按以下方式使用：

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

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

Purifiers 注册表

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

# config/services.yaml

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

现在您可以在以下情况下使用您的 purifier：

// 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）。请针对 2.0 分支进行错误修复，针对 master 分支进行新功能开发。

short-edition / htmlpurifier-bundle

维护者

详细信息