> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Precognition

> Fonctionnalité Laravel qui exécute la validation côté serveur en temps réel avant l'envoi d'un formulaire.

## Qu'est-ce que Precognition

Precognition est un mécanisme qui exécute la validation côté serveur avant que le formulaire soit envoyé.
Vous n'avez pas à dupliquer les règles de validation côté frontend : les règles Laravel sont utilisées telles quelles.

Contrairement à une requête normale, dans une requête Precognition les middlewares de route et la validation des form requests sont exécutés, mais pas le corps de la méthode du contrôleur.
C'est donc idéal pour la validation en temps réel pendant la saisie.

## Installation

Sous Laravel 13, il n'est pas nécessaire d'installer en plus le package backend `laravel/precognition`.
Vous n'avez besoin que du package d'aide côté frontend.

* Vue : `laravel-precognition-vue`
* React : `laravel-precognition-react`
* Alpine.js : `laravel-precognition-alpine`

```shell theme={null}
npm install laravel-precognition-vue
```

```shell theme={null}
npm install laravel-precognition-react
```

```shell theme={null}
npm install laravel-precognition-alpine
```

<Info>
  Inertia intègre le support de Precognition depuis la version 2.3. Il fonctionne également tel quel sous Inertia 3.
  Si vous utilisez les formulaires Inertia, il n'est généralement pas nécessaire d'ajouter `laravel-precognition-vue` / `laravel-precognition-react`.
</Info>

## Configuration backend

Ajoutez le middleware `HandlePrecognitiveRequests` à votre route.
Il est recommandé de regrouper les règles de validation dans une form request.
Cela facilite la réutilisation des règles et la séparation des responsabilités.

```php theme={null}
use App\Http\Requests\StoreUserRequest;
use Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests;
use Illuminate\Support\Facades\Route;

Route::post('/users', function (StoreUserRequest $request) {
    // Ce corps ne s'exécute que lors d'un envoi normal
})->middleware([HandlePrecognitiveRequests::class]);
```

Si un middleware personnalisé produit des effets de bord, ignorez-le lors d'une requête Precognition.

```php theme={null}
public function handle(Request $request, Closure $next): mixed
{
    if (! $request->isPrecognitive()) {
        Interaction::incrementFor($request->user());
    }

    return $next($request);
}
```

## Intégration frontend

### Alpine.js (Blade)

```html theme={null}
<form x-data="{
    form: $form('post', '/users', { name: '', email: '' }),
}">
    @csrf
    <input x-model="form.name" @change="form.validate('name')" />
    <template x-if="form.invalid('name')">
        <div x-text="form.errors.name"></div>
    </template>
</form>
```

### Vue (Inertia.js)

```vue theme={null}
<script setup>
import { useForm } from 'laravel-precognition-vue';

const form = useForm('post', '/users', {
    name: '',
    email: '',
});
</script>

<template>
    <input v-model="form.name" @change="form.validate('name')" />
    <div v-if="form.invalid('name')">{{ form.errors.name }}</div>
</template>
```

### React (Inertia.js)

```jsx theme={null}
import { useForm } from 'laravel-precognition-react';

const form = useForm('post', '/users', {
    name: '',
    email: '',
});

<input
    value={form.data.name}
    onChange={(e) => form.setData('name', e.target.value)}
    onBlur={() => form.validate('name')}
/>
```

### JavaScript vanille avec Axios

Les librairies Precognition utilisent Axios.
Si vous voulez utiliser votre instance Axios existante, injectez-la avec `client.use()`.

```js theme={null}
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);
```

## Contrôle du timing de validation

Pour valider champ par champ, utilisez `validate()`.

```js theme={null}
form.validate('email');
```

Vous pouvez ajuster le temps de debounce avec `setValidationTimeout()`.

```js theme={null}
form.setValidationTimeout(3000);
```

Pour valider les fichiers à chaque fois, utilisez `validateFiles()`.

```js theme={null}
form.validateFiles();
```

Les entrées en tableau se valident avec un joker.

```js theme={null}
form.validate('users.*.email');
```

## Helpers de formulaire

`useForm()` regroupe la gestion de l'envoi et des erreurs.

* `validating` : requête de validation en cours
* `processing` : envoi en cours
* `errors` : liste des erreurs
* `valid('field')` / `invalid('field')` : état de validation du champ
* `submit()` : envoi normal

```js theme={null}
const submit = () => form.submit()
    .then(() => form.reset());
```

## Comparaison entre requête normale et requête Precognition

Le schéma suivant illustre la différence de traitement entre les deux types de requête.

```mermaid theme={null}
sequenceDiagram
    participant User as Utilisateur
    participant Frontend as Frontend
    participant Server as Serveur Laravel

    User->>Frontend: Saisie du formulaire
    Frontend->>Server: Requête Precognition (en-tête Precognition: true)
    Server->>Server: Exécute la validation (sans exécuter la logique du contrôleur)
    Server-->>Frontend: Résultat de la validation
    Frontend-->>User: Affichage en temps réel des erreurs
    User->>Frontend: Envoi du formulaire
    Frontend->>Server: Requête normale
    Server-->>Frontend: Réponse
```

## Liens associés

* [Documentation officielle Laravel : Precognition](https://laravel.com/docs/precognition)
* [Documentation officielle Laravel : Validation](https://laravel.com/docs/validation)