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

> La funzionalità di Laravel per eseguire in tempo reale la validazione lato server prima dell'invio del form

## Cos'è Precognition

Precognition è un meccanismo che esegue la validazione lato server prima dell'invio del form.
Senza duplicare le regole di validazione nel frontend, puoi usare direttamente le regole di Laravel.

A differenza delle richieste normali, in una richiesta Precognition vengono eseguiti middleware di route e validazione delle form request, ma non il corpo del metodo controller.
Per questo è adatto alla validazione in tempo reale durante l'immissione.

## Installazione

In Laravel 13 non è necessario installare `laravel/precognition` sul backend.
Servono invece i pacchetti helper per il 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 integra il supporto a Precognition a partire dalla 2.3. Puoi usarlo così com'è anche con Inertia 3.
  Se usi i form Inertia, di norma non è necessaria l'installazione aggiuntiva di `laravel-precognition-vue` / `laravel-precognition-react`.
</Info>

## Configurazione del backend

Aggiungi il middleware `HandlePrecognitiveRequests` alla route.
In pratica conviene raccogliere le regole di validazione in una form request.
Raggruppandole nella form request ottieni riusabilità delle regole e migliore separazione delle responsabilità.

```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) {
    // Eseguito solo per l'invio normale
})->middleware([HandlePrecognitiveRequests::class]);
```

Se hai middleware personalizzati con effetti collaterali, saltali durante Precognition.

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

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

## Integrazione con il 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 vanilla con Axios

Le librerie Precognition usano Axios.
Per usare un'istanza Axios esistente, sostituiscila con `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);
```

## Controllo del timing di validazione

Per la validazione per singolo input usa `validate()`.

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

Il tempo di debounce si regola con `setValidationTimeout()`.

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

Se vuoi validare i file ogni volta usa `validateFiles()`.

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

Gli input array possono essere validati con wildcard.

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

## Helper per i form

`useForm()` consente di gestire in modo unificato lo stato di invio e di errore.

* `validating`: durante una richiesta di validazione
* `processing`: durante l'invio
* `errors`: elenco degli errori
* `valid('field')` / `invalid('field')`: stato di validazione del campo
* `submit()`: invio normale

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

## Confronto tra richiesta normale e Precognition

Il diagramma seguente mostra la differenza di elaborazione tra una richiesta normale e una richiesta Precognition.

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

    User->>Frontend: Compila il form
    Frontend->>Server: Richiesta Precognition (header Precognition: true)
    Server->>Server: Esegue la validazione (logica del controller non eseguita)
    Server-->>Frontend: Risultato della validazione
    Frontend-->>User: Mostra gli errori in tempo reale
    User->>Frontend: Invia il form
    Frontend->>Server: Richiesta normale
    Server-->>Frontend: Risposta
```

## Link correlati

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