【PHP8.x】DOMText::substringData()メソッドの使い方

Copy
1<?php
2
3/**
4 * DOMTextノードのテキストコンテンツから、末尾から指定された長さの部分文字列を抽出します。
5 *
6 * DOMText::substringData メソッドは開始オフセットと長さを必要としますが、
7 * この関数は「後ろから」の概念を実現するため、内部で開始オフセットを計算します。
8 *
9 * @param DOMText $node DOMTextノードオブジェクト。
10 * @param int $count 抽出する文字数。
11 * @return string 抽出された部分文字列。
12 * @throws InvalidArgumentException $count が負の値またはノードのテキスト長を超える場合にスローされます。
13 */
14function getSubstringFromDOMTextEnd(DOMText $node, int $count): string
15{
16    // DOMTextノードのテキストコンテンツ全体の長さを取得
17    $totalLength = $node->length;
18
19    // 抽出する文字数（$count）が不正な値でないかチェック
20    if ($count < 0) {
21        throw new InvalidArgumentException("抽出する文字数 ($count) は負の値にできません。");
22    }
23    if ($count > $totalLength) {
24        throw new InvalidArgumentException(
25            "抽出する文字数 ($count) がテキストの全長 ($totalLength) を超えています。"
26        );
27    }
28
29    // 末尾から $count 文字を抽出するための開始オフセットを計算
30    // 例: 全長10文字で末尾から3文字を取りたい場合、オフセットは 10 - 3 = 7 となる
31    $offset = $totalLength - $count;
32
33    // DOMText::substringData メソッドを使用して部分文字列を抽出
34    // $offset: 抽出を開始する位置（0から始まる）
35    // $count: 抽出する文字数
36    return $node->substringData($offset, $count);
37}
38
39// --- サンプルコードの実行例 ---
40
41// 新しいDOMDocumentオブジェクトを作成
42$dom = new DOMDocument();
43// シンプルなXML文字列をロードし、DOMTextノードを持つ構造を作成
44// <root>タグ内にテキストノードが1つ存在します。
45$dom->loadXML('<root>これはPHPのDOMText::substringDataのテストテキストです。</root>');
46
47// DOMTextノードを取得
48// documentElement (この場合 <root> タグ) の最初の子ノードがテキストノードになります。
49$textNode = $dom->documentElement->firstChild;
50
51// 取得したノードがDOMTextのインスタンスであるか確認
52if ($textNode instanceof DOMText) {
53    try {
54        // ノードの元のテキストコンテンツを表示
55        echo "元のテキスト: " . $textNode->wholeText . PHP_EOL;
56
57        // 例1: 末尾から7文字を抽出
58        // 元のテキスト: "これはPHPのDOMText::substringDataのテストテキストです。" (41文字)
59        // 期待される結果: "テキストです。"
60        $substring1 = getSubstringFromDOMTextEnd($textNode, 7);
61        echo "末尾から7文字: " . $substring1 . PHP_EOL;
62
63        // 例2: 末尾から15文字を抽出
64        // 期待される結果: "のテストテキストです。"
65        $substring2 = getSubstringFromDOMTextEnd($textNode, 15);
66        echo "末尾から15文字: " . $substring2 . PHP_EOL;
67
68        // 例3: 全文を抽出
69        // $node->length プロパティは DOMText ノードの全体のテキスト長を返します。
70        $substring3 = getSubstringFromDOMTextEnd($textNode, $textNode->length);
71        echo "全文を抽出: " . $substring3 . PHP_EOL;
72
73        // 例4: 0文字を抽出（結果として空文字列が返されます）
74        $substring4 = getSubstringFromDOMTextEnd($textNode, 0);
75        echo "0文字を抽出: '" . $substring4 . "'" . PHP_EOL;
76
77        // エラーケースの例（コメントを外して実行すると、InvalidArgumentExceptionがスローされます）
78        // $substringError1 = getSubstringFromDOMTextEnd($textNode, -5);   // エラー: 負の文字数
79        // $substringError2 = getSubstringFromDOMTextEnd($textNode, 100); // エラー: テキスト全長を超える文字数
80
81    } catch (InvalidArgumentException $e) {
82        // エラーが発生した場合にメッセージを表示
83        echo "エラー: " . $e->getMessage() . PHP_EOL;
84    }
85} else {
86    echo "エラー: DOMTextノードが見つかりませんでした。" . PHP_EOL;
87}

PHPのDOMText::substringDataメソッドは、DOMTextノードのテキストコンテンツから部分文字列を抽出するために使用されます。このメソッドは、int $offsetで指定された開始位置（0から始まる）から、int $countで指定された長さの文字列を抽出し、結果をstringとして返します。

通常のsubstringDataは開始位置からの抽出しかサポートしていませんが、サンプルコードでは「後ろから」部分文字列を抽出するためのヘルパー関数getSubstringFromDOMTextEndを定義しています。この関数はDOMText $node（対象となるテキストノード）とint $count（末尾から抽出する文字数）を引数として受け取ります。関数内部では、まずノードの全長を取得し、そこから$countを引くことで、substringDataメソッドに渡す適切な開始オフセットを計算します。そして、計算されたオフセットと$countを使って$node->substringData()を呼び出し、抽出した文字列を返します。

また、この関数は堅牢性を高めるため、$countが負の値であったり、ノードのテキスト全長を超えていたりする不正な場合にInvalidArgumentExceptionをスローするよう設計されています。サンプルコードの実行例では、DOMDocumentを使ってXMLからテキストノードを作成し、そのノードに対してgetSubstringFromDOMTextEnd関数を用いて、末尾から7文字、15文字、全文、そして0文字を抽出する具体的な利用方法が示されています。これにより、DOMText::substringDataを応用した柔軟なテキスト操作とエラーハンドリングの方法を学ぶことができます。

Copy
1<?php
2
3/**
4 * DOMText::substringData メソッドの使用例を示します。
5 * このメソッドは、XML/HTMLドキュメント内のDOMTextノードから指定された範囲のテキストデータを抽出します。
6 * システムエンジニアを目指す初心者の方のために、DOMDocumentの基本的な操作と合わせて解説します。
7 *
8 * @param string $initialText DOMTextノードに設定する初期テキスト
9 * @param int $offset 抽出を開始するオフセット（0から始まる）
10 * @param int $count 抽出する文字数
11 * @return void
12 */
13function demonstrateDomTextSubstringData(string $initialText, int $offset, int $count): void
14{
15    echo "--- DOMText::substringData の使用例 ---" . PHP_EOL;
16    echo "初期テキスト: '{$initialText}'" . PHP_EOL;
17    echo "抽出開始オフセット: {$offset}, 抽出文字数: {$count}" . PHP_EOL . PHP_EOL;
18
19    // 1. 新しいDOMDocumentオブジェクトを作成します。
20    //    これはXMLやHTMLのようなドキュメント構造をプログラムで操作するための基盤となります。
21    $dom = new DOMDocument('1.0', 'UTF-8');
22    $dom->formatOutput = true; // 出力を整形して見やすく設定します
23
24    // 2. ルート要素（例: <div>）を作成し、DOMドキュメントに追加します。
25    $divElement = $dom->createElement('div');
26    $dom->appendChild($divElement);
27
28    // 3. テキストノードを作成します。これがDOMTextオブジェクトになります。
29    //    このノードには抽出元のテキストデータが含まれます。
30    $textNode = $dom->createTextNode($initialText);
31
32    // 4. 作成したテキストノードを<div>要素に追加します。
33    //    これでテキストノードがDOMツリーの一部となります。
34    $divElement->appendChild($textNode);
35
36    // 5. DOMText::substringData メソッドを呼び出して、テキストの一部を抽出します。
37    //    これはPHPの標準関数である substr() と似ていますが、
38    //    DOMTextオブジェクトに対して動作し、XML/HTMLドキュメントの文脈で使用されます。
39    //    $textNode が DOMText のインスタンスなので、直接メソッドを呼び出せます。
40    $extractedString = $textNode->substringData($offset, $count);
41
42    // 6. 抽出された文字列を表示します。
43    echo "抽出された文字列: '{$extractedString}'" . PHP_EOL;
44
45    // 参考として、作成されたDOMドキュメントのHTML構造を出力します。
46    echo PHP_EOL . "--- 作成されたDOMドキュメントのHTML (確認用) ---" . PHP_EOL;
47    echo $dom->saveHTML();
48    echo PHP_EOL;
49}
50
51// サンプルコードを実行して、さまざまなケースを試します。
52
53// ケース1: 文字列の途中から一部を抽出
54demonstrateDomTextSubstringData("Hello, PHP DOM World!", 7, 3); // "PHP" を抽出
55
56// ケース2: 別の文字列で抽出
57demonstrateDomTextSubstringData("This is an example text for substring.", 8, 7); // "an exam" を抽出
58
59// ケース3: 文字列の先頭から抽出
60demonstrateDomTextSubstringData("Another test string.", 0, 7); // "Another" を抽出
61
62// ケース4: 抽出文字数が残りの文字列長を超える場合（可能な限り抽出される）
63demonstrateDomTextSubstringData("Short text", 5, 10); // " text" を抽出
64
65// ケース5: オフセットが文字列長を超える場合（空文字列が返される）
66demonstrateDomTextSubstringData("Short text", 15, 5); // "" (空文字列) を抽出

DOMText::substringDataは、PHPのDOM拡張機能の一部で、XMLやHTMLドキュメントの構造を扱う際に使用されるメソッドです。このメソッドは、ドキュメントツリー内のテキストデータが格納されているDOMTextノードから、指定された範囲の文字列を抽出するために利用されます。

引数としては、抽出を開始する位置を示す$offsetと、そこから何文字抽出するかを示す$countの2つの整数値を受け取ります。$offsetは文字列の先頭を0として数え始めます。戻り値は、抽出されたテキスト部分をstring型で返します。例えば、テキスト「Hello World」に対して$offsetに7、$countに3を指定すると、「Wor」という文字列が抽出されます。指定されたオフセットがテキストの長さを超える場合や、$countが残りの文字数を超える場合は、それぞれ可能な範囲で抽出が行われるか、あるいは空の文字列が返されることがあります。

このメソッドは、PHPの標準関数であるsubstr()と機能が似ていますが、DOMTextクラスのインスタンスに対して直接呼び出される点が異なります。XMLやHTMLドキュメントをプログラムで解析・操作し、特定のテキストノードから内容を部分的に取得したい場合に活用されます。サンプルコードでは、DOMDocumentを作成し、その中に要素とテキストノードを配置した後、DOMTextノードからsubstringDataメソッドを使って目的の文字列を抽出する具体的な手順が示されており、DOM操作の基本的な流れとともにメソッドの利用方法を理解できます。