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

substringDataメソッドの使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年11月25日

基本的な使い方

『substringDataメソッドは、Dom\Textオブジェクトが持つテキストデータから、指定した部分文字列を取得するために実行するメソッドです。このメソッドは、元のテキストノードの内容を一切変更せずに、その一部分を文字列として取り出します。メソッドを呼び出す際には2つの引数を指定する必要があります。第1引数には、切り出しを開始したい位置を0から始まる数値（オフセット）で指定します。第2引数には、開始位置から何文字分を切り出すかの長さ（文字数）を指定します。処理が正常に完了した場合、戻り値として切り出された文字列が返されます。もし、指定した開始位置がテキストデータの長さを超えているなど、無効な範囲が指定された場合には、文字列の代わりにfalseが返されます。これにより、プログラムは文字列の取得が成功したかどうかを判断できます。HTMLやXMLドキュメント内の特定のテキスト情報の一部だけを安全に読み取りたい場合に非常に便利なメソッドです。』

構文(syntax)


1<?php
2
3$dom = new Dom\Document();
4$dom->loadHTML('<div>Hello World</div>');
5
6// 'Hello World' というテキストノードを取得
7$textNode = $dom->getElementsByTagName('div')->item(0)->firstChild;
8
9// public function substringData(int $offset, int $length): string
10$substring = $textNode->substringData(6, 5);
11
12// 出力: "World"
13echo $substring;
14
15?>

引数(parameters)

int $offset, int $length

int $offset: 取得を開始する位置を指定する整数
int $length: 取得する文字数を指定する整数

戻り値(return)

string

指定された位置から始まる文字列の一部を返します。

サンプルコード

PHP Dom\Text::substringData で後ろから抽出する


1<?php
2
3/**
4 * Dom\Text::substringData メソッドを使用して、Dom\Textオブジェクトから後ろから指定された長さの部分文字列を抽出します。
5 * Dom\Text::substringData は負のオフセットを直接サポートしないため、
6 * テキストノードの全長を基に開始オフセットを計算する必要があります。
7 *
8 * @param Dom\Text $textNode 処理対象のDom\Textオブジェクト。
9 * @param int $lengthFromEnd テキストの最後から抽出する文字数。0より大きく、テキストの全長以下である必要があります。
10 * @return string 抽出された部分文字列。無効な $lengthFromEnd が指定された場合は空文字列を返します。
11 */
12function getSubstringFromEndOfDomText(Dom\Text $textNode, int $lengthFromEnd): string
13{
14    // テキストノードの全長を取得します。
15    // Dom\Text::$length プロパティは、テキストデータの文字数を表します。
16    $totalLength = $textNode->length;
17
18    // 抽出したい長さがテキストの全長を超える場合、または0以下の場合、
19    // 無効なリクエストとみなし、空文字列を返します。
20    if ($lengthFromEnd <= 0 || $lengthFromEnd > $totalLength) {
21        return '';
22    }
23
24    // 後ろから指定された長さを抽出するための開始オフセットを計算します。
25    // 例: 全長10、後ろから3文字 (lengthFromEnd) を抽出したい場合、
26    // 開始オフセットは 10 - 3 = 7 となります。
27    $offset = $totalLength - $lengthFromEnd;
28
29    // Dom\Text::substringData メソッドを使用して、部分文字列を抽出します。
30    // 第1引数は抽出を開始するオフセット、第2引数は抽出する長さです。
31    $subData = $textNode->substringData($offset, $lengthFromEnd);
32
33    return $subData;
34}
35
36// --- サンプルコードの使用例 ---
37
38// 1. 新しいDom\Documentオブジェクトを作成します。
39$dom = new Dom\Document('1.0', 'UTF-8');
40
41// 2. DOMツリーのルートとなる要素を作成し、ドキュメントに追加します。
42$rootElement = $dom->createElement('root');
43$dom->appendChild($rootElement);
44
45// 3. テキストノードを保持するための要素を作成し、ルート要素に追加します。
46$paragraphElement = $dom->createElement('p');
47$rootElement->appendChild($paragraphElement);
48
49// 4. Dom\Textノードを作成し、上記で作成した要素に追加します。
50// このテキストノードから部分文字列を抽出します。
51$textNode = $dom->createTextNode('この長いテキストの最後から一部を抽出します。');
52$paragraphElement->appendChild($textNode);
53
54// 5. 作成したDom\Textノードから、文字列の最後から7文字を抽出します。
55$lengthToExtract = 7;
56$extractedString = getSubstringFromEndOfDomText($textNode, $lengthToExtract);
57
58echo "元のテキスト: " . $textNode->wholeText . PHP_EOL;
59echo "後ろから " . $lengthToExtract . " 文字を抽出: " . $extractedString . PHP_EOL; // 出力: "抽出します。"
60
61// 別の例: 後ろから13文字を抽出します。
62$lengthToExtract = 13;
63$extractedString = getSubstringFromEndOfDomText($textNode, $lengthToExtract);
64
65echo "後ろから " . $lengthToExtract . " 文字を抽出: " . $extractedString . PHP_EOL; // 出力: "一部を抽出します。"
66
67// 無効な長さ（テキストの全長より長い）を試す例
68$invalidLength = 100;
69$extractedString = getSubstringFromEndOfDomText($textNode, $invalidLength);
70
71echo "後ろから " . $invalidLength . " 文字を抽出 (無効な長さ): " . ($extractedString ?: '抽出失敗（長さが不適切）') . PHP_EOL;
72
73// 無効な長さ（0文字）を試す例
74$zeroLength = 0;
75$extractedString = getSubstringFromEndOfDomText($textNode, $zeroLength);
76
77echo "後ろから " . $zeroLength . " 文字を抽出 (無効な長さ): " . ($extractedString ?: '抽出失敗（長さが不適切）') . PHP_EOL;
78
79?>

PHP 8のDom\Text::substringDataメソッドは、XMLやHTMLなどのDOMツリー内のテキストノードから、指定された位置（オフセット）と長さで部分文字列を抽出するための機能です。このメソッドは、第1引数に抽出を開始する文字位置（0から始まるオフセット）、第2引数に抽出する文字数を指定し、結果として抽出された文字列を返します。

しかし、substringDataメソッド自体は、文字列の末尾から数えるような負のオフセットを直接サポートしていません。今回ご紹介するサンプルコードは、このsubstringDataメソッドを応用し、テキストノードの最後から指定された長さの部分文字列を抽出する方法を初心者の方にも分かりやすく示しています。

サンプルコードのgetSubstringFromEndOfDomText関数では、まず対象のDom\Textオブジェクトが持つlengthプロパティを利用して、テキスト全体の文字数を取得します。次に、「テキストの最後から抽出したい文字数」をこの全長から差し引くことで、substringDataメソッドが必要とする「文字列の先頭からの開始オフセット」を計算しています。例えば、全長が10文字で、最後から3文字を抽出したい場合、開始オフセットは7（10 - 3）となります。そして、この計算されたオフセットと、もともと指定された「最後から抽出したい文字数」をsubstringDataメソッドに渡すことで、目的の部分文字列を効率的に取得しています。

この関数は、Dom\Textオブジェクトと、テキストの最後から抽出したい文字数を引数として受け取ります。抽出する文字数が0以下であったり、テキストの全長を超えたりするなど、無効な値が指定された場合には、空文字列を返すことでエラー状態を適切に扱っています。このように、substringDataはDOM内のテキストデータを柔軟に操作するために非常に役立つメソッドです。

Dom\Text::substringDataメソッドは、PHPの一般的な文字列関数とは異なり、負のオフセットを直接指定して後ろから部分文字列を抽出することはできません。そのため、サンプルコードのようにテキストノードの全長をまず取得し、そこから開始オフセットを計算する必要があります。

また、抽出したい長さが0以下であったり、元のテキストの全長を超過したりする場合、メソッドがエラーを発生させる代わりに空文字列を返すようなバリデーションを含めることで、安全で堅牢なコードになります。Dom\Text::$lengthプロパティはテキストの正確な文字数を返しますので、マルチバイト文字を含む場合でもオフセット計算を安心して行えます。この関数はDOM操作に特化しているため、一般的な文字列処理と混同しないよう注意が必要です。

PHP DOM Text substringData で部分文字列を取得する


1<?php
2
3// DOMDocumentを作成します。これはHTMLやXMLのようなドキュメントを操作するための基盤です。
4$dom = new DOMDocument('1.0', 'UTF-8');
5
6// ルート要素（例: <body> や <root>）を作成し、ドキュメントに追加します。
7// テキストノードを追加するためには、まず親となる要素が必要です。
8$rootElement = $dom->createElement('root');
9$dom->appendChild($rootElement);
10
11// テキストノードを作成します。これが Dom\Text クラスのインスタンス（またはその子クラスのインスタンス）となります。
12// substringData メソッドはこのテキストノードに対して使われます。
13$textNode = $dom->createTextNode('Welcome to PHP DOM Text Manipulation!');
14$rootElement->appendChild($textNode);
15
16// Dom\Text::substringData メソッドを使用して、テキストノードから部分文字列を抽出します。
17// 第1引数 ($offset): 抽出を開始する位置 (0から始まるインデックス)。
18// 第2引数 ($length): 抽出する文字数。
19
20// 例1: "PHP" を抽出
21$offset1 = 11; // 'P' の位置
22$length1 = 3;  // "PHP" の長さ
23
24$extractedText1 = $textNode->substringData($offset1, $length1);
25
26echo "元のテキスト: \"" . $textNode->nodeValue . "\"\n";
27echo "抽出された部分文字列 (オフセット " . $offset1 . "、長さ " . $length1 . "): \"" . $extractedText1 . "\"\n";
28
29// 例2: "Manipulation" を抽出
30$offset2 = 21; // 'M' の位置
31$length2 = 12; // "Manipulation" の長さ
32
33$extractedText2 = $textNode->substringData($offset2, $length2);
34
35echo "抽出された部分文字列 (オフセット " . $offset2 . "、長さ " . $length2 . "): \"" . $extractedText2 . "\"\n";
36
37?>

PHP 8のDom\Text::substringDataメソッドは、XMLやHTMLなどのドキュメント構造をプログラムで操作するDOM（Document Object Model）において、テキストノードに格納されている文字列の一部を抽出するために使用されます。このメソッドは、ドキュメント内の実際のテキスト内容を表すDom\Textクラスのインスタンスに対して呼び出されます。

substringDataメソッドは二つの整数型引数を取ります。一つ目の$offsetは、文字列の抽出を開始する位置を0から数えて指定します。二つ目の$lengthは、$offsetで指定された位置から何文字分の文字列を抽出するかを指定します。これらの引数に基づいて、指定された範囲の部分文字列が新しい文字列として返されます。元のテキストノードの文字列自体は変更されません。

サンプルコードでは、DOMDocumentを作成し、その中に'Welcome to PHP DOM Text Manipulation!'というテキストノードを追加しています。そして、このテキストノードに対してsubstringDataメソッドを呼び出し、例えばオフセット11から3文字分の"PHP"や、オフセット21から12文字分の"Manipulation"といった部分文字列を抽出しています。このように、ドキュメント内の特定のテキスト情報を取り出して利用・加工する際に、このメソッドは大変役立ちます。

Dom\Text::substringDataは、通常の文字列関数と異なり、DOMツリー内のテキストノード専用のメソッドです。PHPのDOM拡張機能として、HTMLやXMLのようなドキュメントのテキスト部分を構造的に扱います。

引数$offsetは0からの抽出開始位置、$lengthは抽出する文字数を指定します。これらの値が元のテキストの範囲を超えてもエラーは発生しませんが、予期せぬ結果を避けるため、テキストの長さを確認し、適切な範囲を指定することが重要です。

本メソッドは、DOMツリーの整合性を保ちながらテキストデータを安全に処理する際に推奨されます。テキストノードのnodeValueプロパティを直接操作するよりも、DOM要素としてテキストを扱う場合は、本メソッドの使用がより適切です。