README

Soflomo\Purifier 是 Zend Framework 的 HTMLPurifier 集成。

它提供了一个 Zend\Filter\FilterInterface 实现，因此您可以在您的 Zend\InputFilter 类中使用 HTMLPurifier。此外，还提供了一个视图助手，以帮助在视图脚本中即时净化 HTML。

安装

您可以通过 Composer 安装 Soflomo\Purifier。

$: composer require soflomo/purifier

要启用 ZF2 应用程序中的模块，请将 Soflomo\Purifier 添加到 config/application.config.php 中已启用的模块列表中。

使用方法

在您的输入过滤器配置中，使用 htmlpurifier 作为过滤器规范中的 name。

一个示例 Form

class MyForm extends Zend\Form\Form implements Zend\InputFilter\InputFilterProviderInterface
{
    public function init()
    {
        $this->add([
            'name'    => 'text',
            'options' => [
                'label' => 'Text'
            ],
            'attributes' => [
                'type' => 'textarea',
            ],
        ]);
    }

    public function getInputFilterSpecification()
    {
        return [
            'text'  => [
                'required' => true,
                'filters'  => [
                    [ 'name' => 'stringtrim' ],
                    [ 'name' => 'htmlpurifier' ],
                ],
            ],
        ];
    }
}

或 InputFilter

class MyInputFilter extends Zend\InputFilter\InputFilter
{
    public function init()
    {
        $this->add([
            'name'     => 'text',
            'required' => true,
            'filters'  => [
                [ 'name' => 'stringtrim' ],
                [ 'name' => 'htmlpurifier' ],
            ],
        ]);
    }
}

或者，您可以使用 FQCN Soflomo\Purifier\PurifierFilter 替代 htmlpurifier 别名。

如果您从各自的插件管理器中提取消费者，则应该可以直接使用。如果不是这样，请阅读 如何注入过滤器插件管理器。

如果您出于某种原因想在视图模板中使用过滤器，您还可以使用视图助手。请注意，HTMLPurifier 并不是一个很快的库，因此每次请求进行过滤都可能成为性能瓶颈。建议使用缓存机制来缓存过滤后的 HTML 输出。视图助手可在 htmlPurifier 键下使用。

<?php echo $this->htmlPurifier()->purify($foo->getText()) ?>

还有一个简写可用

<?php echo $this->htmlPurifier($foo->getText()) ?>

配置 HTMLPurifier

HTMLPurifier 使用类 HTMLPurifier_Config 来配置其规则。大多数配置规则基于键/值对：$config->set('HTML.Doctype', 'HTML 4.01 Transitional')。

全局配置

HTMLPurifier_Config 键/值存储由 Soflomo\Purifier 以关联数组的形式暴露给 ZF2 配置，因此您可以像这样自定义默认的 HTMLPurifier_Config 实例

return [
    'soflomo_purifier' => [
        'config' => [
            'HTML.Doctype' => 'HTML 4.01 Transitional'
        ],
    ],
];

配置工厂还处理一个 definitions 子数组，以向净化器添加自定义定义，如此处所述。

例如

return [
    'soflomo_purifier' => [
        'config' => [
            'HTML.DefinitionID' => 'my custom definitions',
        ], 
        'definitions' => [
            'HTML' => [
                'addAttribute' => [
                    [ 'a', 'target', 'Enum#_blank,_self,_target,_top' ]
                ],
            ],
        ],
    ],
];

这将添加一个针对 target 属性的 a 元素的 HTMLPurifier_AttrDef_Enum 定义。请注意，需要为 HTML.DefinitionID 配置键提供一个任意值才能正确加载定义。

也可以在配置数组的 definitions 键下设置定义。这些将覆盖 soflomo_purifier 数组中的键。

实例配置

您还可以使用通常的 options 键设置使用规范添加过滤器时的不同配置。

class MyInputFilter extends Zend\InputFilter\InputFilter
{
    public function init()
    {
        $this->add([
            'name'     => 'text',
            'required' => true,
            'filters'  => [
                [ 'name' => 'stringtrim' ],
                [
                    'name' => 'htmlpurifier',
                    'options' => [
                        'config' => [
                            'HTML.AllowedElements' => 'a, span',
                            'HTML.DefinitionID' => 'my custom definitions',
                        ], 
                        'definitions' => [
                            'HTML' => [
                                'addAttribute' => [
                                    [ 'a', 'target', 'Enum#_blank,_self,_target,_top' ]
                                ],
                            ],
                        ],
                    ],
                ],
            ],
        ]);
    }
}

注入 FilterManager

如果您使用 new 关键字手动实例化表单或输入过滤器，而不是从各自的插件管理器（即 FormElementManager 和 InputFilterManager）中提取它们，则 FilterManager 不会自动注入到它们的工厂中，它们将回退到使用默认的一个。

因此，您会得到一个 ServiceNotFoundException: Zend\Filter\FilterPluginManager::get was unable to fetch or create an instance for htmlpurifier。这意味着过滤器插件管理器是延迟实例化的，并且不知道 htmlpurifier 插件。

您可以通过手动执行初始化器来解决这个问题。

$form = new MyForm();
$formElementManager = $serviceManager->get('FormElementManager');
$formElementManager->injectFactory($form);

// same goes for input filters
$inputFilter = new MyInputFilter();
$inputFilterManager = $serviceManager->get('InputFilterManager');
$inputFilterManager->populateFactory($inputFilter);

然而，强烈建议从各自的插件管理器中提取表单和输入过滤器，并在适用的情况下使用 init() 方法（该方法将在所有工厂注入后调用）。

性能优化

HTMLPurifier 不是一个最快的库。它使用大量的类和文件，因此自动加载可能会变得繁琐。

幸运的是，你可以创建 HTMLPurifier 类的独立版本（请点击此处），其中单个文件包含大部分类。

vendor/bin/purifier-generate-standalone 中的脚本为您生成此文件。独立文件创建在 vendor/ezyang/htmlpurifier/library 内，所以请确保您可以在该目录中写入。

Soflomo\Purifier 通过配置选项 soflomo_purifier.standalone 帮助您使用此独立版本。

例如，您可以在 config/autoload/local.php 中添加以下内容

return [
    'soflomo_purifier' => [
        'standalone' => true,
    ],
];

如果您想将独立文件放置在其他位置，也可以设置其路径

return [
    'soflomo_purifier' => [
        'standalone'      => true,
        'standalone_path' => 'path/to/HTMLPurifier.standalone.php',
    ],
];

注意：由于特定版本的 HTMLPurifier 版本 4.7.0 中存在上游 BC 断裂，独立生成器脚本将无法使用。请参阅 htmlpurifier #65。