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

# Gérer correctement les entrées des URL signées

> Ce que protège une URL signée dans Laravel 13 et pourquoi récupérer les valeurs de requête signées avec query(), illustré par un exemple de lien à durée limitée.

## Objectif de cette page

Lorsque vous souhaitez utiliser tels quels les paramètres fixés à l'émission d'un lien de partage à durée limitée, il ne suffit pas de vérifier la signature de l'URL : il faut aussi être cohérent sur **l'endroit d'où vous lisez les valeurs**.
Cette page s'appuie sur un exemple qui inclut le type de rapport et le format de sortie dans l'URL, puis renvoie un JSON d'aperçu.

Elle concerne Laravel 13. Pour la génération d'URL en général, consultez [Génération d'URL](/fr/urls), et pour les bases de la récupération des entrées, [Requêtes HTTP](/fr/requests).

<Warning>
  La signature ne protège pas l'intégralité de la requête. Le corps d'un formulaire ou d'un JSON n'est pas signé.
  Après la vérification de la signature, récupérez les valeurs de requête signées avec `$request->query('format')`.
  `input()`, `all()` et les propriétés dynamiques peuvent renvoyer des valeurs non signées issues du corps. Cette distinction s'applique aussi aux requêtes GET.
</Warning>

## Ce que protège la signature

| Élément | Traitement |
| - | - |
| Chemin de l'URL | Inclus dans la vérification de la signature |
| Chaîne de requête | En principe incluse dans la vérification, à l'exception des paramètres explicitement ignorés |
| Schéma et hôte | Normalement inclus dans la signature, mais pas avec une signature relative |
| Corps de formulaire ou JSON | Non signé |
| Date d'expiration | Ajoutée par `temporarySignedRoute()` et contrôlée lors de la vérification |

`input()` est une API qui traite non seulement la chaîne de requête, mais aussi le corps. Lorsque Laravel fusionne ces entrées, les valeurs du corps ont priorité sur celles de la chaîne de requête.
`query()`, en revanche, ne récupère que la chaîne de requête.

Le succès de la vérification de la signature et le fait que les valeurs lues ensuite soient signées sont deux points distincts à contrôler.

```mermaid theme={null}
flowchart TD
    A["Accès via une URL à durée limitée"] --> B{"Middleware signed<br>vérifie la signature et l'expiration"}
    B -->|Invalide| C["Réponse 403"]
    B -->|Valide| D["Récupérer les valeurs de requête signées<br>avec query()"]
    D --> E["Valider le format et les valeurs autorisées"]
    E --> F["Renvoyer l'aperçu"]
```

## Implémenter un lien d'aperçu à durée limitée

### 1. Définir la route à vérifier

Dans `routes/web.php`, définissez une route nommée qui exige une signature.
Cet exemple ne manipule ni base de données ni fichier : il renvoie simplement les paramètres reçus.

```php theme={null}
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use Illuminate\Support\Facades\Validator;

Route::get('/reports/preview', function (Request $request) {
    $options = Validator::make([
        'report' => $request->query('report'),
        'format' => $request->query('format'),
    ], [
        'report' => ['required', 'string', 'in:monthly,annual'],
        'format' => ['required', 'string', 'in:csv,pdf'],
    ])->validate();

    return response()->json($options);
})->middleware('signed')->name('reports.preview');
```

* Le middleware `signed` vérifie la signature et la date d'expiration avant l'exécution de la closure. S'il échoue, il renvoie `403`.
* `query()` récupère explicitement depuis la chaîne de requête les valeurs utilisées par le traitement.
* La validation porte sur le tableau ainsi obtenu. La vérification de la signature ne garantit ni le type des valeurs ni leur conformité aux règles métier.

<Info>
  Dans cet exemple, seules les valeurs extraites avec `query()` sont transmises à `Validator::make()`.
  Si vous les remplacez par `$request->all()` à un endroit censé valider la requête signée, vous traiterez des entrées qui incluent le corps.
</Info>

### 2. Générer l'URL dans un traitement d'émission de confiance

Une fois la route nommée enregistrée, utilisez le code suivant dans le traitement qui émet le lien.
`report` et `format` ne sont pas des paramètres du chemin : ils sont donc ajoutés à la chaîne de requête.

```php theme={null}
use Illuminate\Support\Facades\URL;

$url = URL::temporarySignedRoute(
    'reports.preview',
    now()->addMinutes(30),
    ['report' => 'monthly', 'format' => 'csv'],
);
```

En plus des paramètres indiqués, cette URL contient `expires` et `signature`.
`expires` et `signature` sont des paramètres réservés utilisés par Laravel : ne les utilisez pas comme noms de paramètres métier.

Si vous exposez le traitement d'émission dans une application réelle, n'autorisez pas n'importe qui à émettre des liens avec des paramètres arbitraires, et appliquez l'[authentification](/fr/authentication) et l'[autorisation](/fr/authorization) nécessaires.

### 3. Vérifier l'utilisation normale

Si vous ouvrez l'URL émise telle quelle avant son expiration, le JSON suivant est renvoyé.

```json theme={null}
{
  "report": "monthly",
  "format": "csv"
}
```

Une fois le lien expiré, le middleware `signed` de la route renvoie `403`.
Une URL signée n'est pas un jeton à usage unique. Dans cet exemple, la même URL peut être réutilisée tant qu'elle n'a pas expiré.
Pour n'autoriser qu'une seule utilisation, vous devez gérer un état « déjà utilisé » indépendamment de la signature.

## Séparer les valeurs exclues de la vérification

Pour autoriser des valeurs ajoutées par le frontend, comme un numéro de page, vous pouvez les exclure de la vérification avec `hasValidSignatureWhileIgnoring(['page'])`.
Cependant, n'importe qui peut modifier les valeurs exclues : ne les traitez donc pas comme des paramètres signés.

Par exemple, `page`, utilisé pour l'affichage, n'a pas le même rôle que `report` et `format`, fixés à l'émission.
N'excluez pas, par simple commodité, les valeurs servant à déterminer les données ciblées, le destinataire, le tarif, etc.

<Warning>
  L'exemple ci-dessus utilise le middleware `signed` standard, donc `page` n'est pas exclu non plus.
  Si vous souhaitez ajouter des paramètres de requête, décidez d'abord, côté génération comme côté vérification, de ce qui doit être signé.
</Warning>

## Utiliser une signature relative

Si la conception n'inclut pas le domaine dans la signature, combinez `absolute: false` lors de la génération et `signed:relative` lors de la vérification.

```php theme={null}
$url = URL::temporarySignedRoute(
    'reports.preview',
    now()->addMinutes(30),
    ['report' => 'monthly', 'format' => 'csv'],
    absolute: false,
);
```

Dans ce cas, remplacez `middleware('signed')` par `middleware('signed:relative')` dans la route précédente.
Avec une signature relative, le corps n'est pas non plus signé : la règle de récupération via `query()` reste donc la même.

## Liste de contrôle pour l'implémentation

* La route de réception exige la vérification de la signature.
* Les valeurs de requête signées sont récupérées avec `query()`.
* Le format et les valeurs autorisées sont validés séparément.
* Les valeurs exclues de la vérification de la signature ne sont pas utilisées comme des paramètres fixés à l'émission.
* Le choix entre signature absolue et relative est cohérent entre la génération et la vérification.
* Connaître l'URL n'est pas assimilé aux droits de l'utilisateur connecté.

## Pages associées et sources

* [Génération d'URL](/fr/urls) : API des URL signées et réponse aux signatures invalides
* [Requêtes HTTP](/fr/requests) : récupération des entrées et de la chaîne de requête
* [Validation](/fr/validation) : validation du format des entrées et des valeurs autorisées
* [Documentation officielle de Laravel : Signed URLs](https://github.com/laravel/docs/blob/13.x/urls.md#signed-urls)
* [Documentation officielle de Laravel : Retrieving input from the query string](https://github.com/laravel/docs/blob/13.x/requests.md#retrieving-input-from-the-query-string)
* [Laravel Framework : UrlGenerator](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Routing/UrlGenerator.php)
* [Laravel Framework : ValidateSignature](https://github.com/laravel/framework/blob/13.x/src/Illuminate/Routing/Middleware/ValidateSignature.php)


## Related topics

- [Génération d'URL](/fr/urls.md)
- [Client de base - Laravel Bluesky](/fr/packages/laravel-bluesky/basic-client.md)
- [Fusion et cache de la configuration des packages](/fr/advanced/package-config-merging.md)
- [Laravel AI SDK](/fr/ai-sdk.md)
- [Guide de développement d'applications intégrées à l'API du moteur - VOICEVOX for Laravel](/fr/packages/laravel-voicevox/app-guide.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.