Laravel Wayfinder 介紹

composer require laravel/wayfinder

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

import { wayfinder } from "@laravel/vite-plugin-wayfinder";
import { defineConfig } from "vite";
import laravel from "laravel-vite-plugin";

export default defineConfig({
    plugins: [
        laravel({
            input: ["resources/js/app.ts"],
            refresh: true,
        }),
        wayfinder(),
    ],
});

php artisan wayfinder:generate

resources/js/
├── actions/         # controller action 的函式
│   └── App/Http/Controllers/
│       └── PostController.ts
├── routes/          # 命名路由的函式
│   └── post.ts
└── wayfinder/       # 型別定義檔
    └── types.ts

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

php artisan wayfinder:generate --skip-actions  # 只產生路由
php artisan wayfinder:generate --skip-routes   # 只產生 action

import { show } from "@/actions/App/Http/Controllers/PostController";

show(1);
// { url: "/posts/1", method: "get" }

show.url(1); // "/posts/1"

show.head(1); // { url: "/posts/1", method: "head" }

import { update } from "@/actions/App/Http/Controllers/PostController";

// 單一參數
show(1);
show({ id: 1 });

// 多重參數
update([1, 2]);
update({ post: 1, author: 2 });
update({ post: { id: 1 }, author: { id: 2 } });

// 若路由為 /posts/{post:slug}
show("my-new-post");
show({ slug: "my-new-post" });

import PostController from "@/actions/App/Http/Controllers/PostController";

PostController.show(1);
PostController.index();

import StorePostController from "@/actions/App/Http/Controllers/StorePostController";

StorePostController(); // { url: "/posts", method: "post" }

import { show } from "@/routes/post";

// 若路由名稱為 `post.show`
show(1); // { url: "/posts/1", method: "get" }

import { show } from "@/actions/App/Http/Controllers/PostController";

show(1, { query: { page: 1, sort_by: "name" } });
// { url: "/posts/1?page=1&sort_by=name", method: "get" }

// 目前 URL: /posts/1?page=1&sort_by=category&q=shirt

show.url(1, { mergeQuery: { page: 2, sort_by: "name" } });
// "/posts/1?page=2&sort_by=name&q=shirt"

// 要刪除參數時指定為 null
show.url(1, { mergeQuery: { sort_by: null } });
// "/posts/1?page=1&q=shirt"

php artisan wayfinder:generate --with-form

import { store, update } from "@/actions/App/Http/Controllers/PostController";

// React 範例
const Page = () => (
    <form {...store.form()}>
        {/* <form action="/posts" method="post"> */}
    </form>
);

const EditPage = () => (
    <form {...update.form(1)}>
        {/* <form action="/posts/1?_method=PATCH" method="post"> */}
    </form>
);

import { useForm } from "@inertiajs/react";
import { store } from "@/actions/App/Http/Controllers/PostController";

const form = useForm({ name: "My Post" });

form.submit(store()); // 送到 POST /posts

import { Link } from "@inertiajs/react";
import { show } from "@/actions/App/Http/Controllers/PostController";

const Nav = () => (
    <Link href={show(1)}>查看貼文</Link>
);

// 若 controller 有 delete 方法
import { deleteMethod } from "@/actions/App/Http/Controllers/PostController";

deleteMethod(1); // { url: "/posts/1", method: "delete" }

composer require laravel/wayfinder:dev-next

class StorePostRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'title'   => ['required', 'string', 'max:255'],
            'content' => ['required', 'string'],
            'tags'    => ['nullable', 'array'],
            'tags.*'  => ['string'],
        ];
    }
}

export type Request = {
    title: string;
    content: string;
    tags?: string[] | null;
};

class User extends Model
{
    protected $casts = [
        'email_verified_at' => 'datetime',
        'is_admin' => 'boolean',
    ];

    public function posts(): HasMany
    {
        return $this->hasMany(Post::class);
    }
}

export namespace App.Models {
    export type User = {
        id: number;
        name: string;
        email: string;
        email_verified_at: string | null;
        is_admin: boolean;
        posts: App.Models.Post[];
    };
}

enum PostStatus: string
{
    case Draft = 'draft';
    case Published = 'published';
    case Archived = 'archived';
}

// 型別定義（types.d.ts）
export namespace App.Enums {
    export type PostStatus = "draft" | "published" | "archived";
}

// 常數（App/Enums/PostStatus.ts）
export const Draft = "draft";
export const Published = "published";
export const Archived = "archived";

export const PostStatus = { Draft, Published, Archived } as const;

resources/js/wayfinder/
├── App/Http/Controllers/
│   └── PostController.ts    # action 函式（廢除 actions/）
├── routes/
│   └── post.ts              # 命名路由（相同）
├── broadcast-channels.ts    # broadcast channel
├── broadcast-events.ts      # broadcast event
└── types.d.ts               # 所有型別定義（從 types.ts 變更）