PHP HTMLPurifier 詳細教學：安全過濾 HTML 內容的最佳實踐

HTMLPurifier 是 PHP 專案中標準的 HTML 過濾庫，能有效防止 XSS 攻擊，確保輸出符合標準。本文詳解安裝、配置與進階用法。

安裝與基本引入

下載後核心在 library 目錄，有兩種引入方式：

// 方式一：自動載入器 (官方推薦)
require_once 'HTMLPurifier.auto.php';
$config = HTMLPurifier_Config::createDefault();

// 方式二：手動引入
require_once 'HTMLPurifier.includes.php';
require_once 'HTMLPurifier.autoload.php';
$config = HTMLPurifier_Config::createDefault();

核心配置選項

官方配置文檔：configdoc

$config->set('HTML.AllowedElements', ['div'=>true, 'table'=>true, 'tr'=>true, 'td'=>true, 'br'=>true]);
$config->set('HTML.Doctype', 'XHTML 1.0 Transitional'); // 文檔類型
$config->set('Core.Encoding', 'UTF-8'); // 字元編碼

基本使用流程

$purifier = new HTMLPurifier($config);
$clean_html = $purifier->purify($dirty_html);

進階：封裝為可複用類別 (Zend Framework 風格)

<?php
require_once 'HTMLPurifier.includes.php';
require_once 'HTMLPurifier.autoload.php';

class Resume_HtmlPurifier implements Zend_Filter_Interface {
    protected $_htmlPurifier = null;

    public function __construct($options = null) {
        $config = HTMLPurifier_Config::createDefault();
        $config->set('Core.Encoding', 'UTF-8');
        $config->set('HTML.Doctype', 'XHTML 1.0 Transitional');
        
        if (!is_null($options)) {
            foreach ($options as $option) {
                // $option = [directive, value, scope?]
                $config->set($option[0], $option[1], $option[2] ?? null);
            }
        }
        $this->_htmlPurifier = new HTMLPurifier($config);
    }

    public function filter($value) {
        return $this->_htmlPurifier->purify($value);
    }
}

配置陣列範例

$conf = [
    ['HTML.AllowedElements', ['div'=>true, 'table'=>true, 'tr'=>true, 'td'=>true, 'br'=>true], false],
    ['HTML.AllowedAttributes', ['class'=>true], false],
    ['Attr.ForbiddenClasses', ['resume_p'=>true], false],
    ['AutoFormat.RemoveEmpty', true, false],
    ['AutoFormat.RemoveEmpty.RemoveNbsp', true, false],
    ['URI.Disable', true, false], // 禁用連結
];

// 使用
$p = new Resume_HtmlPurifier($conf);
$clean_html = $p->filter($html);

常用配置指令速查

效能優化建議

• 配置物件 HTMLPurifier_Config 可重複使用，避免重複建立
• 啟用 Cache.DefinitionImpl 快取定義檔
• 大量處理時重複使用 HTMLPurifier 實例