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

# Session

> Comment conserver des données entre les requêtes avec la session HTTP de Laravel.

## Qu'est-ce qu'une session

HTTP est un protocole sans état : il ne dispose pas nativement d'un moyen de conserver des informations d'un utilisateur entre les requêtes.
La session de Laravel fournit ce moyen sur plusieurs requêtes.

État de connexion, contenu d'un panier, valeurs saisies dans un formulaire… placez en session tout ce que vous voulez conserver entre les requêtes.

## Configuration du driver de session

La configuration se trouve dans `config/session.php`.
Vous changez le driver via la variable `SESSION_DRIVER` (dans `.env`).

```ini theme={null}
SESSION_DRIVER=database
```

Drivers pris en charge par défaut :

| Driver     | Description                                                         |
| ---------- | ------------------------------------------------------------------- |
| `file`     | Stocke en fichiers sous `storage/framework/sessions` (par défaut)   |
| `cookie`   | Stocke dans un cookie chiffré côté navigateur                       |
| `database` | Stocke dans une table de la base                                    |
| `redis`    | Stocke dans Redis (rapide)                                          |
| `array`    | Stocke dans un tableau PHP (utilisé pour les tests, non persistant) |

<Info>
  Le projet Laravel par défaut est configuré avec le driver `database`. Une table `sessions` est nécessaire, mais elle est fournie par la migration par défaut.
</Info>

## Accéder à la session

Deux façons d'accéder à la session : via une instance `Request`, ou via le helper global `session()`.

### Via l'instance Request

Recevez `Request` par type-hint dans la méthode de contrôleur, puis appelez `$request->session()`.

```php theme={null}
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\View\View;

class DashboardController extends Controller
{
    public function index(Request $request): View
    {
        $username = $request->session()->get('username');

        return view('dashboard', ['username' => $username]);
    }
}
```

### Via le helper `session()`

Le helper `session()` est utilisable depuis n'importe où (contrôleurs, vues…).

```php theme={null}
// Lire une valeur
$value = session('key');

// Avec une valeur par défaut
$value = session('key', 'valeur par défaut');

// Écrire une valeur
session(['key' => 'value']);
```

<Tip>
  Les deux approches se testent avec `assertSessionHas`. Dans un contrôleur, `$request->session()` rend la dépendance explicite.
</Tip>

## Opérations sur la session

### Lecture

```php theme={null}
// Lire une clé
$value = $request->session()->get('key');

// Avec valeur par défaut
$value = $request->session()->get('key', 'default');

// Valeur par défaut via une closure
$value = $request->session()->get('key', function () {
    return 'default';
});

// Toutes les données de session
$data = $request->session()->all();
```

### Vérification de présence

```php theme={null}
// true si présent et non null
if ($request->session()->has('user_id')) {
    // ...
}

// true si présent, même si null
if ($request->session()->exists('user_id')) {
    // ...
}

// true si absent
if ($request->session()->missing('user_id')) {
    // ...
}
```

Différence entre `has` et `exists` :

| Méthode  | Cas `null`       |
| -------- | ---------------- |
| `has`    | retourne `false` |
| `exists` | retourne `true`  |

### Écriture

```php theme={null}
// Via l'instance Request
$request->session()->put('user_name', 'Tanaka');

// Via le helper
session(['user_name' => 'Tanaka']);

// Ajouter à un tableau
$request->session()->push('cart.items', ['id' => 1, 'name' => 'Article A']);
```

### Suppression

```php theme={null}
// Supprimer une clé
$request->session()->forget('user_name');

// Plusieurs clés à la fois
$request->session()->forget(['user_name', 'cart']);

// Tout supprimer
$request->session()->flush();
```

## Données flash

Les données flash sont des données de session valides **uniquement pour la requête suivante**.
Utiles pour les messages de confirmation d'un formulaire ou les erreurs à afficher une seule fois.

### Enregistrer avec `flash()`

```php theme={null}
$request->session()->flash('status', 'Publication enregistrée.');
```

Elles restent disponibles à la requête suivante, puis sont automatiquement supprimées.

### Prolonger la durée des données flash

```php theme={null}
// Prolonge toutes les données flash d'une requête supplémentaire
$request->session()->reflash();

// Prolonge certaines clés uniquement
$request->session()->keep(['status', 'message']);
```

### Afficher un message flash dans Blade

```blade theme={null}
{{-- resources/views/layouts/app.blade.php --}}

@if (session('success'))
    <div class="alert alert-success">
        {{ session('success') }}
    </div>
@endif

@if (session('error'))
    <div class="alert alert-danger">
        {{ session('error') }}
    </div>
@endif
```

<Tip>
  Placez l'affichage des messages flash dans un layout (`layouts/app.blade.php`) pour un affichage cohérent sur toutes les pages.
</Tip>

## Exemple : message après envoi de formulaire

Après l'envoi d'un formulaire, enregistrer un message de succès en session et rediriger pour l'afficher à la page suivante est un pattern classique.

<Steps>
  <Step title="Définition des routes">
    ```php theme={null}
    use App\Http\Controllers\PostController;

    Route::get('/posts', [PostController::class, 'index'])->name('posts.index');
    Route::get('/posts/create', [PostController::class, 'create'])->name('posts.create');
    Route::post('/posts', [PostController::class, 'store'])->name('posts.store');
    ```
  </Step>

  <Step title="Implémentation du contrôleur">
    Dans `store`, après enregistrement, redirigez avec un message de succès.

    ```php theme={null}
    <?php

    namespace App\Http\Controllers;

    use App\Models\Post;
    use Illuminate\Http\RedirectResponse;
    use Illuminate\Http\Request;
    use Illuminate\View\View;

    class PostController extends Controller
    {
        public function index(): View
        {
            $posts = Post::latest()->get();

            return view('posts.index', ['posts' => $posts]);
        }

        public function create(): View
        {
            return view('posts.create');
        }

        public function store(Request $request): RedirectResponse
        {
            $validated = $request->validate([
                'title' => 'required|string|max:255',
                'body'  => 'required|string',
            ]);

            Post::create($validated);

            return redirect()
                ->route('posts.index')
                ->with('success', 'Publication créée.');
        }
    }
    ```

    `redirect()->with('success', '...')` est un raccourci qui pousse une donnée flash vers la destination.
  </Step>

  <Step title="Afficher le message dans le layout">
    Ajoutez l'affichage des messages flash à `resources/views/layouts/app.blade.php`.

    ```blade theme={null}
    <!DOCTYPE html>
    <html>
    <head>
        <title>My App</title>
    </head>
    <body>
        {{-- Messages flash --}}
        @if (session('success'))
            <div class="alert alert-success">
                {{ session('success') }}
            </div>
        @endif

        @if (session('error'))
            <div class="alert alert-danger">
                {{ session('error') }}
            </div>
        @endif

        @yield('content')
    </body>
    </html>
    ```
  </Step>

  <Step title="Créer la vue de liste">
    ```blade theme={null}
    {{-- resources/views/posts/index.blade.php --}}

    @extends('layouts.app')

    @section('content')
    <h1>Liste des publications</h1>

    @foreach ($posts as $post)
        <div>
            <h2>{{ $post->title }}</h2>
            <p>{{ $post->body }}</p>
        </div>
    @endforeach
    @endsection
    ```

    Après enregistrement puis redirection, la page affiche une fois le message « Publication créée. ».
  </Step>
</Steps>

### Combinaison avec les erreurs de validation

En cas d'échec de validation, combinez avec `back()->withErrors()`.
Laravel place automatiquement les erreurs en flash data : la variable `$errors` est disponible dans Blade.

```php theme={null}
public function store(Request $request): RedirectResponse
{
    $validated = $request->validate([
        'title' => 'required|string|max:255',
        'body'  => 'required|string',
    ]);

    Post::create($validated);

    // Succès : redirection avec message flash
    return redirect()
        ->route('posts.index')
        ->with('success', 'Publication créée.');

    // En cas d'échec de validation, Laravel exécute automatiquement back()->withErrors()->withInput()
}
```

```blade theme={null}
{{-- Page du formulaire --}}

@if ($errors->any())
    <div class="alert alert-danger">
        <ul>
            @foreach ($errors->all() as $error)
                <li>{{ $error }}</li>
            @endforeach
        </ul>
    </div>
@endif

<form method="POST" action="{{ route('posts.store') }}">
    @csrf

    <div>
        <label for="title">Titre</label>
        <input
            id="title"
            type="text"
            name="title"
            value="{{ old('title') }}"
        />
        @error('title')
            <span>{{ $message }}</span>
        @enderror
    </div>

    <div>
        <label for="body">Contenu</label>
        <textarea id="body" name="body">{{ old('body') }}</textarea>
        @error('body')
            <span>{{ $message }}</span>
        @enderror
    </div>

    <button type="submit">Publier</button>
</form>
```

<Warning>
  `flush()` supprime toutes les données de session, y compris l'état de connexion. Utilisez plutôt `forget()` pour cibler des clés précises.
</Warning>

## Prochaines étapes

<Card title="Validation" icon="check-circle" href="/fr/validation">
  Découvrez comment valider les données saisies dans les formulaires.
</Card>


## Related topics

- [Cloud Sessions](/fr/packages/laravel-copilot-sdk/cloud-sessions.md)
- [Remote Sessions](/fr/packages/laravel-copilot-sdk/remote-sessions.md)
- [SessionConfig](/fr/packages/laravel-copilot-sdk/session-config.md)
- [Reprise de session](/fr/packages/laravel-copilot-sdk/resume.md)
- [SessionEvent](/fr/packages/laravel-copilot-sdk/session-event.md)