【PHP8.x】__toStringメソッドの使い方

Copy
1<?php
2
3/**
4 * このサンプルコードは、PHPの特殊メソッドである__toStringの働きと、
5 * その中で配列データをどのように文字列として表現するかを示します。
6 * また、DateMalformedPeriodStringExceptionクラスの__toStringメソッドの動作も確認します。
7 *
8 * __toStringメソッドは、オブジェクトが文字列として扱われる際に自動的に呼び出され、
9 * オブジェクトの状態を表現する文字列を返すために使用されます。
10 */
11
12// 1. DateMalformedPeriodStringException の __toString メソッドの動作を確認
13try {
14    // 不正な期間文字列を DatePeriod コンストラクタに渡し、意図的に例外を発生させます。
15    // 例: "P" は "P1Y2M3D" のように数字と単位が続く必要があるため不正です。
16    new DatePeriod('P');
17} catch (DateMalformedPeriodStringException $e) {
18    // 捕捉した例外オブジェクトを文字列コンテキストで利用すると、
19    // DateMalformedPeriodStringException クラスに定義された __toString() メソッドが自動的に呼び出されます。
20    // これにより、例外の詳細情報が文字列として出力されます。
21    echo "DateMalformedPeriodStringException の情報: " . $e . "\n\n";
22}
23
24/**
25 * 2. カスタムクラスで __toString メソッドを実装し、
26 *    内部に持つ配列データを文字列として表現する方法を示します。
27 *    これはキーワード「php tostring array」に関連する一般的なユースケースです。
28 */
29class MyDataContainer
30{
31    private string $name;
32    private array $items;
33
34    /**
35     * コンストラクタ
36     *
37     * @param string $name コンテナの名前
38     * @param array $items コンテナが持つアイテムの配列
39     */
40    public function __construct(string $name, array $items)
41    {
42        $this->name = $name;
43        $this->items = $items;
44    }
45
46    /**
47     * オブジェクトが文字列として扱われる際に自動的に呼び出されるマジックメソッド。
48     * オブジェクトの現在の状態を読みやすい文字列形式で返します。
49     *
50     * 内部の配列データを implode() 関数を使ってカンマ区切りの文字列に変換することで、
51     * 配列の内容も文字列表現に含めることができます。
52     *
53     * @return string オブジェクトの文字列表現
54     */
55    public function __toString(): string
56    {
57        // 内部の配列 ($this->items) をカンマ区切りの文字列に変換します。
58        // 配列を直接文字列にキャストしようとするとエラーになるため、implode() などを使って明示的に変換します。
59        $itemsString = implode(', ', $this->items);
60        return "データコンテナ名: '{$this->name}', アイテム: [{$itemsString}]";
61    }
62}
63
64// MyDataContainer クラスのインスタンスを作成します。
65$container = new MyDataContainer('商品リスト', ['りんご', 'バナナ', 'オレンジ']);
66
67// オブジェクトを文字列コンテキスト（echo文など）で利用すると、
68// MyDataContainer クラスに定義された __toString() メソッドが自動的に呼び出されます。
69// これにより、オブジェクトが保持する名前と配列の内容が文字列として出力されます。
70echo "カスタムオブジェクトの情報: " . $container . "\n";

PHPの__toStringメソッドは、オブジェクトが文字列として扱われる際に自動的に呼び出される特殊メソッドです。これは、オブジェクトの現在の状態を人間が読みやすい文字列として表現するために使用されます。

DateMalformedPeriodStringExceptionクラスは、DatePeriodのコンストラクタなどで不正な期間文字列が指定された場合に発生する例外です。この例外クラスに定義された__toStringメソッドは、例外オブジェクトが文字列コンテキストで利用された際に、エラーメッセージやファイル、行番号といった詳細情報を文字列として返します。このメソッドは引数を取らず、例外の詳細を含むstring型の戻り値を持ちます。

開発者が独自に作成するクラスでも__toStringを実装できます。例えば、クラスが内部に配列データを保持している場合、__toStringメソッド内でimplode()関数などを使って配列要素を明示的にカンマ区切りなどの文字列に変換することで、配列の内容をオブジェクトの文字列表現に含めることが可能です。これにより、オブジェクトが持つ全ての情報を分かりやすい文字列形式で出力できるようになります。

Copy
1<?php
2
3/**
4 * オブジェクトが文字列として扱われる際に自動的に呼び出される __toString() メソッドの例。
5 * DateMalformedPeriodStringException を捕捉し、その内容を文字列として出力します。
6 */
7class ToStringExample
8{
9    /**
10     * DateMalformedPeriodStringException を意図的に発生させ、
11     * __toString() の動作を確認します。
12     */
13    public static function demonstrate(): void
14    {
15        try {
16            // 不正な形式の期間文字列を DatePeriod のコンストラクタに渡します。
17            // これにより DateMalformedPeriodStringException がスローされます。
18            new DatePeriod('invalid iso 8601 period string');
19        } catch (DateMalformedPeriodStringException $e) {
20            // catchブロックで例外オブジェクトを捕捉します。
21
22            // 例外オブジェクトを echo すると、マジックメソッド __toString() が自動的に呼び出されます。
23            // これにより、例外情報が人間が読める形式の文字列として出力されます。
24            // これは、他の言語における toString() メソッドの呼び出しに相当します。
25            echo $e;
26        }
27    }
28}
29
30ToStringExample::demonstrate();

DateMalformedPeriodStringExceptionクラスの__toString()メソッドについて解説します。これは、オブジェクトを文字列として扱おうとした際に、PHPが自動的に呼び出す特別なメソッド（マジックメソッド）です。このメソッドは引数を受け取らず、戻り値として例外情報を整形した文字列（string）を返します。

サンプルコードでは、new DatePeriod()にわざと不正な形式の期間文字列を渡すことで、DateMalformedPeriodStringExceptionを意図的に発生させています。try-catch構文でこの例外オブジェクト$eを捕捉し、echoを使って出力しようとしています。オブジェクトである$eをechoで直接出力しようとすると、PHPは内部で自動的に$e->__toString()を呼び出し、その戻り値である文字列を表示します。

これにより、例外のメッセージ、発生したファイル名、行番号などを含む、人間が読んで理解しやすい形式の情報が出力されます。この機能は、他の多くのプログラミング言語におけるtoString()メソッドと同様の役割を果たし、デバッグ時に例外の詳細を簡単に確認するのに役立ちます。