Precognition

• Введение
• Живая валидация
  • Использование Vue
  • Использование Vue и Inertia
  • Использование React
  • Использование React и Inertia
  • Использование Alpine и Blade
  • Настройка Axios
• Настройка пользовательских правил валидации
• Обработка загрузки файлов
• Управление побочными эффектами
• Тестирование

Введение

Laravel Precognition позволяет предвидеть результат будущего HTTP-запроса. Одним из основных случаев использования Precognition является возможность предоставления "живой" валидации для вашего фронтенд-приложения на 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]);

Затем установите помощники Laravel Precognition для Vue через NPM:

npm install laravel-precognition-vue

С установленным пакетом Laravel Precognition теперь можно создать объект формы, используя функцию useForm Precognition, предоставив HTTP-метод (post), целевой URL (/users) и начальные данные формы.

Затем, чтобы включить живую валидацию, вызовите метод validate формы на событии change каждого ввода, передавая имя ввода:

<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')
    }"
>

Конечно же, вы также можете выполнить код в реакции на ответ на отправку формы. Функция 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

Примечание Если вы хотите ускорить разработку вашего приложения Laravel с использованием Vue и Inertia, рассмотрите использование одного из наших стартовых наборов. Стартовые наборы Laravel предоставляют каркас аутентификации на стороне сервера и на стороне клиента для вашего нового приложения Laravel.

Прежде чем использовать Precognition с Vue и Inertia, обязательно прочитайте нашу общую документацию по использованию Precognition с Vue. При использовании Vue с Inertia вам нужно установить совместимую с Inertia библиотеку Precognition через NPM:

npm install laravel-precognition-vue-inertia

После установки функция useForm Precognition вернет помощник формы Inertia, дополненный описанными выше функциями валидации.

Метод submit помощника формы был упрощен, убрав необходимость указания HTTP-метода или URL. Вместо этого в качестве первого и единственного аргумента можно передать параметры посещения Inertia. Кроме того, метод submit не возвращает обещание, как в примере с Vue выше. Вместо этого вы можете предоставить любые поддерживаемые Inertia обработчики событий в параметрах посещения, переданных методу submit:

<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. Чтобы проиллюстрировать, как это работает, давайте создадим форму для создания новых пользователей в нашем приложении.

Сначала, чтобы включить Precognition для маршрута, в его определение маршрута следует добавить промежуточный обработчик HandlePrecognitiveRequests. Вы также должны создать запрос формы, чтобы хранить правила валидации маршрута:

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

Затем установите помощники Laravel Precognition для React через NPM:

npm install laravel-precognition-react

С установленным пакетом Laravel Precognition теперь можно создать объект формы, используя функцию useForm Precognition, предоставив HTTP-метод (post), целевой URL (/users) и начальные данные формы.

Для включения живой валидации следует прослушивать события 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 for="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 for="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 предоставит вывод живой валидации на основе правил валидации запроса формы маршрута. Когда изменяются вводы формы, будет отправлен отложенный "предкогнитивный" запрос валидации в ваше приложение Laravel. Вы можете настроить тайм-аут отложенной отправки, вызвав функцию setValidationTimeout формы:

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>}

Внимание Внешний вид формового ввода изменится на допустимый или недопустимый только после его изменения и получения ответа валидации.

Если вы валидируете подмножество вводов формы с использованием Precognition, может быть полезным вручную очистить ошибки. Вы можете использовать функцию forgetError формы для этого:

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

Конечно же, вы также можете выполнить код в реакции на ответ на отправку формы. Функция submit формы возвращает обещание запроса Axios. Это предоставляет удобный способ доступа к полезной нагрузке ответа, сброса вводов формы при успешной отправке формы или обработки неудачного запроса:

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

Примечание Если вы хотите ускорить разработку вашего приложения Laravel с использованием React и Inertia, рассмотрите использование одного из наших стартовых наборов. Стартовые наборы Laravel предоставляют каркас аутентификации на стороне сервера и на стороне клиента для вашего нового приложения Laravel.

Прежде чем использовать Precognition с React и Inertia, обязательно прочитайте нашу общую документацию по использованию Precognition с React. При использовании React с Inertia вам нужно установить совместимую с Inertia библиотеку Precognition через NPM:

npm install laravel-precognition-react-inertia

После установки функция useForm Precognition вернет помощник формы Inertia, дополненный описанными выше функциями валидации.

Метод submit помощника формы был упрощен, убрав необходимость указания HTTP-метода или URL. Вместо этого в качестве первого и единственного аргумента можно передать параметры посещения Inertia. Кроме того, метод submit не возвращает обещание, как в примере с React выше. Вместо этого вы можете предоставить любые поддерживаемые Inertia обработчики событий в параметрах посещения, переданных методу submit:

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. Чтобы проиллюстрировать, как это работает, давайте создадим форму для создания новых пользователей в нашем приложении.

Сначала, чтобы включить Precognition для маршрута, в его определение маршрута следует добавить промежуточный обработчик HandlePrecognitiveRequests. Вы также должны создать запрос формы, чтобы хранить правила валидации маршрута:

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

Затем установите помощники Laravel Precognition для Alpine через NPM:

npm install laravel-precognition-alpine

Затем зарегистрируйте плагин Precognition с Alpine в вашем файле resources/js/app.js:

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

С установленным и зарегистрированным пакетом Laravel Precognition теперь можно создать объект формы, используя $form "магию" Precognition, предоставив HTTP-метод (post), целевой URL (/users) и начальные данные формы.

Чтобы включить живую валидацию, следует привязать данные формы к соответствующему вводу и затем прослушивать событие 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>

Теперь, по мере заполнения формы пользователем, Precognition предоставит вывод живой валидации на основе правил валидации запроса формы маршрута. Когда изменяются вводы формы, будет отправлен отложенный "предкогнитивный" запрос валидации в ваше приложение Laravel. Вы можете настроить тайм-аут отложенной отправки, вызвав функцию setValidationTimeout формы:

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>

Внимание Внешний вид формового ввода изменится на допустимый или недопустимый только после его изменения и получения ответа валидации.

Вы можете определить, находится ли запрос на отправку формы в процессе, проверив свойство 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 используют HTTP-клиент Axios для отправки запросов на бэкенд вашего приложения. Для удобства экземпляр 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)

Внимание Библиотеки Precognition в стиле Inertia будут всегда использовать настроенный экземпляр Axios для запросов валидации. Отправка формы всегда будет осуществляться через Inertia.

Настройка пользовательских правил валидации

Возможно настраивать правила валидации, выполняемые во время предкогнитивного запроса, с использованием метода isPrecognitive запроса.

Например, при создании формы для создания пользователя мы хотим валидировать, что пароль «непригоден» только при окончательной отправке формы. Для предкогнитивных запросов валидации мы просто валидируем, что пароль обязателен и имеет минимум 8 символов. Используя метод isPrecognitive, мы можем настраивать правила, определенные нашим запросом формы:

<?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(),
            ],
            // ...
        ];
    }
}

Обработка загрузки файлов

По умолчанию Laravel Precognition не загружает и не валидирует файлы во время предкогнитивного запроса валидации. Это гарантирует, что большие файлы не загружаются несколько раз без необходимости.

В связи с этим поведением следует удостовериться, что ваше приложение настраивает соответствующие правила валидации запроса формы, чтобы указать, что поле обязательно только для полной отправки формы:

/**
 * Получить правила валидации, применяемые к запросу.
 *
 * @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
{
    /**
     * Обработать входящий запрос.
     */
    public function handle(Request $request, Closure $next): mixed
    {
        if (! $request->isPrecognitive()) {
            Interaction::incrementFor($request->user());
        }
 
        return $next($request);
    }
}

Тестирование

Если вы хотите выполнять предкогнитивные запросы в ваших тестах, в тестовом классе Laravel есть вспомогательная функция withPrecognition, которая добавит заголовок запроса Precognition.

Кроме того, если вы хотите утверждать, что предкогнитивный запрос завершился успешно, например, не вернул ошибок валидации, вы можете использовать метод assertSuccessfulPrecognition в ответе:

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