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

Copy
1<?php
2
3/**
4 * Dom\CharacterData オブジェクトから、指定された文字列を「後ろから」取得するサンプルコードです。
5 *
6 * この関数は、Dom\CharacterData (具体的には Dom\Text) の substringData メソッドを用いて、
7 * 文字列の末尾から数えて特定の部分文字列を抽出する方法を示します。
8 * システムエンジニアを目指す初心者が、DOM操作と文字列操作の組み合わせを理解するのに役立ちます。
9 *
10 * @param string $originalString 元となる文字列。これを Dom\CharacterData として扱います。
11 * @param int $offsetFromEnd 文字列の末尾から数えて、取得を開始する位置 (1から始まるインデックス)。
12 *                           例: 1 は最後の文字、2 は最後から2番目の文字を指します。
13 * @param int|null $length 取得する文字数。null を指定した場合、指定された開始位置から末尾まですべて取得します。
14 * @return string 抽出された部分文字列。
15 */
16function getSubstringFromEndOfDomCharacterData(string $originalString, int $offsetFromEnd, ?int $length = null): string
17{
18    // DOMDocument を作成し、文字列を格納する Dom\Text ノードを生成します。
19    // Dom\Text は Dom\CharacterData を継承しており、substringData メソッドを使用できます。
20    $dom = new DOMDocument();
21    $characterDataNode = $dom->createTextNode($originalString);
22
23    // 文字列全体の長さをマルチバイト文字に対応して取得します。
24    // Dom\CharacterData の `data` プロパティには、ノードのテキストコンテンツが含まれます。
25    $totalLength = mb_strlen($characterDataNode->data, 'UTF-8');
26
27    // 「後ろから」のオフセット ($offsetFromEnd) を、
28    // substringData メソッドが要求する「前から」の 0-based インデックスに変換します。
29    // 例えば、末尾から1文字目 (offsetFromEnd=1) は、(totalLength - 1) のインデックスになります。
30    $startOffset = $totalLength - $offsetFromEnd;
31
32    // もし計算された開始オフセットが文字列の範囲外（負の値）になった場合、
33    // 最も早い位置（0）から開始するように調整します。
34    // これは、指定した $offsetFromEnd が文字列の総文字数より大きい場合に発生します。
35    if ($startOffset < 0) {
36        $startOffset = 0;
37    }
38
39    // substringData メソッドに渡す文字数を決定します。
40    // $length が null の場合、指定された開始位置から文字列の末尾まで全てを取得します。
41    $count = ($length === null) ? ($totalLength - $startOffset) : $length;
42
43    // Dom\CharacterData の substringData メソッドを呼び出して、部分文字列を抽出します。
44    // このメソッドは、$startOffset で指定された位置から $count 文字分の文字列を返します。
45    $result = $characterDataNode->substringData($startOffset, $count);
46
47    return $result;
48}
49
50// --- 関数利用例 ---
51$sampleText = "PHPは素晴らしいプログラミング言語です。";
52
53echo "元の文字列: " . $sampleText . "\n";
54echo "------------------------------------------------\n";
55
56// 例1: 末尾から5文字を取得します。
57// （「PHPは素晴らしいプログラミング言語です。」の末尾5文字は「言語です。」です。）
58$substring1 = getSubstringFromEndOfDomCharacterData($sampleText, 5);
59echo "例1 (末尾から5文字): " . $substring1 . "\n";
60
61// 例2: 末尾から10文字目から3文字を取得します。
62// （「プログラミング言語です。」の後ろから10文字目が「グ」、そこから3文字で「グ言」が取得されます。）
63$substring2 = getSubstringFromEndOfDomCharacterData($sampleText, 10, 3);
64echo "例2 (末尾から10文字目から3文字): " . $substring2 . "\n";
65
66// 例3: 末尾から7文字目以降、末尾まですべて取得します。
67// （「プログラミング言語です。」の後ろから7文字目が「ミ」、そこから末尾までで「ミング言語です。」が取得されます。）
68$substring3 = getSubstringFromEndOfDomCharacterData($sampleText, 7);
69echo "例3 (末尾から7文字目以降すべて): " . $substring3 . "\n";
70
71// 例4: 存在しないほど大きなオフセットを指定した場合。
72// （この場合、内部でオフセットが0に調整され、先頭から指定文字数分の「PHPは」が取得されます。）
73$substring4 = getSubstringFromEndOfDomCharacterData($sampleText, mb_strlen($sampleText, 'UTF-8') + 10, 5);
74echo "例4 (大きなオフセット指定): " . $substring4 . "\n";
75

このサンプルコードは、PHPのDom\CharacterDataオブジェクトが持つsubstringDataメソッドを利用し、文字列の末尾から特定の部分文字列を抽出する方法を示すものです。Dom\CharacterData::substringDataメソッドは、DOM内のテキストデータから部分文字列を取り出すために使用され、int $offsetで指定された開始位置（文字列の先頭から数えた0始まりのインデックス）から、int $countで指定された文字数分の文字列をstringとして返します。

提供されたgetSubstringFromEndOfDomCharacterData関数は、この標準のsubstringDataメソッドを使い、「文字列の後ろから」部分文字列を取得できるように設計されたラッパー関数です。引数$originalStringは処理対象の文字列、$offsetFromEndは文字列の末尾から数えて取得を開始する位置（1始まり）、$lengthは取得する文字数（nullの場合、開始位置から末尾まで）を指定します。関数内部では、まず元の文字列をDom\CharacterData（具体的にはDom\Text）として扱えるように準備します。次に、mb_strlenで文字列の全長を取得し、$offsetFromEndで指定された「後ろから」のオフセットを、substringDataが求める「前から」の0始まりのインデックスに変換する計算を行います。この変換された開始位置と決定された文字数$countをsubstringDataメソッドに渡すことで、目的の部分文字列が抽出され、string型で返されます。これにより、DOM操作を伴う文字列処理の基本的な考え方を学ぶことができます。

Copy
1<?php
2
3/**
4 * Dom\CharacterData::substringData の使用例
5 *
6 * このメソッドは、Dom\CharacterData オブジェクト（例えば Dom\Text ノード）から、
7 * 指定されたオフセット位置から指定された文字数の部分文字列を抽出します。
8 *
9 * システムエンジニアを目指す初心者向けに、具体的な使用例を示します。
10 */
11
12// 1. 新しいDOMドキュメントを作成します。
13//    Dom\CharacterData を直接インスタンス化することはできないため、
14//    それを継承する Dom\Text ノードを通じて機能を示します。
15$document = new DOM\Document('1.0', 'UTF-8');
16
17// 2. テキストノードを作成し、Dom\CharacterData のインスタンスとして扱います。
18//    Dom\Text は Dom\CharacterData を継承しています。
19$characterDataNode = $document->createTextNode('PHPはサーバーサイドスクリプト言語です。');
20
21// 3. substringData メソッドを使用して部分文字列を抽出します。
22//    引数:
23//    - $offset: 抽出を開始する文字のオフセット（0から始まる）。
24//    - $count: 抽出する文字数。
25
26// 例1: 文字列の最初の部分を抽出する
27// オフセット 0 から 3 文字を抽出 -> "PHP"
28$offset1 = 0;
29$count1 = 3;
30$substring1 = $characterDataNode->substringData($offset1, $count1);
31
32echo "元の文字列: " . $characterDataNode->data . PHP_EOL;
33echo "例1: オフセット {$offset1} から {$count1} 文字を抽出: " . $substring1 . PHP_EOL; // 出力: PHP
34
35// 例2: 文字列の中間部分を抽出する
36// オフセット 4 から 8 文字を抽出 -> "サーバーサイド"
37$offset2 = 4;
38$count2 = 8;
39$substring2 = $characterDataNode->substringData($offset2, $count2);
40
41echo "例2: オフセット {$offset2} から {$count2} 文字を抽出: " . $substring2 . PHP_EOL; // 出力: サーバーサイド
42
43// 例3: $count が残りの文字列の長さよりも大きい場合
44// オフセット 13 から 100 文字 (残りすべて) を抽出 -> "スクリプト言語です。"
45$offset3 = 13;
46$count3 = 100; // 残りの文字数より大きい値を指定しても、文字列の終わりまでが抽出されます
47$substring3 = $characterDataNode->substringData($offset3, $count3);
48
49echo "例3: オフセット {$offset3} から {$count3} 文字を抽出 (長さ超過): " . $substring3 . PHP_EOL; // 出力: スクリプト言語です。
50
51// 例4: $offset が文字列の長さ以上の場合
52// オフセット 100 から 5 文字を抽出 -> 空文字列
53$offset4 = 100;
54$count4 = 5;
55$substring4 = $characterDataNode->substringData($offset4, $count4);
56
57echo "例4: オフセット {$offset4} から {$count4} 文字を抽出 (範囲外): " . (empty($substring4) ? '[空文字列]' : $substring4) . PHP_EOL; // 出力: [空文字列]
58
59?>

Dom\CharacterData::substringData メソッドは、PHPでXMLやHTMLなどのDOM (Document Object Model) を操作する際に、文字データを保持するDOMノードから特定の部分文字列を抽出するために利用されます。例えば、ウェブページのテキスト内容を表現するDom\Textノードに含まれる文字列の一部を取り出したいといった場面で活用できます。

このメソッドは、文字データに関する操作を提供する Dom\CharacterData クラスに属しており、テキストノードなどがこのクラスを継承しています。引数には、抽出を開始する位置を0から始まる整数で指定する int $offset と、その位置から何文字を抽出するかを指定する int $count を受け取ります。そして、抽出された部分文字列を string 型の値として返します。

具体的な挙動としては、指定された $offset から $count で指定された文字数分の文字列が正確に抽出されます。もし $count が残りの文字列の長さを超える値を指定しても、エラーとはならず、文字列の終端までがすべて抽出されるのが特徴です。ただし、$offset が元の文字列の長さを超える位置を指定した場合は、抽出する文字がないため空の文字列が返されます。このメソッドを活用することで、DOM要素が持つ長いテキストデータの中から、必要な部分だけを柔軟かつ安全に取り扱うことが可能になります。