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

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * 内部に配列データを持ち、それを文字列として表現する責務を持つクラス
7 *
8 * このクラスは、オブジェクトが文字列として評価されるコンテキスト（例: echo）で
9 * 使用された場合に、__toString() メソッドを自動的に呼び出します。
10 */
11class DataHolder
12{
13    /**
14     * @param string $name データ名
15     * @param array<int, string> $items 保持する配列データ
16     */
17    public function __construct(
18        private string $name,
19        private array $items
20    ) {
21    }
22
23    /**
24     * オブジェクトを文字列に変換するマジックメソッド
25     *
26     * このオブジェクトが持つ配列データを、人間が読みやすい形式の
27     * 文字列に変換して返します。
28     *
29     * @return string オブジェクトの文字列表現
30     */
31    public function __toString(): string
32    {
33        // 配列の要素をカンマで連結して一つの文字列にする
34        $itemsString = implode(', ', $this->items);
35
36        // データ名と連結した配列文字列を返す
37        return "{$this->name}: [{$itemsString}]";
38    }
39}
40
41// サンプルとなる配列データを作成
42$userPermissions = ['read', 'write', 'execute'];
43
44// DataHolderクラスのインスタンスを生成し、配列を渡す
45$data = new DataHolder('UserPermissions', $userPermissions);
46
47// インスタンスを直接 echo すると、__toString() メソッドが自動的に呼び出される
48echo $data . PHP_EOL;
49
50// 出力結果:
51// UserPermissions: [read, write, execute]
52

このPHPサンプルコードは、オブジェクトを文字列として扱う際に自動的に呼び出される特殊なメソッド__toStringの使用例を示しています。

DataHolderクラスは、名前($name)と配列データ($items)をプロパティとして保持します。このクラスに定義された__toStringメソッドは、オブジェクトが文字列として評価される場面、例えばechoで出力しようとした際に自動的に実行されます。

メソッド内部では、まずPHPの組み込み関数implodeを使い、コンストラクタで受け取った配列の全要素をカンマで連結し、一つの文字列に変換します。その後、データ名と整形された配列の文字列を結合し、「UserPermissions: [read, write, execute]」という形式の、人間にとって読みやすい文字列を生成します。

この__toStringメソッドは引数を受け取りません。戻り値としては、必ずstring型（文字列）を返す必要があります。サンプルコードの最後でecho $data;と記述するだけで、このメソッドが呼び出され、オブジェクトが持つ配列データが整形された文字列として出力されます。これにより、複雑なデータ構造を持つオブジェクトでも、その内容を簡単に文字列として表現できるようになります。

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * 書籍情報を表現するクラス
7 *
8 * このクラスは、オブジェクトが文字列として評価される際に
9 * どのように表現されるべきかを定義する __toString() メソッドを実装しています。
10 * これは、他の言語における "toString" メソッドと同等の機能を提供します。
11 */
12class Book
13{
14    /**
15     * コンストラクタ
16     * PHP 8 のコンストラクタ・プロパティ・プロモーションを利用しています。
17     *
18     * @param string $title 書籍のタイトル
19     * @param string $author 著者名
20     */
21    public function __construct(
22        public readonly string $title,
23        public readonly string $author
24    ) {
25    }
26
27    /**
28     * オブジェクトを文字列に変換するマジックメソッド
29     *
30     * このオブジェクトのインスタンスを echo や print で出力しようとしたり、
31     * 文字列と連結しようとしたりすると、このメソッドが自動的に呼び出されます。
32     *
33     * @return string このオブジェクトを表現する文字列
34     */
35    public function __toString(): string
36    {
37        return "『{$this->title}』著：{$this->author}";
38    }
39}
40
41// Book クラスのインスタンス（オブジェクト）を作成します。
42$book = new Book('PHP実践入門', 'システムエンジニア');
43
44// オブジェクトを直接 echo すると、__toString() メソッドが呼び出されます。
45echo $book . PHP_EOL;
46
47// 文字列への明示的なキャストでも、__toString() が呼び出されます。
48$stringRepresentation = (string) $book;
49echo $stringRepresentation . PHP_EOL;
50
51// 文字列コンテキストで使用された場合も同様です。
52$message = "おすすめの書籍は {$book} です。";
53echo $message . PHP_EOL;
54
55?>

PHPの__toString()メソッドは、オブジェクトを文字列として扱おうとした際に、そのオブジェクトがどのように文字列で表現されるかを定義するための特殊なメソッドです。これは「マジックメソッド」の一種で、特定の状況でPHPによって自動的に呼び出されます。このメソッドは引数を取らず、戻り値として必ずstring型の値を返す必要があります。この戻り値が、そのオブジェクトを代表する文字列となります。

サンプルコードのBookクラスでは、__toString()メソッドが実装されており、書籍のタイトルと著者名を組み合わせた文字列を返すように定義されています。そのため、Bookクラスから作成されたオブジェクトをechoで直接出力しようとしたり、(string)を用いて明示的に文字列へ変換（キャスト）したり、ダブルクォーテーションで囲まれた文字列の中に埋め込んだりすると、この__toString()メソッドが自動的に実行されます。その結果、メソッド内で定義された「『（タイトル）』著：（著者名）」という形式の文字列が得られます。

この機能は、JavaにおけるtoString()メソッドなど、他の多くのプログラミング言語に見られるものと同等で、オブジェクトのデバッグやログ出力時に、その内容を人間が読みやすい形式で確認するのに役立ちます。