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

Copy
1<?php
2
3/**
4 * RecursiveTreeIterator::BYPASS_KEY の使用例を示す関数。
5 *
6 * RecursiveTreeIterator は、再帰的なデータ構造（例えば、ネストされた配列やディレクトリ構造）
7 * を線形にイテレートし、視覚的なツリー形式で出力するのに役立つイテレータです。
8 *
9 * RecursiveTreeIterator::BYPASS_KEY 定数は、このイテレータがツリーの要素を整形して出力する際に、
10 * キー（配列のインデックスなど）をその出力に含めるかどうかを制御するフラグです。
11 * このフラグを指定すると、ツリー表示からキー情報が除外されます。
12 *
13 * このサンプルコードでは、ネストされた配列をツリー形式で表示し、
14 * BYPASS_KEY の有無によって出力されるキーの情報がどのように変化するかを示します。
15 */
16function demonstrateRecursiveTreeIteratorBypassKey(): void
17{
18    // ツリー構造を模倣するネストされた配列データを用意
19    $data = [
20        'fruits' => [
21            'apple' => 'Red',
22            'banana' => 'Yellow',
23            'grape' => 'Purple',
24        ],
25        'vegetables' => [
26            'carrot' => 'Orange',
27            'potato' => 'Brown',
28        ],
29        'dairy' => 'Milk',
30    ];
31
32    // --- RecursiveTreeIterator::BYPASS_KEY なしの場合 ---
33    echo "--- RecursiveTreeIterator::BYPASS_KEY なしの場合 ---\n";
34    echo "（ツリー表示にキー（'apple', 'carrot'など）が含まれます）\n";
35    echo "----------------------------------------------------\n";
36
37    // 1. RecursiveArrayIterator を使用して、配列を再帰的にイテレート可能にする
38    $recursiveIterator = new RecursiveArrayIterator($data);
39
40    // 2. RecursiveTreeIterator を使用して、ツリー構造でデータを表示するためのイテレータを作成
41    //    コンストラクタの第2引数にフラグを指定しない場合、またはBYPASS_KEYを含めない場合、
42    //    デフォルトでキー情報も出力されます。
43    $treeIteratorDefault = new RecursiveTreeIterator($recursiveIterator);
44
45    // 3. イテレータをループしてツリー構造を出力
46    //    各 $entry は、整形されたツリーの行（キーと値を含む）を表します。
47    foreach ($treeIteratorDefault as $entry) {
48        echo $entry . "\n";
49    }
50
51    echo "\n\n"; // 出力を見やすくするための改行
52
53    // --- RecursiveTreeIterator::BYPASS_KEY を使用した場合 ---
54    echo "--- RecursiveTreeIterator::BYPASS_KEY を使用した場合 ---\n";
55    echo "（ツリー表示からキー情報が除外されます）\n";
56    echo "------------------------------------------------\n";
57
58    // 1. 再び RecursiveArrayIterator を作成
59    $recursiveIterator = new RecursiveArrayIterator($data);
60
61    // 2. RecursiveTreeIterator のコンストラクタに BYPASS_KEY フラグを指定
62    //    これにより、ツリー表示時にキー情報がスキップされ、値のみが表示されます。
63    $treeIteratorBypassKey = new RecursiveTreeIterator(
64        $recursiveIterator,
65        RecursiveTreeIterator::BYPASS_KEY
66    );
67
68    // 3. イテレータをループしてツリー構造を出力
69    //    BYPASS_KEY の効果により、各 $entry にキー情報は含まれません。
70    foreach ($treeIteratorBypassKey as $entry) {
71        echo $entry . "\n";
72    }
73}
74
75// 関数を実行して、BYPASS_KEY の効果を示す
76demonstrateRecursiveTreeIteratorBypassKey();

PHP 8のRecursiveTreeIterator::BYPASS_KEY定数は、ネストされた配列やディレクトリ構造のような再帰的なデータを、視覚的に分かりやすいツリー形式で出力する際に、その表示内容を制御するためのフラグです。RecursiveTreeIteratorは、こうした複雑なデータを効率的にイテレートし、ツリー状に整形する機能を提供しますが、この定数はツリーの各要素に付随する「キー」（配列のインデックスなど）を出力に含めるかどうかを決定します。

この定数自体には引数はなく、内部的には整数値が戻り値として定義されています。RecursiveTreeIteratorのコンストラクタにRecursiveTreeIterator::BYPASS_KEYを渡すことで、ツリー表示からキー情報が除外され、値のみがシンプルに表示されるようになります。

サンプルコードでは、ネストされた配列データを使い、BYPASS_KEYを使用しない場合と使用した場合の出力の違いを具体的に示しています。BYPASS_KEYを指定しない場合、出力されるツリーには要素のキーも含まれますが、BYPASS_KEYを指定した場合は、キー情報が省略され、値だけが表示されます。これにより、データの視覚的な表現をより簡潔にし、必要な情報のみを強調することが可能となります。

Copy
1<?php
2
3/**
4 * SkippingRecursiveArrayIterator は、指定されたキーの子孫をスキップするRecursiveFilterIteratorの実装です。
5 * RecursiveTreeIteratorと組み合わせて、BYPASS_KEYの動作を示します。
6 */
7class SkippingRecursiveArrayIterator extends RecursiveFilterIterator
8{
9    private string $skipKey;
10
11    public function __construct(RecursiveIterator $iterator, string $skipKey)
12    {
13        parent::__construct($iterator);
14        $this->skipKey = $skipKey;
15    }
16
17    /**
18     * 全ての要素をイテレーションに含めます。
19     */
20    public function accept(): bool
21    {
22        return true;
23    }
24
25    /**
26     * 現在の要素が子要素を持つべきかを判定します。
27     * 特定のキーの場合、子孫のイテレーションをスキップします。
28     */
29    public function hasChildren(): bool
30    {
31        // 指定されたキーの子孫はスキップします。
32        // getInnerIterator() を使うことで、ラップしているイテレータのキーを評価します。
33        if ($this->getInnerIterator()->key() === $this->skipKey) {
34            return false; // 子孫をスキップ
35        }
36        return parent::hasChildren();
37    }
38
39    /**
40     * 子イテレータを返します。
41     * 再帰的にこのフィルタリングを適用するために、自身をラップして返します。
42     */
43    public function getChildren(): self
44    {
45        return new self($this->getInnerIterator()->getChildren(), $this->skipKey);
46    }
47}
48
49/**
50 * RecursiveTreeIterator::BYPASS_KEY を使用して、特定のキーの子孫がスキップされた状態を示すサンプルコード。
51 *
52 * BYPASS_KEY は、RecursiveTreeIteratorが子孫のイテレーションをスキップした際に適用される
53 * 特別なPostfixを設定するために使用される定数です。
54 * これにより、通常のキー生成プロセスが「バイパス」された状態を視覚的に確認できます。
55 */
56function demonstrateRecursiveTreeIteratorBypassKey(): void
57{
58    // ツリー構造を模倣するデータ。
59    // この例では 'folder2' の子孫がスキップされるように設定します。
60    $data = [
61        'item1',
62        'folder1' => [
63            'item2',
64            'item3'
65        ],
66        'folder2' => [ // このキーの子孫はスキップされます。
67            'item4',
68            'folder3' => [
69                'item5'
70            ]
71        ],
72        'item6'
73    ];
74
75    // データの再帰的イテレータを作成
76    $recursiveArrayIterator = new RecursiveArrayIterator($data);
77
78    // 特定のキー('folder2')の子孫をスキップするフィルタを適用
79    $skippingIterator = new SkippingRecursiveArrayIterator($recursiveArrayIterator, 'folder2');
80
81    // ツリー形式で出力するためのイテレータを作成
82    $treeIterator = new RecursiveTreeIterator($skippingIterator);
83
84    // RecursiveTreeIterator::BYPASS_KEY 定数を使用して、
85    // 子孫がスキップされた場合に表示されるPostfixを設定します。
86    // これは、通常のイテレーションにおけるキー生成が「バイパス」された状態を示します。
87    $treeIterator->setPostfix(' [CHILDREN SKIPPED]', RecursiveTreeIterator::BYPASS_KEY);
88
89    echo "--- ツリー構造のイテレーション結果 ---\n";
90    foreach ($treeIterator as $value) {
91        echo $value . "\n";
92    }
93    echo "--------------------------------------\n";
94}
95
96// サンプルコードを実行
97demonstrateRecursiveTreeIteratorBypassKey();

PHPのRecursiveTreeIterator::BYPASS_KEYは、ツリー構造をイテレート（繰り返し処理）する際に使用される定数で、整数型（int）の値を持ちます。この定数はRecursiveTreeIteratorクラスのsetPostfix()メソッドと組み合わせて用いられ、子要素のイテレーションが意図的にスキップされた場合に表示される特別な接尾辞（Postfix）を設定するための目印として機能します。

これにより、ツリー構造の通常のキー生成プロセスが「バイパス」（迂回）された状態を視覚的に示すことができます。定数であるため引数はなく、特定の整数値を返します。

サンプルコードでは、SkippingRecursiveArrayIteratorという独自のイテレータを使って、データ内の「folder2」キー以下の子孫要素をスキップするように設定しています。その上で、RecursiveTreeIteratorのsetPostfix()メソッドにRecursiveTreeIterator::BYPASS_KEYを指定し、「 [CHILDREN SKIPPED]」という接尾辞を設定しています。これにより、イテレーション結果では「folder2 [CHILDREN SKIPPED]」のように表示され、この部分の子要素が処理されずにスキップされたことを明確に確認できます。これは、特定の条件下でツリーの一部を意図的に表示しない場合に、処理の状態を分かりやすく伝えるために利用されます。