【PHP8.x】SplStack::__debugInfo()メソッドの使い方

Copy
1<?php
2
3/**
4 * SplStack を継承し、オブジェクトのデバッグ情報表示をカスタマイズするクラスです。
5 * __debugInfo() マジックメソッドを実装することで、var_dump() などのデバッグ関数が
6 * オブジェクトの内部状態をより分かりやすく表示するように制御できます。
7 */
8class MyDebuggableStack extends SplStack
9{
10    /**
11     * スタックの識別のための名前です。
12     *
13     * @var string
14     */
15    private string $stackName;
16
17    /**
18     * MyDebuggableStack の新しいインスタンスを生成します。
19     *
20     * @param string $name このスタックインスタンスに割り当てる名前
21     */
22    public function __construct(string $name = 'Unnamed Stack')
23    {
24        parent::__construct();
25        $this->stackName = $name;
26    }
27
28    /**
29     * オブジェクトが var_dump() や print_r() でデバッグ出力される際に呼び出されます。
30     * このメソッドが返す連想配列が、オブジェクトのデバッグ情報として表示されます。
31     *
32     * @return array デバッグ情報として表示される連想配列
33     */
34    public function __debugInfo(): array
35    {
36        // SplStackの要素をイテレータとして取得し、配列に変換します。
37        // SplStackはLIFO (後入れ先出し) のため、イテレータは最新の要素から順に返します。
38        $elements = iterator_to_array($this, false);
39
40        // カスタムのデバッグ情報を定義して返します。
41        return [
42            'stackName' => $this->stackName, // このスタックに割り当てた名前
43            'count' => $this->count(),       // 現在の要素数
44            'isEmpty' => $this->isEmpty(),   // スタックが空かどうか
45            'elements' => $elements,         // スタック内の全要素 (最新の要素から順)
46            // 必要に応じて、さらに詳細な情報を追加できます
47        ];
48    }
49}
50
51// --- サンプルコードの実行例 ---
52
53// 1. MyDebuggableStack (カスタムデバッグ情報を持つスタック) の動作確認
54$myStack = new MyDebuggableStack("Important Tasks");
55$myStack->push("Task A: Prepare presentation");
56$myStack->push("Task B: Review code");
57$myStack->push("Task C: Write report");
58
59echo "--- MyDebuggableStack (カスタムデバッグ情報) ---\n";
60// var_dump() を使用して、オブジェクトのデバッグ情報を表示します。
61// __debugInfo() メソッドが呼び出され、カスタマイズされた情報が表示されます。
62var_dump($myStack);
63
64// 2. 空の MyDebuggableStack の動作確認
65$emptyStack = new MyDebuggableStack("Empty Task List");
66echo "\n--- MyDebuggableStack (空の状態) ---\n";
67var_dump($emptyStack);
68
69// 3. 標準の SplStack (__debugInfo() がない場合) との比較
70// 標準の SplStack は、継承元である SplDoublyLinkedList の内部表現を直接表示します。
71$standardStack = new SplStack();
72$standardStack->push("Standard Item 1");
73$standardStack->push("Standard Item 2");
74
75echo "\n--- SplStack (標準デバッグ情報) ---\n";
76var_dump($standardStack);
77
78?>

このサンプルコードは、PHPの特殊なメソッドである__debugInfo()の使い方を示しています。__debugInfo()は「マジックメソッド」と呼ばれ、オブジェクトがvar_dump()やprint_r()といったデバッグ関数によって出力される際に自動的に呼び出される仕組みです。このメソッドをクラス内に実装することで、オブジェクトの内部状態がデバッグ関数で表示される情報を、開発者にとってより分かりやすい形にカスタマイズできます。

__debugInfo()メソッドは引数を取りません。戻り値として連想配列（array）を返す必要があり、この配列のキーと値が、デバッグ出力時にオブジェクトのプロパティとして表示される内容となります。

サンプルコードでは、PHP標準のスタッククラスSplStackを継承したMyDebuggableStackクラスを作成し、この__debugInfo()を実装しています。通常、SplStackをvar_dump()すると内部構造が複雑に表示されますが、MyDebuggableStackでは、__debugInfo()メソッド内でスタックの名前、現在の要素数、空かどうか、そしてスタックに含まれる要素のリストを整形した連想配列を生成して返しています。これにより、var_dump($myStack)を実行した際に、オブジェクトの重要な情報が一目で理解できる形式で出力されるようになります。標準のSplStackのデバッグ出力と比較することで、__debugInfo()によるカスタマイズの効果が明確に確認できます。

Copy
1<?php
2
3/**
4 * SplStack を継承したカスタムスタッククラス。
5 * このクラスは、__debugInfo マジックメソッドの実装例を示します。
6 */
7class MyCustomStack extends SplStack
8{
9    private string $purpose; // このスタックの目的を保持するカスタムプロパティ
10    private int $maxSize;   // スタックの最大サイズ（任意で設定）
11
12    /**
13     * コンストラクタ。
14     *
15     * @param string $purpose このスタックの目的
16     * @param int $maxSize スタックの最大サイズ。-1は無制限を意味します。
17     */
18    public function __construct(string $purpose, int $maxSize = -1)
19    {
20        $this->purpose = $purpose;
21        $this->maxSize = $maxSize;
22        // SplStack のコンストラクタは特に呼び出す必要はありません。
23    }
24
25    /**
26     * オブジェクトのデバッグ情報をカスタマイズするマジックメソッド。
27     * var_dump() などの関数でオブジェクトがダンプされる際に呼び出され、
28     * 何をどのように表示するかを制御できます。
29     *
30     * @return array デバッグ情報として表示したいプロパティの連想配列。
31     *               ここで返される情報が var_dump の出力となります。
32     */
33    public function __debugInfo(): array
34    {
35        return [
36            'type' => 'MyCustomStack (SplStackを拡張)', // クラスのタイプを明示
37            'purpose' => $this->purpose,             // カスタムプロパティの表示
38            'currentSize' => $this->count(),         // SplStackの現在の要素数
39            'maxSize' => $this->maxSize,             // 設定された最大サイズ
40            'isEmpty' => $this->isEmpty(),           // スタックが空かどうか
41            // 必要に応じて、スタックの他の情報も追加できます。
42            // 例: 'topElement' => $this->isEmpty() ? null : $this->top(),
43        ];
44    }
45}
46
47// --- サンプル使用例 ---
48
49echo "--- MyCustomStackのデバッグ情報 (初期状態) ---" . PHP_EOL;
50
51// MyCustomStack のインスタンスを作成
52$myStack = new MyCustomStack("一時的なデータ処理", 10);
53
54// var_dump() を使用してオブジェクトのデバッグ情報を表示
55// __debugInfo メソッドが定義されているため、その戻り値が表示されます。
56var_dump($myStack);
57
58echo PHP_EOL . "--- スタック操作後 ---" . PHP_EOL;
59
60// スタックに要素を追加
61$myStack->push("第一データ");
62$myStack->push(123);
63$myStack->push(["status" => "処理中"]);
64
65// 要素を追加した後、再度 var_dump() でデバッグ情報を表示
66// currentSize などの情報が更新されていることがわかります。
67var_dump($myStack);
68
69// --- __debugInfo メソッドの直接呼び出し (稀なケース) ---
70// 通常は var_dump() などによって自動的に呼び出されますが、
71// メソッドの戻り値そのものを確認したい場合に直接呼び出すことも可能です。
72echo PHP_EOL . "--- __debugInfo メソッドの直接呼び出し結果 ---" . PHP_EOL;
73print_r($myStack->__debugInfo());
74
75?>

__debugInfoは、PHP 8で利用可能なマジックメソッドで、オブジェクトのデバッグ情報をカスタマイズするために使用されます。このメソッドは、var_dump()などの関数がオブジェクトをダンプする際に自動的に呼び出されます。

主な役割は、オブジェクトの内部状態を開発者にとってより分かりやすい形で表示することです。通常、var_dump()はオブジェクトのすべてのプロパティを表示しますが、__debugInfoを実装することで、プライベートなプロパティを隠蔽したり、計算された情報（例：SplStackの現在の要素数）を含めたりと、表示内容を自由に制御できます。これにより、オブジェクトの複雑な内部構造を簡潔に表現し、必要な情報だけを効率的に確認できるようになります。

このメソッドは引数を取りません。戻り値は連想配列で、この配列のキーと値がデバッグ情報として表示されます。サンプルコードでは、MyCustomStackクラスが__debugInfoを実装し、スタックのタイプ、目的、現在の要素数、最大サイズといったカスタム情報を整理して表示しています。これにより、var_dump()の出力がより直感的で有益なものになります。