
# Precognition（预验证）

- [简介](#introduction)
- [实时验证](#live-validation)
    - [使用 Vue](#using-vue)
    - [使用 React](#using-react)
    - [使用 Alpine 和 Blade](#using-alpine)
    - [配置 Axios](#configuring-axios)
- [验证数组](#validating-arrays)
- [自定义验证规则](#customizing-validation-rules)
- [处理文件上传](#handling-file-uploads)
- [管理副作用](#managing-side-effects)
- [测试](#testing)

## 简介

Laravel Precognition 允许你预先判断未来 HTTP 请求可能产生的结果。

Precognition 的主要用途之一，是让前端 JavaScript 应用程序能够实现「实时」验证，而无需在前端重复定义应用程序后端的验证规则。

当 Laravel 收到一个「预验证请求」（Precognitive Request）时，它会执行该路由的所有中间件，并解析路由控制器所依赖的所有依赖项，包括验证 [表单请求]( /docs/laravel/13.x/validation#form-request-validation)。

但它不会真正执行路由对应的控制器方法。

> [!注意]
> 从 Inertia 2.3 开始，已经内置了对 Precognition 的支持。更多信息请参阅 [Inertia 表单文档](https://inertiajs.com/forms)。
>
> 较早版本的 Inertia 需要使用 Precognition 0.x 版本。

## 实时验证

### 使用 Vue

借助 Laravel Precognition，你可以为用户提供实时验证体验，而无需在前端 Vue 应用程序中重复定义验证规则。为了说明其工作原理，下面我们将在应用程序中构建一个用于创建新用户的表单。
首先，要为某个路由启用 Precognition，需要在路由定义中添加 `HandlePrecognitiveRequests` 中间件。你还应该创建一个[表单请求]( /docs/laravel/13.x/validation#form-request-validation)，用于存放该路由的验证规则：

```php
use App\Http\Requests\StoreUserRequest;
use Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests;

Route::post('/users', function (StoreUserRequest $request) {
    // ...
})->middleware([HandlePrecognitiveRequests::class]);
```



接下来，你需要通过 NPM 安装 Laravel Precognition 的 Vue 前端辅助包：

```shell
npm install laravel-precognition-vue
```

安装 Laravel Precognition 包后，你就可以使用 Precognition 提供的 `useForm` 函数创建一个表单对象，并传入 HTTP 请求方法（`post`）、目标 URL（`/users`）以及表单的初始数据。

然后，为了启用实时验证，需要在每个输入框的 `change` 事件中调用表单的 `validate` 方法，并传入对应的输入字段名称：

```vue
<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">姓名</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">邮箱</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">
            创建用户
        </button>
    </form>
</template>
```

现在，当用户填写表单时，Precognition 就会根据路由表单请求中定义的验证规则，实时提供验证结果。当表单输入内容发生变化时，Precognition 会向 Laravel 应用程序发送一个经过防抖处理的「预验证」请求。你可以通过调用表单的 `setValidationTimeout` 函数来配置防抖等待时间：

```js
form.setValidationTimeout(3000);
```

当验证请求正在执行时，表单的 `validating` 属性将为 `true`：

```html
<div v-if="form.validating">
    Validating...
</div>
```

无论是在验证请求期间，还是在提交表单时返回的任何验证错误，都会自动填充到表单的 `errors` 对象中：

```html
<div v-if="form.invalid('email')">
    {{ form.errors.email }}
</div>
```




你可以通过表单的 `hasErrors` 属性判断表单是否存在任何错误：

```html
<div v-if="form.hasErrors">
    <!-- ... -->
</div>
```

你还可以通过分别调用表单的 `valid` 和 `invalid` 方法，并传入输入字段的名称，来判断某个输入项是否通过或未通过验证：

```html
<span v-if="form.valid('email')">
    ✅
</span>

<span v-else-if="form.invalid('email')">
    ❌
</span>
```

> [!警告]
> 只有当表单输入项发生变化，并且收到验证响应后，该输入项才会被标记为有效或无效。

如果你使用 Precognition 只验证表单中的部分输入项，手动清除错误信息可能会很有用。你可以使用表单的 `forgetError` 方法来实现：

```html
<input
    id="avatar"
    type="file"
    @change="(e) => {
        form.avatar = e.target.files[0]

        form.forgetError('avatar')
    }"
>
```

正如我们前面所看到的，你可以监听输入项的 `change` 事件，在用户与输入项交互时对单个字段进行验证。不过，有时你可能需要验证用户尚未交互过的输入项。这种情况在构建「分步表单」（Wizard）时很常见。例如，在进入下一步之前，你希望验证当前页面上所有可见的输入项，而不管用户是否与它们进行过交互。要使用 Precognition 实现这一功能，你应该调用 `validate` 方法，并通过 `only` 配置项传入需要验证的字段名称。你可以通过 `onSuccess` 或 `onValidationError` 回调函数处理验证结果：

```html
<button
    type="button"
    @click="form.validate({
        only: ['name', 'email', 'phone'],
        onSuccess: (response) => nextStep(),
        onValidationError: (response) => /* ... */,
    })"
>Next Step</button>
```

当然，你也可以在表单提交请求返回后执行相应的代码。表单的 `submit` 方法会返回一个 Axios 请求 Promise。这为你提供了一种便捷的方式，可以访问响应数据、在提交成功后重置表单输入项，或者处理请求失败的情况：

```js
const submit = () => form.submit()
    .then(response => {
        form.reset();

        alert('User created.');
    })
    .catch(error => {
        alert('An error occurred.');
    });
```



你可以通过检查表单的 `processing` 属性，判断表单提交请求当前是否正在处理中：

```html
<button :disabled="form.processing">
    提交
</button>
```

### 使用 React

借助 Laravel Precognition，你可以为用户提供实时验证体验，而无需在前端 React 应用程序中重复定义验证规则。为了说明其工作原理，下面我们将在应用程序中构建一个用于创建新用户的表单。
首先，要为某个路由启用 Precognition，需要在路由定义中添加 `HandlePrecognitiveRequests` 中间件。你还应该创建一个[表单请求](/docs/laravel/13.x/validation#form-request-validation)，用于存放该路由的验证规则：

```php
use App\Http\Requests\StoreUserRequest;
use Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests;

Route::post('/users', function (StoreUserRequest $request) {
    // ...
})->middleware([HandlePrecognitiveRequests::class]);
```

接下来，你需要通过 NPM 安装 Laravel Precognition 的 React 前端辅助包：

```shell
npm install laravel-precognition-react
```

安装 Laravel Precognition 包后，你就可以使用 Precognition 提供的 `useForm` 函数创建一个表单对象，并传入 HTTP 请求方法（`post`）、目标 URL（`/users`）以及表单的初始数据。
为了启用实时验证，你需要监听每个输入框的 `change` 和 `blur` 事件。在 `change` 事件处理函数中，使用 `setData` 函数设置表单数据，并传入输入字段的名称和新的值。然后，在 `blur` 事件处理函数中调用表单的 `validate` 方法，并传入对应的输入字段名称：


```jsx
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>
    );
};
```



现在，当用户填写表单时，Precognition 就会根据路由表单请求中定义的验证规则，实时提供验证结果。当表单输入内容发生变化时，Precognition 会向 Laravel 应用程序发送一个经过防抖处理的「预验证」请求。你可以通过调用表单的 `setValidationTimeout` 函数来配置防抖等待时间：

```js
form.setValidationTimeout(3000);
```

当验证请求正在执行时，表单的 `validating` 属性将为 `true`：

```jsx
{form.validating && <div>Validating...</div>}
```

无论是在验证请求期间，还是在提交表单时返回的任何验证错误，都会自动填充到表单的 `errors` 对象中：

```jsx
{form.invalid('email') && <div>{form.errors.email}</div>}
```

你可以通过表单的 `hasErrors` 属性判断表单是否存在任何错误：

```jsx
{form.hasErrors && <div><!-- ... --></div>}
```

你还可以通过分别调用表单的 `valid` 和 `invalid` 方法，并传入输入字段的名称，来判断某个输入项是否通过或未通过验证：

```jsx
{form.valid('email') && <span>✅</span>}

{form.invalid('email') && <span>❌</span>}
```

> [!警告]
> 只有当表单输入项发生变化，并且收到验证响应后，该输入项才会被标记为有效或无效。

如果你使用 Precognition 只验证表单中的部分输入项，手动清除错误信息可能会很有用。你可以使用表单的 `forgetError` 方法来实现：


```jsx
<input
    id="avatar"
    type="file"
    onChange={(e) => {
        form.setData('avatar', e.target.files[0]);

        form.forgetError('avatar');
    }}
>
```

正如我们前面所看到的，你可以监听输入项的 `blur` 事件，在用户与输入项交互时对单个字段进行验证。不过，有时你可能需要验证用户尚未交互过的输入项。这种情况在构建「分步表单」（Wizard）时很常见。例如，在进入下一步之前，你希望验证当前页面上所有可见的输入项，而不管用户是否与它们进行过交互。




要使用 Precognition 实现这一功能，你应该调用 `validate` 方法，并通过 `only` 配置项传入需要验证的字段名称。你可以通过 `onSuccess` 或 `onValidationError` 回调函数处理验证结果：

```jsx
<button
    type="button"
    onClick={() => form.validate({
        only: ['name', 'email', 'phone'],
        onSuccess: (response) => nextStep(),
        onValidationError: (response) => /* ... */,
    })}
>下一步</button>
```

当然，你也可以在表单提交请求返回后执行相应的代码。表单的 `submit` 方法会返回一个 Axios 请求 Promise。这为你提供了一种便捷的方式，可以访问响应数据、在表单提交成功后重置表单输入项，或者处理请求失败的情况：


```js
const submit = (e) => {
    e.preventDefault();

    form.submit()
        .then(response => {
            form.reset();

            alert('User created.');
        })
        .catch(error => {
            alert('An error occurred.');
        });
};
```

你可以通过检查表单的 `processing` 属性，判断表单提交请求当前是否正在处理中：

```html
<button disabled={form.processing}>
    提交
</button>
```

### 使用 Alpine 和 Blade

借助 Laravel Precognition，你可以为用户提供实时验证体验，而无需在前端 Alpine 应用程序中重复定义验证规则。为了说明其工作原理，下面我们将在应用程序中构建一个用于创建新用户的表单。

首先，要为某个路由启用 Precognition，需要在路由定义中添加 `HandlePrecognitiveRequests` 中间件。你还应该创建一个[表单请求](/docs/laravel/13.x/validation#form-request-validation)，用于存放该路由的验证规则：


```php
use App\Http\Requests\CreateUserRequest;
use Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests;

Route::post('/users', function (CreateUserRequest $request) {
    // ...
})->middleware([HandlePrecognitiveRequests::class]);
```



接下来，你需要通过 NPM 安装适用于 Alpine 的 Laravel Precognition 前端辅助包：

```shell
npm install laravel-precognition-alpine
```

然后，在 `resources/js/app.js` 文件中注册 Precognition 插件：

```js
import Alpine from 'alpinejs';
import Precognition from 'laravel-precognition-alpine';

window.Alpine = Alpine;

Alpine.plugin(Precognition);
Alpine.start();
```

安装并注册 Laravel Precognition 包后，你现在就可以使用 Precognition 提供的 `$form`「魔法方法」创建一个表单对象。创建时需要指定 HTTP 请求方法（`post`）、目标 URL（`/users`）以及表单的初始数据。

要启用实时验证，你需要将表单的数据绑定到对应的输入框，然后监听每个输入框的 `change` 事件。在 `change` 事件处理程序中，调用表单的 `validate` 方法，并传入对应输入框的名称：

```html
<form x-data="{
    form: $form('post', '/register', {
        name: '',
        email: '',
    }),
}">
    @csrf
    <label for="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">邮箱</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">
        创建用户
    </button>
</form>
```

现在，当用户填写表单时，Precognition 将根据路由表单请求（Form Request）中定义的验证规则，提供实时验证结果。当表单输入内容发生变化时，Precognition 会向你的 Laravel 应用程序发送一个经过防抖处理的「预验证（precognitive）」请求。你可以通过调用表单的 `setValidationTimeout` 方法来配置防抖延迟时间：

```js
form.setValidationTimeout(3000);
```



当验证请求正在执行时，表单的 `validating` 属性将为 `true`：

```html
<template x-if="form.validating">
    <div>正在验证...</div>
</template>
```

在验证请求或表单提交过程中返回的任何验证错误，都会自动填充到表单的 `errors` 对象中：

```html
<template x-if="form.invalid('email')">
    <div x-text="form.errors.email"></div>
</template>
```

你可以通过表单的 `hasErrors` 属性判断表单是否存在任何错误：

```html
<template x-if="form.hasErrors">
    <div><!-- ... --></div>
</template>
```

你还可以通过分别向表单的 `valid` 和 `invalid` 方法传入输入框的名称，判断某个输入框是否通过或未通过验证：

```html
<template x-if="form.valid('email')">
    <span>✅</span>
</template>

<template x-if="form.invalid('email')">
    <span>❌</span>
</template>
```

> [!警告]
> 只有当表单输入框的值发生变化，并且收到验证响应后，该输入框才会显示为有效或无效状态。

正如我们前面所看到的，你可以监听输入框的 `change` 事件，在用户与输入框交互时对单个输入项进行验证。但是，有时你可能需要验证用户尚未交互过的输入项。这种情况在构建「向导式（wizard）」表单时很常见。例如，在进入下一步之前，你希望验证当前所有可见的输入项，无论用户是否与这些输入项进行过交互。
要使用 Precognition 实现这一功能，你应该调用 `validate` 方法，并通过 `only` 配置项传入需要验证的字段名称。
你可以通过 `onSuccess` 或 `onValidationError` 回调函数处理验证结果：

```html
<button
    type="button"
    @click="form.validate({
        only: ['name', 'email', 'phone'],
        onSuccess: (response) => nextStep(),
        onValidationError: (response) => /* ... */,
    })"
>下一步</button>
```



你可以通过检查表单的 `processing` 属性，判断表单提交请求是否正在执行：

```html
<button :disabled="form.processing">
    提交
</button>
```

#### 重新填充旧的表单数据

在前面讨论的用户创建示例中，我们使用 Precognition 实现实时验证，但表单提交仍然采用传统的服务器端表单提交方式。
因此，表单应该填充服务器端表单提交后返回的任何「旧」输入数据和验证错误：


```html
<form x-data="{
    form: $form('post', '/register', {
        name: '{{ old('name') }}',
        email: '{{ old('email') }}',
    }).setErrors({{ Js::from($errors->messages()) }}),
}">
```

另外，如果你希望通过 XHR 提交表单，可以使用表单的 `submit` 方法，该方法会返回一个 Axios 请求 Promise：

```html
<form
    x-data="{
        form: $form('post', '/register', {
            name: '',
            email: '',
        }),
        submit() {
            this.form.submit()
                .then(response => {
                    this.form.reset();

                    alert('用户创建成功。')
                })
                .catch(error => {
                    alert('发生错误。');
                });
        },
    }"
    @submit.prevent="submit"
>
```

### 配置 Axios

Precognition 验证库使用 [Axios](https://github.com/axios/axios?utm_source=chatgpt.com) HTTP 客户端向应用程序的后端发送请求。

为了方便起见，如果你的应用程序有相关需求，可以自定义 Axios 实例。

例如，当使用 `laravel-precognition-vue` 库时，你可以在应用程序的 `resources/js/app.js` 文件中为每个发出的请求添加额外的请求头：

```js
import { client } from 'laravel-precognition-vue';

client.axios().defaults.headers.common['Authorization'] = authToken;
```

或者，如果你的应用程序已经配置好了 Axios 实例，也可以让 Precognition 使用该实例：

```js
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)
```



## 验证数组

你可以使用通配符来验证数组或嵌套对象中的字段。每个 `*` 都匹配一个路径层级：

```js
// 验证数组中所有用户的 email...
form.validate('users.*.email');

// 验证 profile 对象中的所有字段...
form.validate('profile.*');

// 验证所有用户的所有字段...
form.validate('users.*.*');
```

## **自定义验证规则（Customizing Validation Rules）**

你可以使用请求的 `isPrecognitive` 方法，自定义在预验证请求期间执行的验证规则。例如，在用户创建表单中，我们可能只希望在最终提交表单时，才验证密码是否为「未泄露密码（uncompromised）」。
对于预验证请求，我们只需要验证密码是否必填，以及长度是否至少为 8 个字符。通过使用 `isPrecognitive` 方法，我们可以自定义表单请求中定义的验证规则：

```php
<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rules\Password;

class StoreUserRequest extends FormRequest
{
    /**
     * 获取适用于当前请求的验证规则。
     *
     * @return array
     */
    protected function rules()
    {
        return [
            'password' => [
                'required',
                $this->isPrecognitive()
                    ? Password::min(8)
                    : Password::min(8)->uncompromised(),
            ],
            // ...
        ];
    }
}
```

## 处理文件上传（Handling File Uploads）

默认情况下，Laravel Precognition 不会在预验证请求期间上传或验证文件。这样可以避免大型文件被不必要地重复上传多次。

因此，你应该确保应用程序[自定义相应表单请求的验证规则](#customizing-validation-rules)，指定该字段仅在完整的表单提交过程中才是必填项：

```php
/**
 * 获取适用于当前请求的验证规则。
 *
 * @return array
 */
protected function rules()
{
    return [
        'avatar' => [
            ...$this->isPrecognitive() ? [] : ['required'],
            'image',
            'mimes:jpg,png',
            'dimensions:ratio=3/2',
        ],
        // ...
    ];
}

```



如果你希望在每次验证请求中都包含文件，可以在客户端表单实例上调用 `validateFiles` 方法：

```js
form.validateFiles();
```

## 管理副作用

当你将 `HandlePrecognitiveRequests` 中间件添加到路由时，应该考虑其他中间件中是否存在一些在预验证请求期间应该跳过的副作用操作。

例如，你可能有一个中间件，用于统计每个用户与你的应用程序之间的「交互」总次数，但你可能不希望将预验证请求也计入交互次数。

为了实现这一点，我们可以在增加交互次数之前，检查请求的 `isPrecognitive` 方法：

```php
<?php

namespace App\Http\Middleware;

use App\Facades\Interaction;
use Closure;
use Illuminate\Http\Request;

class InteractionMiddleware
{
    /**
     * 处理传入的请求。
     */
    public function handle(Request $request, Closure $next): mixed
    {
        if (! $request->isPrecognitive()) {
            Interaction::incrementFor($request->user());
        }

        return $next($request);
    }
}
```

## 测试

如果你希望在测试中发送预验证请求，Laravel 的 `TestCase` 提供了一个 `withPrecognition` 辅助方法，它会自动添加 `Precognition` 请求头。

此外，如果你希望断言预验证请求是否成功，例如没有返回任何验证错误，可以在响应对象上使用 `assertSuccessfulPrecognition` 方法：

```php tab=Pest
it('validates registration form with precognition', function () {
    $response = $this->withPrecognition()
        ->post('/register', [
            'name' => 'Taylor Otwell',
        ]);

    $response->assertSuccessfulPrecognition();

    expect(User::count())->toBe(0);
});
```

```php tab=PHPUnit
public function test_it_validates_registration_form_with_precognition()
{
    $response = $this->withPrecognition()
        ->post('/register', [
            'name' => 'Taylor Otwell',
        ]);

    $response->assertSuccessfulPrecognition();
    $this->assertSame(0, User::count());
}
```

