• Introduction
• Installation
• Génération des définitions TypeScript
• Exemples
  • Controllers Invokable
  • Importer des controllers
  • Importer des routes nommés
  • Formulaires conventionnels
  • Query Parameters
• En savoir plus

# Introduction

Laravel Wayfinder fait le lien entre votre backend Laravel et votre frontend TypeScript sans aucune friction. Il génère automatiquement des fonctions TypeScript entièrement typées et importables pour vos contrôleurs et routes, vous permettant ainsi d’appeler vos endpoints Laravel directement dans votre code client comme n’importe quelle autre fonction. Plus besoin de coder en dur les URL, de deviner les paramètres de routes ou de synchroniser manuellement les changements du backend.

# Installation

Pour commencer, installez Wayfinder via le gestionnaire de paquets Composer.

1composer require laravel/wayfinder

Ensuite, installez le plugin Vite de Wayfinder afin de garantir que vos routes soient générées lors de l’étape de build de Vite, mais aussi à chaque modification de vos fichiers pendant l’exécution du serveur de développement de Vite.

1npm i -D @laravel/vite-plugin-wayfinder

Ensuite, mettez à jour le fichier vite.config.js de votre application afin de surveiller les modifications apportées à vos routes et contrôleurs :

1import { wayfinder } from "@laravel/vite-plugin-wayfinder";
2 
3export default defineConfig({
4    plugins: [
5        wayfinder(),
6        // ...
7    ],
8});

# Génération des définitions TypeScript

La commande wayfinder:generate peut être utilisée pour générer les définitions TypeScript de vos routes et méthodes de contrôleurs :

1php artisan wayfinder:generate

Par défaut, Wayfinder génère les fichiers dans trois répertoires (wayfinder, actions et routes) situés dans resources/js, mais vous pouvez configurer le chemin de base :

1php artisan wayfinder:generate --path=resources/js/wayfinder

Les options --skip-actions et --skip-routes peuvent être utilisées pour ignorer la génération des définitions TypeScript pour les méthodes des contrôleurs ou pour les routes, respectivement :

1php artisan wayfinder:generate --skip-actions
2php artisan wayfinder:generate --skip-routes

Vous pouvez en toute sécurité ajouter à .gitignore les répertoires wayfinder, actions et routes, car ils sont entièrement régénérés à chaque build.

# Exemples

Les fonctions de Wayfinder renvoient un objet contenant l’URL résolue ainsi que la méthode HTTP par défaut :

1import { show } from "@/actions/App/Http/Controllers/PostController";
2 
3show(1); // { url: "/posts/1", method: "get" }

Si vous avez seulement besoin de l’URL, ou si vous souhaitez choisir une méthode parmi celles définies sur le serveur, vous pouvez appeler des méthodes supplémentaires sur la fonction générée par Wayfinder :

1import { show } from "@/actions/App/Http/Controllers/PostController";
2 
3show.url(1); // "/posts/1"
4show.head(1); // { url: "/posts/1", method: "head" }

Les fonctions de Wayfinder acceptent différents formats pour leurs arguments :

 1import { show, update } from "@/actions/App/Http/Controllers/PostController";
 2 
 3// Single parameter action...
 4show(1);
 5show({ id: 1 });
 6 
 7// Multiple parameter action...
 8update([1, 2]);
 9update({ post: 1, author: 2 });
10update({ post: { id: 1 }, author: { id: 2 } });

# Controllers Invokable

Si votre contrôleur est un contrôleur invokable, vous pouvez simplement appeler directement la fonction Wayfinder importée :

1import StorePostController from "@/actions/App/Http/Controllers/StorePostController";
2 
3StorePostController();

# Importer des controllers

Vous pouvez également importer la définition du contrôleur générée par Wayfinder et appeler ses méthodes individuelles sur l’objet importé :

1import PostController from "@/actions/App/Http/Controllers/PostController";
2 
3PostController.show(1);

# Importer des routes nommés

Wayfinder peut également générer des méthodes pour les routes nommées de votre application :

1import { show } from "@/routes/post";
2 
3// Named route is `post.show`...
4show(1); // { url: "/posts/1", method: "get" }

# Formulaires conventionnels

Si votre application utilise des soumissions de formulaires HTML classiques, Wayfinder peut également vous aider. Commencez par activer les variantes de formulaires lors de la génération de vos définitions TypeScript :

1php artisan wayfinder:generate --with-form

Ensuite, vous pouvez utiliser la variante .form pour générer automatiquement les attributs des objets <form> :

 1import { store, update } from "@/actions/App/Http/Controllers/PostController";
 2 
 3const Page = () => (
 4    <form {...store.form()}>
 5        {/* <form action="/posts" method="post"> */}
 6        {/* ... */}
 7    </form>
 8);
 9 
10const Page = () => (
11    <form {...update.form(1)}>
12        {/* <form action="/posts/1?_method=PATCH" method="post"> */}
13        {/* ... */}
14    </form>
15);

1import { store, update } from "@/actions/App/Http/Controllers/PostController";
2 
3const Page = () => (
4    <form {...update.form.put(1)}>
5        {/* <form action="/posts/1?_method=PUT" method="post"> */}
6        {/* ... */}
7    </form>
8);

# Query Parameters

Toutes les méthodes de Wayfinder acceptent un dernier argument optionnel options, auquel vous pouvez passer un objet query. Cet objet permet d’ajouter des paramètres de requête à l’URL générée :

 1import { show } from "@/actions/App/Http/Controllers/PostController";
 2 
 3const options = {
 4    query: {
 5        page: 1,
 6        sort_by: "name",
 7    },
 8};
 9 
10show(1, options); // { url: "/posts/1?page=1&sort_by=name", method: "get" }
11show.get(1, options); // { url: "/posts/1?page=1&sort_by=name", method: "get" }
12show.url(1, options); // "/posts/1?page=1&sort_by=name"
13show.form.head(1, options); // { action: "/posts/1?page=1&sort_by=name&_method=HEAD", method: "get" }

# En savoir plus

• Documentation officielle : https://github.com/laravel/wayfinder