Laravel Precognition allows you to anticipate the outcome of a future HTTP request. One of the primary use cases of Precognition is the ability to provide "live" validation for your frontend JavaScript application without having to duplicate your application's backend validation rules. Precognition pairs especially well with Laravel's Inertia-based starter kits.
When Laravel receives a "precognitive request", it will execute all of the route's middleware and resolve the route's controller dependencies, including validating form requests - but it will not actually execute the route's controller method.
Using Laravel Precognition, you can offer live validation experiences to your users without having to duplicate your validation rules in your frontend Vue application. To illustrate how it works, let's build a form for creating new users within our application.
First, to enable Precognition for a route, the HandlePrecognitiveRequests middleware should be added to the route definition. You should also create a form request to house the route's validation rules:
use App\Http\Requests\CreateUserRequest;
use Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests;
Route::post('/users', function (CreateUserRequest $request) {
// ...
})->middleware([HandlePrecognitiveRequests::class]);Next, you should install the Laravel Precognition frontend helpers for Vue via NPM:
npm install laravel-precognition-vueWith the Laravel Precognition package installed, you can now create a form object using Precognition's useForm function, providing the HTTP method (post), the target URL (/users), and the initial form data.
Then, to enable live validation, invoke the form's validate method on each input's change event, providing the input's name:
<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>Create User</button>
</form>
</template>Now, as the form is filled by the user, Precognition will provide live validation output powered by the validation rules in the route's form request. When the form's inputs are changed, a debounced "precognitive" validation request will be sent to your Laravel application. You may configure the debounce timeout by calling the form's setValidationTimeout function:
form.setValidationTimeout(3000);When a validation request is in-flight, the form's validating property will be true:
<div v-if="form.validating">
Validating...
</div>Any validation errors returned during a validation request or a form submission will automatically populate the form's errors object:
<div v-if="form.invalid('email')">
{{ form.errors.email }}
</div>You can determine if the form has any errors using the form's hasErrors property:
<div v-if="form.hasErrors">
<!-- ... -->
</div>You may also determine if an input has passed or failed validation by passing the input's name to the form's valid and invalid functions, respectively:
<span v-if="form.valid('email')">
✅
</span>
<span v-else-if="form.invalid('email')">
❌
</span>Warning A form input will only appear as valid or invalid once it has changed and a validation response has been received.
Of course, you may also execute code in reaction to the response to the form submission. The form's submit function returns an Axios request promise. This provides a convenient way to access the response payload, reset the form inputs on successful submission, or handle a failed request:
const submit = () => form.submit()
.then(response => {
form.reset();
alert('User created.');
})
.catch(error => {
alert('An error occurred.');
});Note If you would like a head start when developing your Laravel application with Vue and Inertia, consider using one of our starter kits. Laravel's starter kits provide backend and frontend authentication scaffolding for your new Laravel application.
Before using Precognition with Vue and Inertia, be sure to review our general documentation on using Precognition with Vue. When using Vue with Inertia, you will need to install the Inertia compatible Precognition library via NPM:
npm install laravel-precognition-vue-inertiaOnce installed, Precognition's useForm function will return an Inertia form helper augmented with the validation features discussed above.
The form helper's submit method has been streamlined, removing the need to specify the HTTP method or URL. Instead, you may pass Inertia's visit options as the first and only argument. In addition, the submit method does not return a Promise as seen in the Vue example above. Instead, you may provide any of Inertia's supported event callbacks in the visit options given to the submit method:
<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>Using Laravel Precognition, you can offer live validation experiences to your users without having to duplicate your validation rules in your frontend React application. To illustrate how it works, let's build a form for creating new users within our application.
First, to enable Precognition for a route, the HandlePrecognitiveRequests middleware should be added to the route definition. You should also create a form request to house the route's validation rules:
use App\Http\Requests\CreateUserRequest;
use Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests;
Route::post('/users', function (CreateUserRequest $request) {
// ...
})->middleware([HandlePrecognitiveRequests::class]);Next, you should install the Laravel Precognition frontend helpers for React via NPM:
npm install laravel-precognition-reactWith the Laravel Precognition package installed, you can now create a form object using Precognition's useForm function, providing the HTTP method (post), the target URL (/users), and the initial form data.
To enable live validation, you should listen to each input's change and blur event. In the change event handler, you should set the form's data with the setData function, passing the input's name and new value. Then, in the blur event handler invoke the form's validate method, providing the input's name:
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>) : null}
<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>) : null}
<button>Create User</button>
</form>
);
};Now, as the form is filled by the user, Precognition will provide live validation output powered by the validation rules in the route's form request. When the form's inputs are changed, a debounced "precognitive" validation request will be sent to your Laravel application. You may configure the debounce timeout by calling the form's setValidationTimeout function:
form.setValidationTimeout(3000);When a validation request is in-flight, the form's validating property will be true:
{form.validating ? (<div>Validating...</div>) : null}Any validation errors returned during a validation request or a form submission will automatically populate the form's errors object:
{form.invalid('email') ? (<div>{form.errors.email}</div>) : null}You can determine if the form has any errors using the form's hasErrors property:
{form.hasErrors ? (<div><!-- ... --></div>) : null}You may also determine if an input has passed or failed validation by passing the input's name to the form's valid and invalid functions, respectively:
{form.valid('email') ? (<span>✅</span>) : null}
{form.invalid('email') ? (<span>❌</span>) : null}Warning A form input will only appear as valid or invalid once it has changed and a validation response has been received.
Of course, you may also execute code in reaction to the response to the form submission. The form's submit function returns an Axios request promise. This provides a convenient way to access the response payload, reset the form's inputs on a successful form submission, or handle a failed request:
const submit = (e) => {
e.preventDefault();
form.submit()
.then(response => {
form.reset();
alert('User created.');
})
.catch(error => {
alert('An error occurred.');
});
};Note If you would like a head start when developing your Laravel application with React and Inertia, consider using one of our starter kits. Laravel's starter kits provide backend and frontend authentication scaffolding for your new Laravel application.
Before using Precognition with React and Inertia, be sure to review our general documentation on using Precognition with React. When using React with Inertia, you will need to install the Inertia compatible Precognition library via NPM:
npm install laravel-precognition-react-inertiaOnce installed, Precognition's useForm function will return an Inertia form helper augmented with the validation features discussed above.
The form helper's submit method has been streamlined, removing the need to specify the HTTP method or URL. Instead, you may pass Inertia's visit options as the first and only argument. In addition, the submit method does not return a Promise as seen in the React example above. Instead, you may provide any of Inertia's supported event callbacks in the visit options given to the submit method:
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(),
});
};It is possible to customize the validation rules executed during a precognitive request by using the request's isPrecognitive method.
For example, on a user creation form, we may want to validate that a password is "uncompromised" only on the final form submission. For precognitive validation requests, we will simply validate that the password is required and has a minimum of 8 characters. Using the isPrecognitive method, we can customize the rules defined by our form request:
<?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(),
],
// ...
];
}
}When adding the HandlePrecognitiveRequests middleware to a route, you should consider if there are any side-effects in other middleware that should be skipped during a precognitive request.
For example, you may have a middleware that increments the total number of "interactions" each user has with your application, but you may not want precognitive requests to be counted as an interaction. To accomplish this, we may check the request's isPrecognitive method before incrementing the interaction count:
<?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);
}
}