thinkstream

Once Props

一部のデータはほとんど変更されない、計算コストが高い、または単純にサイズが大きい場合があります。こうしたデータを毎回のレスポンスに含める代わりに、once props を使用できます。これらの props はクライアントによって記憶され、同じ prop を含む後続のページで再利用されます。そのため、共有データ に最適です。

Once Props の作成

once prop を作成するには、レスポンスを返す際に Inertia::once() メソッドを使用します。このメソッドは、prop データを返すコールバックを受け取ります。

php
return Inertia::render('Billing', [
    'plans' => Inertia::once(fn () => Plan::all()),
]);

クライアントがこの prop を受信すると、以降のリクエストではコールバックの解決がスキップされ、レスポンスから prop が除外されます。クライアントは、once prop を含むページ間をナビゲートしている間のみ、once prop を記憶します。

once prop を含まないページへ移動すると、記憶されていた値は破棄され、次にその prop を含むページで再度解決されます。実際には、once prop は通常共有データやアプリケーションの特定のセクション内で使用されるため、問題になることはほとんどありません。

強制的に更新する

fresh() メソッドを使用すると、once prop を強制的に更新できます。

php
return Inertia::render('Billing', [
    'plans' => Inertia::once(fn () => Plan::all())->fresh(),
]);

このメソッドは boolean も受け取り、条件付きで prop を更新できます。

php
return Inertia::render('Billing', [
    'plans' => Inertia::once(fn () => Plan::all())->fresh($condition),
]);

クライアントからの更新

クライアント側から パーシャルリロード を使用して once prop を更新できます。サーバーは、明示的に要求された場合は常に once prop を解決します。

有効期限

until() メソッドを使用して有効期限を設定できます。このメソッドは DateTimeInterface、DateInterval、または整数（秒）を受け取ります。有効期限を過ぎた後の次回訪問時に prop は更新されます。

php
return Inertia::render('Dashboard', [
    'rates' => Inertia::once(fn () => ExchangeRate::all())->until(now()->addDay()),
]);

カスタムキー

as() メソッドを使用して、prop にカスタムキーを割り当てることができます。これは、異なる prop 名を使いながら複数のページ間でデータを共有したい場合に便利です。

php
// チームメンバー一覧...
return Inertia::render('Team/Index', [
    'memberRoles' => Inertia::once(fn () => Role::all())->as('roles'),
]);

// 招待フォーム...
return Inertia::render('Team/Invite', [
    'availableRoles' => Inertia::once(fn () => Role::all())->as('roles'),
]);

両方のページは同じカスタムキーを使用しているため、同じ基盤データを共有します。その結果、最初に訪問したページでのみ prop が解決されます。

Once Props の共有

Inertia::share() メソッドを使用して、once prop をグローバルに共有できます。

php
Inertia::share('countries', Inertia::once(fn () => Country::all()));

または、利便性のために shareOnce() メソッドを使用することもできます。

php
Inertia::shareOnce('countries', fn () => Country::all());

shareOnce メソッドには、as()、fresh()、until() をチェーンすることも可能です。

php
Inertia::shareOnce('countries', fn () => Country::all())->until(now()->addDay());

さらに、ミドルウェア内に専用の shareOnce() メソッドを定義することもできます。ミドルウェアは share() と shareOnce() の両方を評価し、結果をマージします。

php
class HandleInertiaRequests extends Middleware
{
    public function shareOnce(Request $request): array
    {
        return array_merge(parent::shareOnce($request), [
            'countries' => fn () => Country::all(),
        ]);
    }
}

プリフェッチ

once prop は プリフェッチ と互換性があります。クライアントは、記憶されている once prop を自動的にプリフェッチされたレスポンスに含めるため、プリフェッチされたページに遷移すると、すでに once prop が利用可能な状態になります。

期限切れの once prop を含むプリフェッチされたページは、キャッシュから無効化されます。

他の Prop タイプとの組み合わせ

once() 修飾子は、deferred、merge、および optional props にチェーンできます。

php
return Inertia::render('Dashboard', [
    'permissions' => Inertia::defer(fn () => Permission::all())->once(),
    'activity' => Inertia::merge(fn () => $user->recentActivity())->once(),
    'categories' => Inertia::optional(fn () => Category::all())->once(),
]);