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

Copy
1<?php
2
3/**
4 * 遅延ロードされるリソースの例。
5 * 初期化に時間がかかることをシミュレートするため、sleep() を使用します。
6 */
7class HeavyResource
8{
9    private string $name;
10
11    public function __construct(string $name)
12    {
13        // 初期化に時間がかかる処理をシミュレート
14        sleep(1);
15        echo "DEBUG: HeavyResource '{$name}' が初期化されました。\n";
16        $this->name = $name;
17    }
18
19    /**
20     * リソースが提供する機能の例。
21     *
22     * @return string
23     */
24    public function doSomething(): string
25    {
26        return "ACTION: HeavyResource '{$this->name}' が何かをしました。\n";
27    }
28}
29
30echo "--- プロキシ作成前 ---\n";
31
32// ReflectionClass のインスタンスを作成し、遅延ロードしたいクラスを指定します。
33$reflector = new ReflectionClass(HeavyResource::class);
34
35// newLazyProxy メソッドを使用してプロキシオブジェクトを作成します。
36// $factory 引数には、プロキシのメソッドが初めて呼び出されたときに
37// 実際のオブジェクトを生成する callable (クロージャ) を渡します。
38// この時点ではまだ HeavyResource の __construct() は実行されません。
39$lazyResource = $reflector->newLazyProxy(function (): HeavyResource {
40    echo "DEBUG: HeavyResource を生成するためのファクトリ関数が実行されました。\n";
41    return new HeavyResource('重要なデータ');
42});
43
44echo "--- プロキシオブジェクト作成済み。HeavyResource はまだ初期化されていません。 ---\n";
45
46// ここで初めてプロキシオブジェクトのメソッドが呼び出されます。
47// この瞬間に、$factory で指定したクロージャが実行され、
48// HeavyResource のインスタンスが生成され、その後メソッド呼び出しがそのインスタンスに転送されます。
49echo $lazyResource->doSomething();
50
51echo "--- HeavyResource が初期化され、メソッドが実行されました。 ---\n";
52
53// 2回目以降のメソッド呼び出しでは、ファクトリ関数は再度実行されず、
54// 既に生成された HeavyResource インスタンスのメソッドが直接呼び出されます。
55echo $lazyResource->doSomething();
56
57echo "--- 全ての処理が完了しました。 ---\n";

ReflectionClass::newLazyProxyは、PHP 8で導入されたメソッドで、初期化に時間やリソースを要するオブジェクトの生成を、実際にそのオブジェクトが必要になるまで遅らせる「遅延ロード（Lazy Load）」を実現するために使用されます。

このメソッドは、指定されたクラスのインスタンスを直接生成する代わりに、そのクラスの「代理（プロキシ）」オブジェクトを生成します。引数$factoryには、プロキシオブジェクトのメソッドが初めて呼び出されたときに、実際のオブジェクトを生成するための関数（callable）を渡します。この工場関数は、実際に必要とされるまで実行されないため、不要なリソースの消費を防ぐことができます。

戻り値は、元のクラスのメソッドを呼び出すことができるプロキシオブジェクトです。このプロキシオブジェクトのメソッドが初めて呼び出されると、内部で$factoryが実行されて実際のオブジェクトが生成され、その後、呼び出しはその実際のオブジェクトに転送されます。

サンプルコードでは、初期化に時間がかかるHeavyResourceクラスを例に、newLazyProxyを使ってプロキシオブジェクトを作成しています。プロキシ作成時点ではHeavyResourceのコンストラクタは実行されません。その後、$lazyResource->doSomething()が初めて呼び出された際に初めて$factoryが実行され、HeavyResourceが初期化されてメソッドが実行されます。2回目以降の呼び出しでは、すでに生成されたインスタンスが利用されるため、$factoryは再実行されません。このように、必要な時まで初期化を待つことで、アプリケーションのパフォーマンス向上やリソース効率化が期待できます。

Copy
1<?php
2
3/**
4 * New Relic API の操作を模倣するクラス。
5 * 実際には New Relic の PHP エージェント関数（例: newrelic_record_metric()）を呼び出すことを想定しています。
6 * このクラスのインスタンス生成を ReflectionClass::newLazyProxy を使って遅延させます。
7 */
8class NewRelicApiManager
9{
10    public function __construct()
11    {
12        // インスタンスが生成されたことを示すメッセージ
13        echo "[NewRelicApiManager]: インスタンスが生成されました。\n";
14    }
15
16    /**
17     * 指定された名前と値でメトリックを記録する操作を模倣します。
18     *
19     * @param string $metricName 記録するメトリックの名前
20     * @param float  $value      記録する値
21     */
22    public function recordMetric(string $metricName, float $value): void
23    {
24        echo "[NewRelicApiManager]: メトリック '{$metricName}' に値 '{$value}' を記録しました。\n";
25        // 実際には newrelic_record_metric($metricName, $value); のような呼び出しが行われます。
26    }
27
28    /**
29     * 指定されたキーと値でカスタムパラメータを追加する操作を模倣します。
30     *
31     * @param string $key   カスタムパラメータのキー
32     * @param string $value カスタムパラメータの値
33     */
34    public function addCustomParameter(string $key, string $value): void
35    {
36        echo "[NewRelicApiManager]: カスタムパラメータ '{$key}' = '{$value}' を追加しました。\n";
37        // 実際には newrelic_add_custom_parameter($key, $value); のような呼び出しが行われます。
38    }
39}
40
41// --- ReflectionClass::newLazyProxy の使用例 ---
42
43// NewRelicApiManager クラスの ReflectionClass インスタンスを取得します。
44$reflector = new ReflectionClass(NewRelicApiManager::class);
45
46echo "--- プロキシオブジェクト生成前 ---\n";
47
48// ReflectionClass::newLazyProxy を使用して、NewRelicApiManager の「プロキシオブジェクト」を生成します。
49// 第1引数の callable（無名関数）は「ファクトリ関数」と呼ばれ、
50// このプロキシオブジェクトのメソッドが初めて呼び出されたときにだけ実行され、
51// 実際の NewRelicApiManager インスタンスを生成します。
52$newRelicProxy = $reflector->newLazyProxy(function () {
53    echo "[newLazyProxy]: ファクトリ関数が実行され、実際の NewRelicApiManager オブジェクトを生成中...\n";
54    return new NewRelicApiManager();
55});
56
57echo "--- プロキシオブジェクト生成後 ---\n\n";
58
59echo "--- プロキシのメソッドを呼び出す (初めての呼び出し) ---\n";
60// ここで初めて $newRelicProxy のメソッド (recordMetric) が呼び出されるため、
61// 上記で定義したファクトリ関数が実行され、NewRelicApiManager のインスタンスが生成されます。
62$newRelicProxy->recordMetric('Transactions/Web/Homepage', 1.0);
63
64echo "\n--- プロキシの別のメソッドを呼び出す (2回目以降の呼び出し) ---\n";
65// 既に NewRelicApiManager のインスタンスは生成されているため、
66// ファクトリ関数は再度実行されず、既存のインスタンスに処理が委譲されます。
67$newRelicProxy->addCustomParameter('user_id', 'some_unique_id_123');
68
69echo "\n--- プロキシのさらに別のメソッドを呼び出す ---\n";
70$newRelicProxy->recordMetric('Custom/ApiCall/Success', 10.0);
71
72?>

PHPのReflectionClass::newLazyProxyメソッドは、実際のオブジェクトの生成を必要となる瞬間まで遅らせる「プロキシオブジェクト」を作成するために使用されます。この機能は、アプリケーションの起動時間を短縮したり、使用頻度の低いオブジェクトが不必要にリソースを消費するのを防いだりする際に役立ちます。

第一引数には、実際のオブジェクトを生成する役割を持つ「ファクトリ関数」（callable型）を指定します。このファクトリ関数は、生成されたプロキシオブジェクトのメソッドが初めて呼び出されたときに一度だけ実行され、その結果として本物のオブジェクトが生成されます。第二引数の$optionsは追加設定のための整数値ですが、通常はデフォルトの0を使用します。

このメソッドが返す戻り値は、実際のオブジェクトと同じインターフェースを持つプロキシオブジェクトです。一度ファクトリ関数によって実際のオブジェクトが生成されると、その後のプロキシオブジェクトへのメソッド呼び出しは、全て内部で保持されている本物のオブジェクトに委譲されます。

サンプルコードでは、NewRelicApiManagerクラスのインスタンス生成をnewLazyProxyで遅延させています。New Relicのような監視ツール連携は、アプリケーションのライフサイクル全体で常に必要とされるわけではないため、この遅延ロードにより、初めて関連する操作が行われるまでリソースを節約できるという利点があります。