a-blog cms PHP API Reference

Helper
in package

Table of Contents

Constants

UNTRUSTED_ALLOWED_ELEMENTS  = ['iframe', 'script', 'blockquote', 'a', 'p', 'span', 'img', 'br', 'div', 'section']
信頼できない HTML で許可する要素。
UNTRUSTED_DEFINITION_ID  = 'acms-untrusted-html-purifier'
信頼できない HTML 用のカスタム定義を識別する ID。

Properties

$cacheDir  : string
キャッシュディレクトリのパス
$htmlPurifier  : HTMLPurifier
HTMLPurifierのインスタンス
$untrustedHtmlPurifier  : HTMLPurifier|null
信頼できない HTML 用の HTMLPurifier のインスタンス

Methods

__construct()  : mixed
clean()  : string
HTMLをクリーンアップする
cleanUntrusted()  : string
信頼できない HTML（外部プロバイダの oEmbed 応答など）をクリーンアップする。
clearCache()  : void
HTMLPurifierのキャッシュをクリアする
codeEscape()  : string
HTMLの<pre><code>内のコードをエスケープする
dispatchConfigHook()  : void
HTMLPurifier の config 拡張フックを発火する。
dispatchDefinitionHook()  : void
HTMLPurifier のカスタム HTML 定義拡張フックを発火する。

Constants

UNTRUSTED_ALLOWED_ELEMENTS

信頼できない HTML で許可する要素。

private array<string|int, string> UNTRUSTED_ALLOWED_ELEMENTS = ['iframe', 'script', 'blockquote', 'a', 'p', 'span', 'img', 'br', 'div', 'section']

埋め込み（oEmbed 応答）の描画に必要な最小限。各要素の属性検証は PurifierFactory 側の定義（Enum / Bool / CDATA + iframe は IframePolicyTransform、 script は ScriptPolicyTransform）をそのまま使い、ここで絞るのは要素の可否のみ。

script を含むのは、X / Instagram / Threads のように blockquote + script 形式で埋め込みを 返すプロバイダーがあるため。要素として許すだけで、実際に読み込める src は許可ホストの whitelist（html_purifier_script_allowed_hosts）が決め、インライン JS は常に落ちる。

section を含むのは、TikTok が blockquote の中を section で包んで返すため。許可しないと Core.EscapeInvalidTags により <section> が本文に文字のまま出る。div と同じ構造要素で、 属性は Common の範囲に限られる。

UNTRUSTED_DEFINITION_ID

信頼できない HTML 用のカスタム定義を識別する ID。

private mixed UNTRUSTED_DEFINITION_ID = 'acms-untrusted-html-purifier'

PurifierFactory 既定の ID（'acms-html-purifier'）と分けることで、同じキャッシュ ディレクトリに置いても定義キャッシュが混ざらない。

Properties

$cacheDir

キャッシュディレクトリのパス

protected string $cacheDir = ''

$htmlPurifier

HTMLPurifierのインスタンス

protected HTMLPurifier $htmlPurifier

$untrustedHtmlPurifier

信頼できない HTML 用の HTMLPurifier のインスタンス

private HTMLPurifier|null $untrustedHtmlPurifier = null

Why not コンストラクタで組み立てないか: 外部由来 HTML のサニタイズは埋め込みの保存時 などに限られ、大半のリクエストでは使われない。常時 2 つ構築するのは無駄なので、 cleanUntrusted() が最初に呼ばれたときだけ組み立てる。

Methods

__construct()

public __construct() : mixed

clean()

HTMLをクリーンアップする

public clean(string|array<string|int, mixed> $html) : string
Parameters
$html : string|array<string|int, mixed>
Return values
string

cleanUntrusted()

信頼できない HTML（外部プロバイダの oEmbed 応答など）をクリーンアップする。

public cleanUntrusted(string $html) : string

clean() は管理画面で制作者・編集者が書いた HTML を通す前提で HTML.Trusted / CSS.Trusted / CSS.AllowTricky を有効にしている。外部から取得した HTML はその信頼を 前提にできない（position:fixed の全面オーバーレイのような UI 覆い被せに使われうる）ため、 Trusted 系を無効化し、許可要素も必要最小限へ絞った別インスタンスを通す。

iframe / script の許可ホスト（config の html_purifier_iframe_allowed_hosts / html_purifier_script_allowed_hosts）は clean() と同じ IframePolicy / ScriptPolicy をそのまま使い、単一の情報源を保つ。

Why not clean() と同じ前処理（codeEscape / html_entity_decode）を通さないか: あれは 編集者が本文に書いたコード表示（pre > code）を保護するための処理で、外部から取得した 埋め込み HTML には該当しない。エンティティを復号すると、提供元がエスケープ済みで返した 文字列を live なタグへ戻してしまう危険もある。

Parameters
$html : string
Return values
string

clearCache()

HTMLPurifierのキャッシュをクリアする

public clearCache() : void

用途（信頼済み / 信頼できない）ごとにキャッシュディレクトリを分けると、用途が増えるたびに 呼び出し元（ACMS_POST_Cache / Engine）へクリア処理を 足す必要が出て漏れる。定義の分離は HTML.DefinitionID に任せ、置き場所はこの 1 つに保つ ことで、クリアの入口もこのメソッド 1 つに保つ。

削除後にベースディレクトリを作り直す。PurifierFactory が設定した Cache.SerializerPath は リクエスト内で生存し続けるため、作り直さないと同一リクエスト内の後続 clean() で HTMLPurifier の定義キャッシュ書き込みがベースディレクトリ不在エラーになる。

codeEscape()

HTMLの<pre><code>内のコードをエスケープする

protected codeEscape(string $html) : string
Parameters
$html : string
Return values
string

dispatchConfigHook()

HTMLPurifier の config 拡張フックを発火する。

private dispatchConfigHook(HTMLPurifier_Config $config) : void

フック発火（グローバルな HookFactory へのアクセス）を本クラスの private に閉じ、 PurifierFactory 側はコールバックを受け取るだけにすることで、Factory の単体テスト可能性を保つ。 Hook 無効時（HOOK_ENABLE が未定義 / false）は何もしない。

Parameters
$config : HTMLPurifier_Config

カスタム HTML 定義の取得前の config

dispatchDefinitionHook()

HTMLPurifier のカスタム HTML 定義拡張フックを発火する。

private dispatchDefinitionHook(HTMLPurifier_HTMLDefinition $def, HTMLPurifier_Config $config) : void
Parameters
$def : HTMLPurifier_HTMLDefinition

カスタム HTML 定義（addAttribute / addElement で拡張する）

$config : HTMLPurifier_Config

取得済みの config


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results