【PHP8.x】RecursiveTreeIterator::CATCH_GET_CHILD定数の使い方

Copy
1<?php
2
3/**
4 * RecursiveIterator インターフェースを実装し、
5 * getChildren() メソッドで意図的に例外をスローするイテレータの例です。
6 *
7 * このクラスは、ツリー構造のルート要素を一つだけ持ち、その子要素を取得しようとすると
8 * 常に LogicException を発生させるように設計されています。
9 */
10class MyFaultyRecursiveIterator implements RecursiveIterator
11{
12    private int $position = 0;
13    private array $items = ['root_node']; // 単一のルートノードを持つと仮定
14
15    /**
16     * 現在の要素が子を持つかどうかを判断します。
17     * ルートノードは子を持つと見せかけます。
18     */
19    public function hasChildren(): bool
20    {
21        return $this->position === 0 && isset($this->items[$this->position]);
22    }
23
24    /**
25     * 現在の要素の子イテレータを返します。
26     * このメソッドは意図的に LogicException をスローします。
27     */
28    public function getChildren(): ?RecursiveIterator
29    {
30        if ($this->position === 0) {
31            // 子要素の取得に失敗したというシナリオをシミュレート
32            throw new LogicException("子要素の取得中に問題が発生しました。これはオリジナルの例外です。");
33        }
34        return null; // 通常は新しい RecursiveIterator インスタンスを返すべきです
35    }
36
37    /**
38     * 現在の要素を返します。
39     */
40    public function current(): mixed
41    {
42        return $this->items[$this->position];
43    }
44
45    /**
46     * 現在の要素のキーを返します。
47     */
48    public function key(): mixed
49    {
50        return $this->position;
51    }
52
53    /**
54     * イテレータを次の要素に進めます。
55     */
56    public function next(): void
57    {
58        $this->position++;
59    }
60
61    /**
62     * イテレータを最初の要素に巻き戻します。
63     */
64    public function rewind(): void
65    {
66        $this->position = 0;
67    }
68
69    /**
70     * 現在の要素が有効かどうかを判断します。
71     */
72    public function valid(): bool
73    {
74        return isset($this->items[$this->position]);
75    }
76}
77
78echo "--- RecursiveTreeIterator::CATCH_GET_CHILD なしの場合 ---\n";
79try {
80    $faultyIterator = new MyFaultyRecursiveIterator();
81    // RecursiveTreeIterator を RecursiveTreeIterator::CATCH_GET_CHILD フラグなしで作成
82    // これにより、get_children() でスローされた例外がそのまま伝播します。
83    $treeIterator = new RecursiveTreeIterator($faultyIterator);
84
85    echo "RecursiveTreeIteratorを走査中...\n";
86    // foreachループが開始されると、内部で hasChildren() -> getChildren() が呼ばれる
87    foreach ($treeIterator as $key => $value) {
88        // この行に到達する前に getChildren() で例外が発生します
89        echo "Key: $key, Value: $value\n";
90    }
91    echo "走査完了 (例外が発生しなければ表示されます)\n";
92} catch (LogicException $e) {
93    // CATCH_GET_CHILD がないため、MyFaultyRecursiveIterator がスローした
94    // 元の LogicException を直接捕捉できます。
95    echo "LogicException を捕捉しました: " . $e->getMessage() . "\n";
96    echo "このケースでは、オリジナルの例外がそのまま捕捉されます。\n";
97} catch (Exception $e) {
98    echo "その他の例外を捕捉しました: " . $e->getMessage() . "\n";
99}
100
101echo "\n--- RecursiveTreeIterator::CATCH_GET_CHILD ありの場合 ---\n";
102try {
103    $faultyIterator = new MyFaultyRecursiveIterator();
104    // RecursiveTreeIterator を RecursiveTreeIterator::CATCH_GET_CHILD フラグありで作成
105    // このフラグは、get_children() でスローされた例外を RuntimeException でラップし、
106    // 再スローするように指示します。
107    $treeIteratorWithCatch = new RecursiveTreeIterator(
108        $faultyIterator,
109        RecursiveTreeIterator::CATCH_GET_CHILD
110    );
111
112    echo "RecursiveTreeIteratorを走査中 (CATCH_GET_CHILD フラグ付き)...\n";
113    foreach ($treeIteratorWithCatch as $key => $value) {
114        // この行に到達する前に getChildren() で例外が発生します
115        echo "Key: $key, Value: $value\n";
116    }
117    echo "走査完了 (例外が発生しなければ表示されます)\n";
118} catch (RuntimeException $e) {
119    // CATCH_GET_CHILD フラグがあるため、MyFaultyRecursiveIterator がスローした
120    // LogicException は RuntimeException にラップされて捕捉されます。
121    echo "RuntimeException を捕捉しました: " . $e->getMessage() . "\n";
122    echo "元の例外メッセージ: " . ($e->getPrevious()?->getMessage() ?? '元の例外なし') . "\n";
123    echo "このケースでは、RecursveTreeIterator 内部で発生した元の例外が\n";
124    echo "RuntimeException としてラップされ、捕捉可能になっています。\n";
125} catch (Exception $e) {
126    echo "その他の例外を捕捉しました: " . $e->getMessage() . "\n";
127}

RecursiveTreeIterator::CATCH_GET_CHILDは、PHPのRecursiveTreeIteratorクラスがツリー構造を走査する際に、子要素の取得中に発生した例外をどのように扱うかを制御するための定数です。この定数自体は引数を取らず、整数値（int）を返します。

この定数をRecursiveTreeIteratorのコンストラクタに指定しない場合、子要素を取得するためのgetChildren()メソッド内で発生した例外（例としてLogicException）は、RecursiveTreeIteratorを介さずにそのまま外部に伝播します。そのため、プログラム側では元の例外の種類で直接catchすることができます。

一方、RecursiveTreeIterator::CATCH_GET_CHILDをRecursiveTreeIteratorのコンストラクタの第二引数に指定すると、getChildren()メソッド内で発生した例外は、RuntimeExceptionでラップされて再スローされます。この場合、プログラム側ではRuntimeExceptionをcatchする必要があります。元の例外は、捕捉したRuntimeExceptionオブジェクトのgetPrevious()メソッドを通じて取得することが可能です。

このように、CATCH_GET_CHILD定数を使用することで、ツリー構造のイテレーション中に子要素の取得で問題が発生した場合の例外処理の挙動を、柔軟に制御できるのが特徴です。

Copy
1<?php
2
3/**
4 * RecursiveTreeIterator::CATCH_GET_CHILD の動作を示すためのカスタム RecursiveIterator。
5 * 特定のキー ('error_node') で子要素にアクセスしようとすると例外をスローします。
6 */
7class MyRecursiveArrayIterator extends ArrayIterator implements RecursiveIterator
8{
9    public function hasChildren(): bool
10    {
11        return is_array($this->current());
12    }
13
14    public function getChildren(): RecursiveIterator
15    {
16        // 'error_node' キーの子要素にアクセスしようとした際に意図的に例外をスローします。
17        // RecursiveTreeIterator::CATCH_GET_CHILD が設定されている場合、
18        // この例外は外部に伝播せず、イテレーションは続行されます。
19        if ($this->key() === 'error_node') {
20            throw new Exception("Failed to get children for 'error_node'.");
21        }
22        return new self($this->current());
23    }
24}
25
26/**
27 * RecursiveTreeIterator::CATCH_GET_CHILD の使用例を示します。
28 *
29 * この定数 (int 型) を RecursiveTreeIterator のコンストラクタに渡すと、
30 * 基になる RecursiveIterator の getChildren() メソッドが例外をスローしても、
31 * その例外はイテレータの外部に「catchされず」に伝播することなく、
32 * イテレーション処理が中断されずに続行されます。
33 * 例外をスローしたノードは子を持たないリーフノードとして扱われ、
34 * その子孫はスキップされます。
35 *
36 * これは、ツリー構造の一部に問題があっても全体の走査を止めずに、
37 * 問題のある部分を単にスキップしたい場合に非常に有用です。
38 */
39function demonstrateRecursiveTreeIteratorCatchGetChild(): void
40{
41    $data = [
42        'item1' => [
43            'subitem1a' => 'value1a',
44            'subitem1b' => 'value1b',
45        ],
46        'item2' => 'value2',
47        'item3' => [
48            'subitem3a' => 'value3a',
49            'error_node' => 'This node will cause an exception when its children are requested.',
50            'subitem3b' => 'value3b', // この要素は'error_node'の後にあるためスキップされます。
51        ],
52        'item4' => 'value4',
53    ];
54
55    // RecursiveArrayIterator を作成し、カスタムの RecursiveIterator を適用します。
56    $recursiveIterator = new MyRecursiveArrayIterator($data);
57
58    // RecursiveTreeIterator を作成し、CATCH_GET_CHILD フラグを設定します。
59    // このフラグにより、getChildren() で発生した例外が内部で処理され、イテレーションが続行されます。
60    $treeIterator = new RecursiveTreeIterator(
61        $recursiveIterator,
62        RecursiveTreeIterator::BYPASS_CURRENT_KEY, // 出力を見やすくするためのフラグ
63        RecursiveTreeIterator::BYPASS_CURRENT_KEY, // 出力を見やすくするためのフラグ
64        RecursiveTreeIterator::CATCH_GET_CHILD     // <-- ここで定数を使用
65    );
66
67    echo "RecursiveTreeIterator::CATCH_GET_CHILD を使用したツリー走査:\n";
68    echo "('error_node' の子要素取得時に例外が発生しますが、イテレーションは中断されません。)\n\n";
69
70    // ツリーを走査し、各要素を出力します。
71    foreach ($treeIterator as $key => $value) {
72        // 現在の深さに応じてインデントを追加し、ツリー構造を表現します。
73        echo str_repeat('  ', $treeIterator->getDepth()) . "[{$key}] = {$value}\n";
74    }
75
76    echo "\n注意: 'error_node' の後に続く 'subitem3b' は表示されません。";
77    echo "これは 'error_node' が子ノードの取得で例外をスローし、";
78    echo "CATCH_GET_CHILD によりその例外が内部で処理され、";
79    echo "'error_node' がリーフノードとして扱われたためです。\n";
80}
81
82// サンプルコードを実行します。
83demonstrateRecursiveTreeIteratorCatchGetChild();

PHP 8 の RecursiveTreeIterator::CATCH_GET_CHILD は、RecursiveTreeIterator のコンストラクタに渡すことで特定の動作を制御する整数型の定数です。この定数を指定すると、基となる RecursiveIterator の getChildren() メソッドが子要素の取得時に例外をスローした場合でも、その例外が RecursiveTreeIterator の内部で処理され、外部には伝播することなく、イテレーション処理が中断されずに続行されます。例外をスローしたノードは子を持たないリーフノードとして扱われ、その子孫はスキップされます。

サンプルコードでは、MyRecursiveArrayIterator というカスタムイテレータを定義し、特定のキー（'error_node'）の子要素にアクセスしようとすると例外をスローするようにしています。このカスタムイテレータを RecursiveTreeIterator に渡し、さらに RecursiveTreeIterator::CATCH_GET_CHILD 定数を指定してツリーを走査しています。これにより、'error_node' の子要素取得時に例外が発生してもイテレーションは中断されず、その後の 'item4' などの要素も引き続き処理されます。しかし、例外をスローした 'error_node' 自体は子を持たないものと見なされるため、その子孫である 'subitem3b' は表示されません。この機能は、ツリー構造の一部に問題があっても全体の走査を中断せず、問題のある部分を単にスキップして処理を続けたい場合に非常に役立ちます。