パッケージ - 予知（Precognition） - 《Laravel 11.x ドキュメント》日本語

はじめに
ライブ検証
検証ルールのカスタマイズ
ファイルアップロードの処理
副作用の管理
テスト

はじめに

Laravel Precognitionを使用すると、将来のHTTPリクエストの結果を予測できます。Precognitionの主な使用ケースの1つは、アプリケーションのバックエンドの検証ルールを重複させることなく、フロントエンドのJavaScriptアプリケーションに「ライブ」検証を提供できることです。Precognitionは、特にLaravelのInertiaベースのスターターキットと相性が良いです。

Laravelが「予知リクエスト」を受け取ると、すべてのルートのミドルウェアを実行し、ルートのコントローラ依存関係を解決します。これには、フォームリクエストの検証が含まれますが、実際にはルートのコントローラメソッドは実行されません。

ライブ検証

Vueの使用

Laravel Precognitionを使用すると、フロントエンドのVueアプリケーションで検証ルールを重複させることなく、ユーザーにライブ検証体験を提供できます。これがどのように機能するかを示すために、アプリケーション内で新しいユーザーを作成するためのフォームを作成しましょう。

まず、ルートに対してPrecognitionを有効にするには、HandlePrecognitiveRequestsミドルウェアをルート定義に追加する必要があります。また、ルートの検証ルールを格納するためのフォームリクエストを作成する必要があります：

use App\Http\Requests\StoreUserRequest;
use Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests;
Route::post('/users', function (StoreUserRequest $request) {
   // ...
})->middleware([HandlePrecognitiveRequests::class]);

次に、NPMを介してVue用のLaravel Precognitionフロントエンドヘルパーをインストールする必要があります：

npm install laravel-precognition-vue

Laravel Precognitionパッケージがインストールされたら、HTTPメソッド（post）、ターゲットURL（/users）、および初期フォームデータを提供して、PrecognitionのuseForm関数を使用してフォームオブジェクトを作成できます。

次に、ライブ検証を有効にするために、各入力のchangeイベントでフォームのvalidateメソッドを呼び出し、入力の名前を提供します：

<script setup>
import { useForm } from 'laravel-precognition-vue';
const form = useForm('post', '/users', {
   name: '',
   email: '',
});
const submit = () => form.submit();
</script>
<template>
   <form @submit.prevent="submit">
   <label for="name">Name</label>
   <input
   id="name"
   v-model="form.name"
   @change="form.validate('name')"
   />
   <div v-if="form.invalid('name')">
   {{ form.errors.name }}
   </div>
   <label for="email">Email</label>
   <input
   id="email"
   type="email"
   v-model="form.email"
   @change="form.validate('email')"
   />
   <div v-if="form.invalid('email')">
   {{ form.errors.email }}
   </div>
   <button :disabled="form.processing">
   Create User
   </button>
   </form>
</template>

ユーザーがフォームに入力すると、Precognitionはルートのフォームリクエストに基づいたライブ検証出力を提供します。フォームの入力が変更されると、デバウンスされた「予知」検証リクエストがLaravelアプリケーションに送信されます。デバウンスのタイムアウトは、フォームのsetValidationTimeout関数を呼び出すことで設定できます：

form.setValidationTimeout(3000);

検証リクエストが進行中の場合、フォームのvalidatingプロパティはtrueになります：

<div v-if="form.validating">
   Validating...
</div>

検証リクエストまたはフォーム送信中に返された検証エラーは、自動的にフォームのerrorsオブジェクトに入力されます：

<div v-if="form.invalid('email')">
   {{ form.errors.email }}
</div>

フォームにエラーがあるかどうかは、フォームのhasErrorsプロパティを使用して判断できます：

<div v-if="form.hasErrors">
   <!-- ... -->
</div>

入力が検証に合格したか失敗したかを判断するには、入力の名前をフォームのvalidおよびinvalid関数に渡します：

<span v-if="form.valid('email')">
   ✅
</span>
<span v-else-if="form.invalid('email')">
   ❌
</span>

フォーム入力は、変更され、検証応答が受信されるまで、有効または無効として表示されません。

Precognitionを使用してフォームの入力のサブセットを検証している場合、エラーを手動でクリアすることが役立つ場合があります。これを達成するには、フォームのforgetError関数を使用できます：

<input
   id="avatar"
   type="file"
   @change="(e) => {
   form.avatar = e.target.files[0]
   form.forgetError('avatar')
   }"
>

ご覧のとおり、入力のchangeイベントにフックして、ユーザーがそれらと対話する際に個々の入力を検証できます。ただし、ユーザーがまだ対話していない入力を検証する必要がある場合があります。これは、「ウィザード」を構築する際によく見られます。次のステップに進む前に、ユーザーが対話したかどうかにかかわらず、すべての表示されている入力を検証したいからです。

Precognitionを使用してこれを行うには、touchメソッドに名前を渡して、検証したいフィールドを「タッチ済み」としてマークする必要があります。その後、validateメソッドをonSuccessまたはonValidationErrorコールバックで呼び出します：

<button
   type="button"
   @click="form.touch(['name', 'email', 'phone']).validate({
   onSuccess: (response) => nextStep(),
   onValidationError: (response) => /* ... */,
   })"
>Next Step</button>

もちろん、フォーム送信の応答に反応してコードを実行することもできます。フォームのsubmit関数は、Axiosリクエストの約束を返します。これにより、応答ペイロードにアクセスしたり、成功した送信時にフォームの入力をリセットしたり、失敗したリクエストを処理したりする便利な方法が提供されます：

const submit = () => form.submit()
   .then(response => {
   form.reset();
   alert('User created.');
   })
   .catch(error => {
   alert('An error occurred.');
   });

フォーム送信リクエストが進行中かどうかは、フォームのprocessingプロパティを調べることで判断できます：

<button :disabled="form.processing">
   Submit
</button>

VueとInertiaの使用

VueとInertiaを使用してLaravelアプリケーションを開発する際に先手を打ちたい場合は、私たちのスターターキットの1つを使用することを検討してください。Laravelのスターターキットは、新しいLaravelアプリケーションのバックエンドおよびフロントエンドの認証スキャフォールディングを提供します。

VueとInertiaでPrecognitionを使用する前に、VueでのPrecognitionの使用に関する一般的なドキュメントを確認してください。VueをInertiaと一緒に使用する場合、NPMを介してInertia互換のPrecognitionライブラリをインストールする必要があります：

npm install laravel-precognition-vue-inertia

インストールが完了すると、PrecognitionのuseForm関数は、上記で説明した検証機能を強化したInertiaのフォームヘルパーを返します。

フォームヘルパーのsubmitメソッドは簡素化されており、HTTPメソッドやURLを指定する必要がなくなりました。代わりに、Inertiaの訪問オプションを最初の引数として渡すことができます。さらに、submitメソッドは、上記のReactの例で見られるようにPromiseを返しません。代わりに、submitメソッドに渡される訪問オプションで、Inertiaのサポートされているイベントコールバックのいずれかを提供できます：

<script setup>
import { useForm } from 'laravel-precognition-vue-inertia';
const form = useForm('post', '/users', {
   name: '',
   email: '',
});
const submit = () => form.submit({
   preserveScroll: true,
   onSuccess: () => form.reset(),
});
</script>

Reactの使用

Laravel Precognitionを使用すると、フロントエンドのReactアプリケーションで検証ルールを重複させることなく、ユーザーにライブ検証体験を提供できます。これがどのように機能するかを示すために、アプリケーション内で新しいユーザーを作成するためのフォームを作成しましょう。

use App\Http\Requests\StoreUserRequest;
use Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests;
Route::post('/users', function (StoreUserRequest $request) {
   // ...
})->middleware([HandlePrecognitiveRequests::class]);

次に、NPMを介してReact用のLaravel Precognitionフロントエンドヘルパーをインストールする必要があります：

npm install laravel-precognition-react

ライブ検証を有効にするには、各入力のchangeおよびblurイベントをリッスンする必要があります。changeイベントハンドラーでは、setData関数を使用してフォームのデータを設定し、入力の名前と新しい値を渡す必要があります。次に、blurイベントハンドラーでフォームのvalidateメソッドを呼び出し、入力の名前を提供します：

import { useForm } from 'laravel-precognition-react';
export default function Form() {
   const form = useForm('post', '/users', {
   name: '',
   email: '',
   });
   const submit = (e) => {
   e.preventDefault();
   form.submit();
   };
   return (
   <form onSubmit={submit}>
   <label htmlFor="name">Name</label>
   <input
   id="name"
   value={form.data.name}
   onChange={(e) => form.setData('name', e.target.value)}
   onBlur={() => form.validate('name')}
   />
   {form.invalid('name') && <div>{form.errors.name}</div>}
   <label htmlFor="email">Email</label>
   <input
   id="email"
   value={form.data.email}
   onChange={(e) => form.setData('email', e.target.value)}
   onBlur={() => form.validate('email')}
   />
   {form.invalid('email') && <div>{form.errors.email}</div>}
   <button disabled={form.processing}>
   Create User
   </button>
   </form>
   );
};

form.setValidationTimeout(3000);

検証リクエストが進行中の場合、フォームのvalidatingプロパティはtrueになります：

{form.validating && <div>Validating...</div>}

検証リクエストまたはフォーム送信中に返された検証エラーは、自動的にフォームのerrorsオブジェクトに入力されます：

{form.invalid('email') && <div>{form.errors.email}</div>}

フォームにエラーがあるかどうかは、フォームのhasErrorsプロパティを使用して判断できます：

{form.hasErrors && <div><!-- ... --></div>}

入力が検証に合格したか失敗したかを判断するには、入力の名前をフォームのvalidおよびinvalid関数に渡します：

{form.valid('email') && <span>✅</span>}
{form.invalid('email') && <span>❌</span>}

フォーム入力は、変更され、検証応答が受信されるまで、有効または無効として表示されません。

<input
   id="avatar"
   type="file"
   onChange={(e) => {
   form.setData('avatar', e.target.value);
   form.forgetError('avatar');
   }}
>

ご覧のとおり、入力のblurイベントにフックして、ユーザーがそれらと対話する際に個々の入力を検証できます。ただし、ユーザーがまだ対話していない入力を検証する必要がある場合があります。これは、「ウィザード」を構築する際によく見られます。次のステップに進む前に、ユーザーが対話したかどうかにかかわらず、すべての表示されている入力を検証したいからです。

<button
   type="button"
   onClick={() => form.touch(['name', 'email', 'phone']).validate({
   onSuccess: (response) => nextStep(),
   onValidationError: (response) => /* ... */,
   })}
>Next Step</button>

const submit = (e) => {
   e.preventDefault();
   form.submit()
   .then(response => {
   form.reset();
   alert('User created.');
   })
   .catch(error => {
   alert('An error occurred.');
   });
};

フォーム送信リクエストが進行中かどうかは、フォームのprocessingプロパティを調べることで判断できます：

<button disabled={form.processing}>
   Submit
</button>

ReactとInertiaの使用

ReactとInertiaを使用してLaravelアプリケーションを開発する際に先手を打ちたい場合は、私たちのスターターキットの1つを使用することを検討してください。Laravelのスターターキットは、新しいLaravelアプリケーションのバックエンドおよびフロントエンドの認証スキャフォールディングを提供します。

ReactとInertiaでPrecognitionを使用する前に、ReactでのPrecognitionの使用に関する一般的なドキュメントを確認してください。ReactをInertiaと一緒に使用する場合、NPMを介してInertia互換のPrecognitionライブラリをインストールする必要があります：

npm install laravel-precognition-react-inertia

インストールが完了すると、PrecognitionのuseForm関数は、上記で説明した検証機能を強化したInertiaのフォームヘルパーを返します。

import { useForm } from 'laravel-precognition-react-inertia';
const form = useForm('post', '/users', {
   name: '',
   email: '',
});
const submit = (e) => {
   e.preventDefault();
   form.submit({
   preserveScroll: true,
   onSuccess: () => form.reset(),
   });
};

AlpineとBladeの使用

Laravel Precognitionを使用すると、フロントエンドのAlpineアプリケーションで検証ルールを重複させることなく、ユーザーにライブ検証体験を提供できます。これがどのように機能するかを示すために、アプリケーション内で新しいユーザーを作成するためのフォームを作成しましょう。

use App\Http\Requests\CreateUserRequest;
use Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests;
Route::post('/users', function (CreateUserRequest $request) {
   // ...
})->middleware([HandlePrecognitiveRequests::class]);

次に、NPMを介してAlpine用のLaravel Precognitionフロントエンドヘルパーをインストールする必要があります：

npm install laravel-precognition-alpine

次に、resources/js/app.jsファイルでAlpineにPrecognitionプラグインを登録します：

import Alpine from 'alpinejs';
import Precognition from 'laravel-precognition-alpine';
window.Alpine = Alpine;
Alpine.plugin(Precognition);
Alpine.start();

Laravel Precognitionパッケージがインストールされ、登録されたら、HTTPメソッド（post）、ターゲットURL（/users）、および初期フォームデータを提供して、Precognitionの$form「マジック」を使用してフォームオブジェクトを作成できます。

ライブ検証を有効にするには、フォームのデータを関連する入力にバインドし、各入力のchangeイベントをリッスンする必要があります。changeイベントハンドラーでは、入力の名前を提供してフォームのvalidateメソッドを呼び出す必要があります：

<form x-data="{
   form: $form('post', '/register', {
   name: '',
   email: '',
   }),
}">
   @csrf
   <label for="name">Name</label>
   <input
   id="name"
   name="name"
   x-model="form.name"
   @change="form.validate('name')"
   />
   <template x-if="form.invalid('name')">
   <div x-text="form.errors.name"></div>
   </template>
   <label for="email">Email</label>
   <input
   id="email"
   name="email"
   x-model="form.email"
   @change="form.validate('email')"
   />
   <template x-if="form.invalid('email')">
   <div x-text="form.errors.email"></div>
   </template>
   <button :disabled="form.processing">
   Create User
   </button>
</form>

form.setValidationTimeout(3000);

検証リクエストが進行中の場合、フォームのvalidatingプロパティはtrueになります：

<template x-if="form.validating">
   <div>Validating...</div>
</template>

検証リクエストまたはフォーム送信中に返された検証エラーは、自動的にフォームのerrorsオブジェクトに入力されます：

<template x-if="form.invalid('email')">
   <div x-text="form.errors.email"></div>
</template>

フォームにエラーがあるかどうかは、フォームのhasErrorsプロパティを使用して判断できます：

<template x-if="form.hasErrors">
   <div><!-- ... --></div>
</template>

入力が検証に合格したか失敗したかを判断するには、入力の名前をフォームのvalidおよびinvalid関数に渡します：

<template x-if="form.valid('email')">
   <span>✅</span>
</template>
<template x-if="form.invalid('email')">
   <span>❌</span>
</template>

フォーム入力は、変更され、検証応答が受信されるまで、有効または無効として表示されません。

<button
   type="button"
   @change="form.touch(['name', 'email', 'phone']).validate({
   onSuccess: (response) => nextStep(),
   onValidationError: (response) => /* ... */,
   })"
>Next Step</button>

フォーム送信リクエストが進行中かどうかは、フォームのprocessingプロパティを調べることで判断できます：

<button :disabled="form.processing">
   Submit
</button>

古いフォームデータの再入力

上記で説明したユーザー作成の例では、ライブ検証を行うためにPrecognitionを使用しています。ただし、フォームを送信するために従来のサーバーサイドフォーム送信を行っています。したがって、フォームはサーバーサイドフォーム送信から返された「古い」入力と検証エラーで入力される必要があります：

<form x-data="{
   form: $form('post', '/register', {
   name: '{{ old('name') }}',
   email: '{{ old('email') }}',
   }).setErrors({{ Js::from($errors->messages()) }}),
}">

または、XHRを介してフォームを送信したい場合は、フォームのsubmit関数を使用できます。この関数はAxiosリクエストの約束を返します：

<form
   x-data="{
   form: $form('post', '/register', {
   name: '',
   email: '',
   }),
   submit() {
   this.form.submit()
   .then(response => {
   form.reset();
   alert('User created.')
   })
   .catch(error => {
   alert('An error occurred.');
   });
   },
   }"
   @submit.prevent="submit"
>

Axiosの設定

Precognition検証ライブラリは、Axios HTTPクライアントを使用して、アプリケーションのバックエンドにリクエストを送信します。便利なことに、必要に応じてAxiosインスタンスをカスタマイズできます。たとえば、laravel-precognition-vueライブラリを使用する場合、アプリケーションのresources/js/app.jsファイルで各送信リクエストに追加のリクエストヘッダーを追加できます：

import { client } from 'laravel-precognition-vue';
client.axios().defaults.headers.common['Authorization'] = authToken;

または、すでにアプリケーション用に設定されたAxiosインスタンスがある場合は、Precognitionにそのインスタンスを使用するように指示できます：

import Axios from 'axios';
import { client } from 'laravel-precognition-vue';
window.axios = Axios.create()
window.axios.defaults.headers.common['Authorization'] = authToken;
client.use(window.axios)

InertiaフレーバーのPrecognitionライブラリは、検証リクエストに対して設定されたAxiosインスタンスのみを使用します。フォーム送信は常にInertiaによって送信されます。

検証ルールのカスタマイズ

予知リクエスト中に実行される検証ルールをカスタマイズすることが可能です。リクエストのisPrecognitiveメソッドを使用します。

たとえば、ユーザー作成フォームでは、パスワードが「妥協されていない」ことを最終的なフォーム送信時のみ検証したい場合があります。予知検証リクエストでは、パスワードが必須であり、8文字以上であることを検証します。isPrecognitiveメソッドを使用して、フォームリクエストで定義されたルールをカスタマイズできます：

<?php
namespace App\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rules\Password;
class StoreUserRequest extends FormRequest
{
   /**
     * Get the validation rules that apply to the request.
   *
     * @return array
   */
   protected function rules()
   {
   return [
   'password' => [
   'required',
   $this->isPrecognitive()
   ? Password::min(8)
   : Password::min(8)->uncompromised(),
   ],
   // ...
   ];
   }
}

ファイルアップロードの処理

デフォルトでは、Laravel Precognitionは予知検証リクエスト中にファイルをアップロードまたは検証しません。これにより、大きなファイルが不必要に何度もアップロードされることを防ぎます。

この動作のため、アプリケーションが対応するフォームリクエストの検証ルールをカスタマイズすることを確認し、フィールドが完全なフォーム送信時のみ必須であることを指定する必要があります：

/**
 * Get the validation rules that apply to the request.
 *
 * @return array
 */
protected function rules()
{
   return [
   'avatar' => [
   ...$this->isPrecognitive() ? [] : ['required'],
   'image',
   'mimes:jpg,png',
   'dimensions:ratio=3/2',
   ],
   // ...
   ];
}

すべての検証リクエストにファイルを含めたい場合は、クライアント側のフォームインスタンスでvalidateFiles関数を呼び出すことができます：

form.validateFiles();

副作用の管理

ルートにHandlePrecognitiveRequestsミドルウェアを追加する際には、予知リクエスト中にスキップすべき他のミドルウェアに副作用があるかどうかを考慮する必要があります。

たとえば、ユーザーがアプリケーションと持つ「インタラクション」の総数を増加させるミドルウェアがある場合、予知リクエストをインタラクションとしてカウントしたくないかもしれません。これを実現するために、インタラクションカウントを増加させる前にリクエストのisPrecognitiveメソッドを確認できます：

<?php
namespace App\Http\Middleware;
use App\Facades\Interaction;
use Closure;
use Illuminate\Http\Request;
class InteractionMiddleware
{
   /**
     * Handle an incoming request.
   */
   public function handle(Request $request, Closure $next): mixed
   {
   if (! $request->isPrecognitive()) {
   Interaction::incrementFor($request->user());
   }
   return $next($request);
   }
}

テスト

テストで予知リクエストを行いたい場合、LaravelのTestCaseには、withPrecognitionヘルパーが含まれており、Precognitionリクエストヘッダーを追加します。

さらに、予知リクエストが成功したことを主張したい場合、たとえば、検証エラーが返されなかった場合は、応答に対してassertSuccessfulPrecognitionメソッドを使用できます：

it('validates registration form with precognition', function () {
   $response = $this->withPrecognition()
   ->post('/register', [
   'name' => 'Taylor Otwell',
   ]);
   $response->assertSuccessfulPrecognition();
   expect(User::count())->toBe(0);
});

public function test_it_validates_registration_form_with_precognition()
{
   $response = $this->withPrecognition()
   ->post('/register', [
   'name' => 'Taylor Otwell',
   ]);
   $response->assertSuccessfulPrecognition();
   $this->assertSame(0, User::count());
}