a-blog cms PHP API Reference

Helper
in package

Table of Contents

Constants

FUNCTION_TAG_TOKEN_PREFIX  = 'acms-fn-tag:'
展開前の機能タグを置き換えるトークン（コメントノードの本文）の接頭辞

Properties

$authoring  : AuthoringConverter
入稿用タグの変換器
$functionTags  : FunctionTagRegistry
機能タグの展開ハンドラ
$lightboxClass  : string
Lightboxクラス名
$resizeImageSize  : int
画像リサイズの幅

Methods

__construct()  : mixed
extractMediaId()  : array<string|int, int>
メディアIDを抽出する
fix()  : string
ブロックエディターのHTMLを修正する
fixMediaId()  : string
メディアIDを修正する
importExternalMedia()  : string
本文中の img/fileBlock で data-mid が未設定のノードに、$registerCallback から 得た media_id を設定する（CSV インポート、CMS-7715）
applyHtmlFilterHook()  : string
組み立て済みのブロックエディターHTMLを `filterBlockEditorHtml` フックで調整する
applyRegisteredMediaId()  : void
$source をコールバックに渡し、得られた media_id を $target の data-mid に設定する
expandFunctionTags()  : array<string, string>
機能タグを一意なトークンのコメントノードに置き換え、トークンと展開後HTMLの対応を返す
extractFunctionTagAttributes()  : array{id?: string, class?: string}
ハンドラへ渡す機能タグの属性（id / class）を取り出す
fixMediaFiles()  : void
メディアファイルの修正
fixMediaImages()  : void
メディア画像の修正
getInnerHTML()  : string
DOMDocumentからHTML文字列を取得する
hasAncestorTag()  : bool
$node の祖先に $tagName を持つ要素があるか判定する
isAttachedTo()  : bool
ノードが $doc のツリーに繋がっているか（置き換えで切り離された部分木の中でないか）
loadHTML()  : DOMDocument
HTMLをDOMDocumentとしてロードする
loadMedia()  : array<string|int, array{path: string, width: string, height: string, permalink: string, icon: string, iconWidth: string, iconHeight: string, extension: string, fileSize: int, imagePermalink: string}>
htmlに存在するメディア情報を取得する
promoteToFullFileBlock()  : void
$block（div[data-type="fileBlock"]）の a 配下に、fixMediaFiles() が値を 埋める対象となる img/p.caption の箱を補う。既に img を持つ場合は何もしない。
promoteToFullImageBlock()  : void
$img を管理画面のブロックエディターが「メディアを編集」操作を提供できる 完全な imageBlock 構造（class/data-align/data-width/data-eid/data-no-lightbox/ figure/figcaption）で包み直す
removeLastEmptyParagraph()  : void
最後の空の段落を削除する

Constants

FUNCTION_TAG_TOKEN_PREFIX

展開前の機能タグを置き換えるトークン（コメントノードの本文）の接頭辞

private mixed FUNCTION_TAG_TOKEN_PREFIX = 'acms-fn-tag:'

Properties

$lightboxClass

Lightboxクラス名

protected string $lightboxClass

$resizeImageSize

画像リサイズの幅

protected int $resizeImageSize

Methods

extractMediaId()

メディアIDを抽出する

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

fix()

ブロックエディターのHTMLを修正する

public fix(string $html[, array{resizeImage?: bool, enableFilterHook?: bool, expandFunctionTag?: bool} $options = [] ]) : string
Parameters
$html : string
$options : array{resizeImage?: bool, enableFilterHook?: bool, expandFunctionTag?: bool} = []

整形オプション

  • resizeImage: メディア画像をリサイズするか（既定 true）
  • enableFilterHook: 最終HTMLに filterBlockEditorHtml フックを適用するか（既定 true）
  • expandFunctionTag: 機能タグ（埋め込みブロック・HTMLブロック等）を展開するか（既定 true）
Return values
string

fixMediaId()

メディアIDを修正する

public fixMediaId(string $html, array<int, int> $mediaIdMap) : string
Parameters
$html : string
$mediaIdMap : array<int, int>
Return values
string

importExternalMedia()

本文中の img/fileBlock で data-mid が未設定のノードに、$registerCallback から 得た media_id を設定する（CSV インポート、CMS-7715）

public importExternalMedia(string $html, callable(string $source): Array $registerCallback, int $entryId) : string

Why not data-mid の設定だけで済ませないか: 管理画面のブロックエディター（Tiptap）は <figure> を持たない <img> 単体を data-mid 無視のフォールバックとして扱うため、 それだと表示は正しくても「メディアを編集」操作ができなくなる。そのため promoteToFullImageBlock()/promoteToFullFileBlock() で完全な構造まで組み立て直す。

Parameters
$html : string
$registerCallback : callable(string $source): Array

失敗時は null を返す

$entryId : int

編集中のエントリーID（imageBlock の data-eid に埋め込む）

Return values
string

applyHtmlFilterHook()

組み立て済みのブロックエディターHTMLを `filterBlockEditorHtml` フックで調整する

private applyHtmlFilterHook(string $html, bool $resizeImage) : string

配信URL置換まで終えた最終HTMLを参照渡しでフックに渡し、フック側での書き換え結果を返す。 ショートコードの展開など、最終出力の上書きに利用できる。フックが未登録の場合は $html を そのまま返す。

注意: ページキャッシュ有効時は出力ごとキャッシュされるため、時刻やログイン状態に依存する 動的な展開には向かない（既存のユニット拡張フックと同じ制約）。

Parameters
$html : string

配信URL置換まで終えた最終HTML

$resizeImage : bool

画像リサイズ有効か（フロント描画時 true）

Return values
string

applyRegisteredMediaId()

$source をコールバックに渡し、得られた media_id を $target の data-mid に設定する

private applyRegisteredMediaId(DOMElement $target, string $source, callable(string $source): Array $registerCallback) : void
Parameters
$target : DOMElement
$source : string
$registerCallback : callable(string $source): Array

expandFunctionTags()

機能タグを一意なトークンのコメントノードに置き換え、トークンと展開後HTMLの対応を返す

private expandFunctionTags(DOMXPath $xpath, DOMDocument $doc) : array<string, string>

対応するハンドラが無い data-block-type はそのまま残す。将来追加される型や、 拡張アプリを外した状態の既存コンテンツを取りこぼして消さないため。

展開後HTMLは fix() が getInnerHTML() した直後に文字列として差し戻す。そのため 配信URL置換と filterBlockEditorHtml フックは展開後HTMLにも効くが、DOM を対象とする 後段の処理（最後の空段落の削除・メディア画像/ファイルの書き換え）は及ばない。

Why not DOM へ取り込む: ハンドラの戻り値を libxml で再パースすると、<script> 内の </div> のような文字列が要素として解釈されて崩れ、@click [attr] のように libxml が 受け付けない属性名が落ちる。編集者が書いたHTMLを加工せず出力するため、DOM を経由させない。

Parameters
$xpath : DOMXPath
$doc : DOMDocument
Return values
array<string, string> —

コメントノードとして出力されるトークン文字列 => 展開後HTML

extractFunctionTagAttributes()

ハンドラへ渡す機能タグの属性（id / class）を取り出す

private extractFunctionTagAttributes(DOMElement $tag) : array{id?: string, class?: string}

Why not 全属性をコピー: data-block-* は保存形式の内部情報であり、任意属性を渡すと ハンドラが意図せずそれらを出力して公開HTMLの構造が保存形式に依存してしまうため、 用途が明確な id / class に限る。

Parameters
$tag : DOMElement
Return values
array{id?: string, class?: string}

fixMediaFiles()

メディアファイルの修正

private fixMediaFiles(DOMXPath $xpath, array<string|int, array{path: string, width: string, height: string, permalink: string, icon: string, iconWidth: string, iconHeight: string, extension: string, fileSize: int, imagePermalink: string}> $mediaList) : void
Parameters
$xpath : DOMXPath
$mediaList : array<string|int, array{path: string, width: string, height: string, permalink: string, icon: string, iconWidth: string, iconHeight: string, extension: string, fileSize: int, imagePermalink: string}>

fixMediaImages()

メディア画像の修正

private fixMediaImages(DOMXPath $xpath, array<string|int, array{path: string, width: string, height: string, permalink: string, icon: string, iconWidth: string, iconHeight: string, extension: string, fileSize: int, imagePermalink: string}> $mediaList[, bool $resize = true ]) : void
Parameters
$xpath : DOMXPath
$mediaList : array<string|int, array{path: string, width: string, height: string, permalink: string, icon: string, iconWidth: string, iconHeight: string, extension: string, fileSize: int, imagePermalink: string}>
$resize : bool = true

getInnerHTML()

DOMDocumentからHTML文字列を取得する

private getInnerHTML(DOMDocument $doc) : string
Parameters
$doc : DOMDocument
Return values
string

hasAncestorTag()

$node の祖先に $tagName を持つ要素があるか判定する

private hasAncestorTag(DOMElement $node, string $tagName) : bool
Parameters
$node : DOMElement
$tagName : string
Return values
bool

isAttachedTo()

ノードが $doc のツリーに繋がっているか（置き換えで切り離された部分木の中でないか）

private isAttachedTo(DOMNode $node, DOMDocument $doc) : bool
Parameters
$node : DOMNode
$doc : DOMDocument
Return values
bool

loadHTML()

HTMLをDOMDocumentとしてロードする

private loadHTML(string $html) : DOMDocument
Parameters
$html : string
Return values
DOMDocument

loadMedia()

htmlに存在するメディア情報を取得する

private loadMedia(DOMXPath $xpath) : array<string|int, array{path: string, width: string, height: string, permalink: string, icon: string, iconWidth: string, iconHeight: string, extension: string, fileSize: int, imagePermalink: string}>
Parameters
$xpath : DOMXPath
Return values
array<string|int, array{path: string, width: string, height: string, permalink: string, icon: string, iconWidth: string, iconHeight: string, extension: string, fileSize: int, imagePermalink: string}>

promoteToFullFileBlock()

$block（div[data-type="fileBlock"]）の a 配下に、fixMediaFiles() が値を 埋める対象となる img/p.caption の箱を補う。既に img を持つ場合は何もしない。

private promoteToFullFileBlock(DOMDocument $doc, DOMElement $block, DOMElement $linkTag) : void
Parameters
$doc : DOMDocument
$block : DOMElement
$linkTag : DOMElement

promoteToFullImageBlock()

$img を管理画面のブロックエディターが「メディアを編集」操作を提供できる 完全な imageBlock 構造（class/data-align/data-width/data-eid/data-no-lightbox/ figure/figcaption）で包み直す

private promoteToFullImageBlock(DOMDocument $doc, DOMElement $img, int $entryId) : void

既に <figure> の子孫であれば、手書き・既存データ由来の完全な構造とみなして 何もしない（align 等の既存指定を壊さないため）。

Parameters
$doc : DOMDocument
$img : DOMElement
$entryId : int

removeLastEmptyParagraph()

最後の空の段落を削除する

private removeLastEmptyParagraph(DOMXPath $xpath) : void

ブロックエディターがカーソル配置用に文書末尾へ残すトップレベルの空段落だけを対象にする。 //p で文書全体から探すと、末尾のブロックが group の場合に group 内の要素まで 対象になってしまう（group 内の空段落は group の中身であり、トップレベルの 末尾ダミー段落とは無関係）。loadHTML() が常に /html/body/... の構造で包むため、 body の直下（トップレベル）に絞る。

さらに body 直下の最後のノード（空白のみのテキストを除く）が p のときだけを対象にする。 展開済みの機能タグ（トークンのコメントノード）が末尾にある場合、その手前の空段落は 末尾のダミー段落ではなく編集者が置いた段落であるため残す。 段落の中に機能タグのトークンがある場合も、展開後に実体を持つため空段落として扱わない （通常のコメントだけの段落は従来どおり空とみなす）。

Parameters
$xpath : DOMXPath 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results