【PHP8.x】RecursiveCachingIterator::TOSTRING_USE_INNER定数の使い方

Copy
1<?php
2
3// RecursiveCachingIterator::TOSTRING_USE_INNER 定数の動作を示すサンプルコードです。
4// この定数は、RecursiveCachingIteratorオブジェクトを文字列に変換する際に、
5// ラップしている内部イテレータの__toString()メソッドを使用するように指示します。
6
7/**
8 * 内部イテレータとして使用するカスタムの再帰イテレータクラス。
9 * RecursiveCachingIteratorでラップされることを想定しており、
10 * __toString() メソッドを持つことで、その動作の違いを示します。
11 *
12 * このクラスは、RecursiveIterator インターフェースの必須メソッドを実装していますが、
13 * 本サンプルコードの目的（__toString()の動作デモンストレーション）のため、
14 * 最小限の機能に留めています。
15 */
16class MyRecursiveIterator implements RecursiveIterator
17{
18    private array $data;
19    private int $position = 0;
20    private string $name;
21
22    /**
23     * コンストラクタ
24     *
25     * @param string $name このイテレータを識別するための名前
26     * @param array $data イテレータが処理するデータ
27     */
28    public function __construct(string $name, array $data)
29    {
30        $this->name = $name;
31        $this->data = $data;
32    }
33
34    /**
35     * オブジェクトが文字列として扱われたときに呼び出されるマジックメソッド。
36     * RecursiveCachingIterator::TOSTRING_USE_INNER フラグが設定されている場合、
37     * このメソッドの戻り値が使用されます。
38     *
39     * @return string このオブジェクトの文字列表現
40     */
41    public function __toString(): string
42    {
43        return "MyCustomIterator[{$this->name}]";
44    }
45
46    // RecursiveIteratorインターフェースの必須メソッド
47    public function hasChildren(): bool
48    {
49        return is_array($this->current());
50    }
51
52    public function getChildren(): RecursiveIterator
53    {
54        // ネストされた配列を新しいMyRecursiveIteratorインスタンスでラップ
55        return new self($this->name . '_child', $this->current());
56    }
57
58    public function current(): mixed
59    {
60        return $this->data[$this->position] ?? null;
61    }
62
63    public function key(): int
64    {
65        return $this->position;
66    }
67
68    public function next(): void
69    {
70        $this->position++;
71    }
72
73    public function rewind(): void
74    {
75        $this->position = 0;
76    }
77
78    public function valid(): bool
79    {
80        return isset($this->data[$this->position]);
81    }
82}
83
84/**
85 * RecursiveCachingIterator::TOSTRING_USE_INNER 定数の動作を示す関数。
86 * システムエンジニアを目指す初心者向けに、具体例を通じて定数の効果を説明します。
87 */
88function demonstrateRecursiveCachingIteratorToString(): void
89{
90    // 1. 内部イテレータとなるカスタムイテレータのインスタンスを作成します。
91    //    このイテレータは、文字列に変換されたときに特定の文字列を返すよう定義されています。
92    $innerIterator = new MyRecursiveIterator('ExampleData', ['value1', 'value2', ['nested1', 'nested2']]);
93
94    echo "--- デフォルトの RecursiveCachingIterator の __toString() の挙動 ---" . PHP_EOL;
95    // 2. RecursiveCachingIterator をフラグなし（デフォルト）で作成します。
96    //    この場合、RecursiveCachingIterator自身のデフォルトの文字列表現が使用されます。
97    //    通常、これはクラス名やオブジェクトIDを含む形式になります。
98    $rcIteratorDefault = new RecursiveCachingIterator($innerIterator);
99    echo "RecursiveCachingIterator (デフォルト): " . $rcIteratorDefault . PHP_EOL . PHP_EOL;
100
101    echo "--- TOSTRING_USE_INNER フラグを設定した場合の RecursiveCachingIterator の __toString() の挙動 ---" . PHP_EOL;
102    // 3. RecursiveCachingIterator を TOSTRING_USE_INNER フラグと共に作成します。
103    //    このフラグが設定されると、RecursiveCachingIteratorを文字列に変換する際に、
104    //    ラップしている内部イテレータ ($innerIterator) の __toString() メソッドが呼び出されます。
105    //    これにより、上記で定義した MyRecursiveIterator の __toString() の戻り値が直接出力されます。
106    $rcIteratorWithFlag = new RecursiveCachingIterator(
107        $innerIterator,
108        RecursiveCachingIterator::TOSTRING_USE_INNER
109    );
110    echo "RecursiveCachingIterator (TOSTRING_USE_INNER): " . $rcIteratorWithFlag . PHP_EOL;
111}
112
113// 上記で定義したデモンストレーション関数を実行します。
114demonstrateRecursiveCachingIteratorToString();

PHPのRecursiveCachingIterator::TOSTRING_USE_INNER定数は、RecursiveCachingIteratorクラスのインスタンスを文字列に変換する際の動作を制御するために使用されます。この定数自体は引数を持ちませんが、内部的には整数値（int）として扱われ、特定の動作モードを示します。

通常、RecursiveCachingIteratorオブジェクトをそのまま文字列として扱うと、PHPのデフォルトのルールに従い、クラス名などを含む文字列表現が返されます。しかし、このTOSTRING_USE_INNER定数をRecursiveCachingIteratorのコンストラクタに設定すると、この挙動を変更できます。

サンプルコードでは、まずMyRecursiveIteratorという独自のイテレータを作成し、その__toString()メソッドが特定の文字列を返すように定義しています。このMyRecursiveIteratorをRecursiveCachingIteratorでラップし、TOSTRING_USE_INNERフラグを設定せずに文字列に変換すると、RecursiveCachingIterator自身のデフォルトの文字列表現が出力されます。

対照的に、TOSTRING_USE_INNERフラグをコンストラクタに指定してRecursiveCachingIteratorを作成し、文字列に変換すると、ラップされているMyRecursiveIteratorの__toString()メソッドが呼び出され、そのメソッドが返す文字列がそのまま出力されます。これにより、内部のイテレータが持つ独自の文字列表現を、外部のRecursiveCachingIteratorを介して直接利用できるようになります。これは、デバッグやログ出力の際に、イテレータの中身をより分かりやすく表示したい場合に役立ちます。

Copy
1<?php
2
3/**
4 * RecursiveCachingIterator の TOSTRING_USE_INNER 定数の使用例。
5 *
6 * この定数は、RecursiveCachingIterator オブジェクトが文字列に変換される際に、
7 * 内部のイテレータの __toString() メソッドを使用するかどうかを制御します。
8 *
9 * PHP 8 の機能を使用しています。
10 */
11
12/**
13 * 内部イテレータとして使用するための ArrayIterator の拡張クラス。
14 * __toString() メソッドをオーバーライドして、カスタムの文字列表現を提供します。
15 */
16class MyCustomArrayIterator extends ArrayIterator
17{
18    /**
19     * オブジェクトの文字列表現を返します。
20     * RecursiveCachingIterator::TOSTRING_USE_INNER が設定されている場合に呼び出されます。
21     */
22    public function __toString(): string
23    {
24        return 'MyCustomArrayIterator が持つ要素数: ' . $this->count() . '個です。';
25    }
26}
27
28// テスト用のデータ配列
29$data = ['apple', 'banana', 'cherry'];
30
31// 1. カスタムの内部イテレータを作成
32// このイテレータは、文字列に変換されるとカスタムメッセージを返します。
33$innerIterator = new MyCustomArrayIterator($data);
34
35echo "--- TOSTRING_USE_INNER を使用しない場合 ---\n";
36
37// 2. TOSTRING_USE_INNER フラグなしで RecursiveCachingIterator を作成
38// デフォルトでは、RecursiveCachingIterator 自身のクラス名とオブジェクトハッシュが出力されます。
39$rcIteratorDefault = new RecursiveCachingIterator($innerIterator);
40
41// RecursiveCachingIterator オブジェクトを文字列として出力
42// ここでは、内部イテレータの __toString() は使用されません。
43echo "デフォルトのRecursiveCachingIteratorの文字列化: " . $rcIteratorDefault . "\n\n";
44
45echo "--- TOSTRING_USE_INNER を使用する場合 ---\n";
46
47// 3. TOSTRING_USE_INNER フラグを指定して RecursiveCachingIterator を作成
48// このフラグにより、RecursiveCachingIterator を文字列化する際に、
49// 内部イテレータ（MyCustomArrayIterator）の __toString() メソッドが呼び出されます。
50$rcIteratorWithFlag = new RecursiveCachingIterator(
51    $innerIterator,
52    RecursiveCachingIterator::TOSTRING_USE_INNER
53);
54
55// RecursiveCachingIterator オブジェクトを文字列として出力
56// TOSTRING_USE_INNER フラグのおかげで、MyCustomArrayIterator の __toString() が呼び出されます。
57echo "TOSTRING_USE_INNERありのRecursiveCachingIteratorの文字列化: " . $rcIteratorWithFlag . "\n";
58
59?>

RecursiveCachingIterator::TOSTRING_USE_INNERは、PHP 8で導入されたRecursiveCachingIteratorクラスに属する定数です。この定数自体に引数はなく、整数型の値を持ち、RecursiveCachingIteratorオブジェクトを文字列に変換する際の挙動を制御するために使用されます。

通常、PHPのオブジェクトを文字列として出力しようとすると、そのオブジェクト自身のクラス名と一意な識別子（ハッシュ）が表示されます。しかし、RecursiveCachingIteratorのコンストラクタの第二引数にTOSTRING_USE_INNER定数を指定すると、その挙動を変更することができます。この定数を指定した場合、RecursiveCachingIteratorオブジェクトが文字列に変換される際に、それが内部に持っているイテレータ（ループ処理を行うオブジェクト）の__toString()メソッドが呼び出されるようになります。

サンプルコードでは、__toString()メソッドを独自に実装したMyCustomArrayIteratorクラスを内部イテレータとして使用しています。TOSTRING_USE_INNER定数を指定せずにRecursiveCachingIteratorを文字列化すると、デフォルトのオブジェクト情報が出力されます。しかし、この定数を指定して文字列化すると、MyCustomArrayIteratorで定義されたカスタムメッセージ「MyCustomArrayIterator が持つ要素数: X個です。」が出力されます。これにより、RecursiveCachingIteratorが保持する内部イテレータの情報を、より意味のある形で文字列として表現することが可能になります。