Laravel Wayfinder

https://github.com/laravel/wayfinder
Admin
Laravel Wayfinder automatically generates fully-typed TypeScript functions for your Laravel routes...
Tokens:44,994
Snippets:326
Trust Score:9.7
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Test setup and generation command

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/service-provider.md

Shows a test setup that creates a table and route, then runs the artisan wayfinder:generate command with options and asserts success and output content.

```php
protected function setUp(): void
{
    parent::setUp();

    Schema::create('docblock_posts', function (Blueprint $table) {
        $table->id();
    });

    Route::get('/docblock-posts/{post}', fn (DocblockPost $post) => $post)
        ->name('docblock-posts.show');
}

public function test_skipping_the_database_reads_model_docblocks(): void
{
    $this->artisan('wayfinder:generate', [
        '--path' => $this->tempPath,
        '--skip-actions' => true,
        '--skip-database' => true,
    ])->assertSuccessful();

    $this->assertStringContainsString('post: string', $this->generatedFile());
}
```

--------------------------------

### Query options usage examples

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/generated-functions.md

Shows how to pass query options to generated route functions. The first example adds a query parameter, the second merges with the current window.location.search.

```TypeScript
show(1, { query: { page: 1 } });          // { url: "/posts/1?page=1", method: "get" }
```

```TypeScript
show.url(1, { mergeQuery: { q: "shirt" } }); // merges with window.location.search
```

--------------------------------

### Verb class usage example

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/typescript.md

Shows how to create Verb instances with different HTTP method strings and access the 'actual' and 'formSafe' properties. The example demonstrates that 'QUERY' is normalized to lowercase 'query' and its 'formSafe' is 'post' because QUERY is not a safe method, while 'get' has 'formSafe' as 'get'.

```php
$verb = new Verb('QUERY');
$verb->actual;    // 'query'
$verb->formSafe;  // 'post'  (QUERY is not get/head/options)

$verb = new Verb('get');
$verb->formSafe;  // 'get'
```

--------------------------------

### Install Wayfinder via Composer

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Run this command to install the Laravel Wayfinder package via Composer.

```bash
composer require laravel/wayfinder
```

--------------------------------

### Example: basic query with queryParams

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/js-runtime.md

Shows how to build a query string from a `query` object. The result is `?page=1&sort_by=name`.

```typescript
import { queryParams, type RouteQueryOptions } from "@/wayfinder";

const q = queryParams({ query: { page: 1, sort_by: "name" } });
// "?page=1&sort_by=name"
```

--------------------------------

### Install Wayfinder Vite plugin via NPM

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Run this command to install the Wayfinder Vite plugin as a dev dependency.

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

--------------------------------

### Type-name mapping example

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/binding-resolver.md

Shows how a model docblock with @property tags is mapped to columns. The example includes a docblock with three properties and the resulting columns array with name and type_name fields.

```php
// Model docblock:
// /**
//  * @property int $id
//  * @property string $name
//  * @property string|null $remember_token
//  */
// → columns: [{'name': 'id', 'type_name': 'int'}, {'name': 'name', 'type_name': 'string'}, {'name': 'remember_token', 'type_name': 'string|null'}]
```

--------------------------------

### Example: setUrlDefaults and applyUrlDefaults usage

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/js-runtime.md

Shows how to set a default locale and apply it to route arguments. The user-provided value wins when present.

```TypeScript
import { setUrlDefaults, applyUrlDefaults } from "@/wayfinder";

setUrlDefaults({ locale: "en" });

const args = applyUrlDefaults({ page: 2 }); // { page: 2, locale: "en" }
const args2 = applyUrlDefaults({ locale: "es" }); // { locale: "es" } — user value wins
```

--------------------------------

### show.get(id, options)

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Generates a URL with query parameters using the get method.

```APIDOC
## [METHOD] show.get(id, options)

### Description
Generates a URL for the show action with query parameters, explicitly using the get method.

### Method
METHOD

### Endpoint
show.get(id, options)

### Parameters
#### Path Parameters
- **id** (number) - Required - The resource identifier.

#### Query Parameters
- **query** (object) - Optional - An object of query parameters to append to the URL.

### Request Example
```ts
const options = {
    query: {
        page: 1,
        sort_by: "name",
    },
};

show.get(1, options);
```

### Response
#### Success Response (200)
- **url** (string) - The generated URL with query parameters, e.g., "/posts/1?page=1&sort_by=name"
- **method** (string) - The HTTP method, e.g., "get"

#### Response Example
```json
{
  "url": "/posts/1?page=1&sort_by=name",
  "method": "get"
}
```
```

--------------------------------

### Using .url() and other HTTP method helpers

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Shows how to get just the URL with .url() or choose a specific HTTP method (e.g., head) by calling the corresponding method on the generated function.

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

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

--------------------------------

### Example: merge with current location

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/js-runtime.md

Demonstrates `mergeQuery` mode, which merges with the current `window.location.search`. Passing `null` for a key deletes that parameter family.

```typescript
// window.location.search === "?page=1&sort_by=category&q=shirt"
const q = queryParams({ mergeQuery: { page: 2, sort_by: null } });
// "?page=2&q=shirt"   (sort_by deleted via null)
```

--------------------------------

### Merge with existing URL parameters using mergeQuery

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Shows how to use `mergeQuery` to merge with the URL's existing parameters. The example assumes `window.location.search` is `?page=1&sort_by=category&q=shirt`.

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

// window.location.search = "?page=1&sort_by=category&q=shirt"

const options = {
    mergeQuery: {
        page: 2,
        sort_by: "name",
    },
};

show.url(1, options); // "/posts/1?page=2&sort_by=name&q=shirt"
```

--------------------------------

### Invokable controller usage example

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/generated-functions.md

Shows how an invokable controller's default export is the invokable function itself, with additional actions attached as properties.

```typescript
InvokablePlusController();               // { url: "/invokable-plus-controller", method: "get" }
InvokablePlusController.store();         // { url: "/invokable-plus-controller", method: "post" }
```

--------------------------------

### Verb constructor

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/typescript.md

Constructor for the Verb class. It lower-cases the provided HTTP verb and sets `formSafe` to 'get' for GET, HEAD, and OPTIONS, otherwise 'post'. The `actual` parameter is a promoted property.

```php
public function __construct(public string $actual)
{
    $this->actual = strtolower($actual);

    $this->formSafe = in_array(strtolower($actual), ['get', 'head', 'options'], true) ? 'get' : 'post';
}
```

--------------------------------

### Generated docblock example

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/generated-functions.md

Each export carries a docblock from `docblock.blade.ts`. Includes `@see` references, optional `@param` for defaults, and `@route`.

```plaintext
/** @see App\Http\Controllers\PostController::show
 * @see <relative controller path>:<line>
 * @param post - Default: 'en'   (only for parameters with a resolved default)
 * @route /posts/{post}
 */
```

--------------------------------

### setUrlDefaults(params: UrlDefaults | (() => UrlDefaults)): void

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/js-runtime.md

Installs the URL-defaults provider. Accepts either a plain object or a getter function; the getter is invoked by applyUrlDefaults on every call. Returns undefined. Applications generally do not call this directly — defaults are baked into generated definitions.

```APIDOC
## setUrlDefaults(params: UrlDefaults | (() => UrlDefaults)): void

### Description
Installs the URL-defaults provider. Accepts either a plain object or a getter function; the getter is invoked by `applyUrlDefaults` on every call.

### Method
setUrlDefaults

### Signature
```ts
setUrlDefaults(params: UrlDefaults | (() => UrlDefaults)): void
```

### Parameters
- **params** (UrlDefaults | (() => UrlDefaults)) - Required - A plain object or a getter function returning the default URL parameters.

### Returns
`undefined`

### Source
`resources/js/wayfinder.ts:117`

### Notes
Applications generally do not call this directly — defaults are baked into generated definitions.
```

--------------------------------

### Example — bound model parameter

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/binding-resolver.md

Shows how to call resolveTypeAndKey() for a model-bound route parameter. The comment shows the route, controller, and model property. The result is $type = 'int', $key = 'id', leading to a generated signature of user: number.

```php
// Route: Route::get('/users/{user}', [ModelBindingController::class, 'show']);
// Controller: public function show(User $user) { ... }
// Model User: @property int $id

[$type, $key] = BindingResolver::resolveTypeAndKey('App\Models\User', null);
// $type = 'int', $key = 'id' → generated signature: user: number
```

--------------------------------

### Use Wayfinder with Inertia's Link component

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Use Wayfinder in conjunction with Inertia's Link component. The example shows a Link that navigates to the show action for the first post.

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

const Nav = () => <Link href={show(1)}>Show me the first post</Link>;
```

--------------------------------

### Generated signature example for bound parameter

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/parameter.md

Shows the TypeScript type emitted for a route parameter bound to a model with an integer ID column.

```typescript
user: number
```

--------------------------------

### Example — skip-database mode

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/binding-resolver.md

Command to generate with --skip-database. In this mode, getColumns() skips schema queries and uses parseDocBlock($model). Properties without @property tags fall back to 'string | number' in generated signatures.

```shell
php artisan wayfinder:generate --skip-database
```

--------------------------------

### Generate TypeScript definitions with custom path

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Use the --path option to change the base directory where Wayfinder generates files. The example sets the base path to resources/js/wayfinder.

```shell
php artisan wayfinder:generate --path=resources/js/wayfinder
```

--------------------------------

### URL and Option Shapes

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/generated-functions.md

The generated functions provide methods to build URLs with parameters and query options. The `url` method returns a string, while the `get` method accepts parameters and query options to return a route object.

```APIDOC
## URL and Option Shapes

### Description
The generated functions provide methods to build URLs with parameters and query options. The `url` method returns a string, while the `get` method accepts parameters and query options to return a route object.

### Method
N/A (Generated JavaScript/TypeScript functions)

### Endpoint
N/A

### Parameters
#### `url` method
- **id** (number) - Required - The route parameter value.

#### `get` method
- **post** (object) - Required - The route parameters (e.g., `{ post: 1 }`).
- **query** (object) - Optional - Query parameters (e.g., `{ page: 1 }`).

### Request Example
```ts
show.url({ id: 1 });
show.get({ post: 1 }, { query: { page: 1 } });
```

### Response
#### Success Response
- **url** (string) - The generated URL (e.g., "/posts/1").
- **method** (string) - The HTTP method (e.g., "get").

#### Response Example
```ts
"/posts/1"
{ url: "/posts/1?page=1", method: "get" }
```
```

--------------------------------

### Importing named routes

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Wayfinder can generate methods for named routes. Import from the routes directory and call the function to get the URL and method.

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

// Named route is `post.show`...
show(1); // { url: "/posts/1", method: "get" }
```

--------------------------------

### Use Wayfinder with Inertia's useForm submit method

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Pass the result of a Wayfinder method directly to the submit method of useForm. It automatically resolves the correct URL and method. The example shows a POST request to '/posts'.

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

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

form.submit(store()); // Will POST to `/posts`...
```

--------------------------------

### Basic Wayfinder function call returning URL and method

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Shows the default behavior of a Wayfinder-generated function: calling it returns an object with the resolved URL and the default HTTP method (get).

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

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

--------------------------------

### URL-Only and Custom Method Invocation

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Invoke additional methods on the Wayfinder function to get just the URL or to specify a different HTTP method.

```APIDOC
## URL-Only and Custom Method Invocation

### Description
Use `.url()` to get only the URL, or use a method name like `.head()` to get the URL with a specific HTTP method.

### Method
N/A (JavaScript function call)

### Endpoint
N/A

### Parameters
- **parameters** (any) - Required - Route parameters.

### Request Example
```ts
import { show } from "@/actions/App/Http/Controllers/PostController";
show.url(1); // "/posts/1"
show.head(1); // { url: "/posts/1", method: "head" }
```

### Response
#### Success Response
- For `.url()`: **string** - The resolved URL.
- For other methods: **object** with `url` and `method` properties.

#### Response Example
```ts
"/posts/1"
{ url: "/posts/1", method: "head" }
```
```

--------------------------------

### Example — invalid omission (error handling)

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/js-runtime.md

Shows a call that throws an Error because a non-trailing optional parameter is missing. The error message is "Unexpected optional parameters missing. Unable to generate a URL."

```TypeScript
import { validateParameters } from "@/wayfinder";

try {
    validateParameters({ two: "2" }, ["one", "two", "three"]);
} catch (error) {
    // Error: "Unexpected optional parameters missing. Unable to generate a URL."
    // `two` cannot be present while `one` is missing
}
```

--------------------------------

### setUrlDefaults function definition

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/js-runtime.md

Installs the URL-defaults provider. Accepts a plain object or a getter function; the getter is invoked by applyUrlDefaults on every call. Returns undefined. Applications generally do not call this directly.

```TypeScript
export const setUrlDefaults = (params: UrlDefaults | (() => UrlDefaults)) => {
    urlDefaults = typeof params === "function" ? params : () => params;
};
```

--------------------------------

### Basic Wayfinder Function Invocation

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Wayfinder functions return an object containing the resolved URL and default HTTP method. Call the function with route parameters to get the URL and method.

```APIDOC
## Wayfinder Function Invocation

### Description
Call the generated Wayfinder function to get an object with the resolved URL and default HTTP method.

### Method
N/A (JavaScript function call)

### Endpoint
N/A

### Parameters
- **parameters** (any) - Required - Route parameters, can be a single value, an array, or an object.

### Request Example
```ts
import { show } from "@/actions/App/Http/Controllers/PostController";
show(1);
```

### Response
#### Success Response
- **url** (string) - The resolved URL.
- **method** (string) - The default HTTP method (e.g., "get").

#### Response Example
```ts
{ url: "/posts/1", method: "get" }
```
```

--------------------------------

### boot() method signature

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/service-provider.md

The signature of the boot() method. It is called by the container during application boot and registers the wayfinder:generate command only in console mode.

```php
public function boot(): void
```

--------------------------------

### TypeScript::quoteIfNeeded

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/typescript.md

Quotes a name when it cannot be used as a bare property key in JavaScript, such as when it starts with a digit.

```APIDOC
## TypeScript::quoteIfNeeded

### Description
Quotes a name when it cannot be a bare property key in JavaScript. Numeric names are returned unchanged, but names starting with a digit are wrapped in quotes.

### Method
static quoteIfNeeded(string $name): string

### Parameters
- **name** (string) - Required - The name to check and potentially quote.

### Returns
- **string** - The name, quoted if necessary.

### Behavior
- If `is_numeric($name)`, returns unchanged (e.g., `404`).
- If first character is numeric, wraps in quotes (e.g., `"404"`).
- Otherwise returns unchanged.
```

--------------------------------

### Create Route instances from router routes

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/route.md

Maps over the router's routes to create Route instances, merging global URL defaults with middleware-specific defaults and applying the forced scheme and root.

```php
use Laravel\Wayfinder\Route;

$routes = collect($this->router->getRoutes())->map(function (BaseRoute $base) use ($globalUrlDefaults) {
    $defaults = $this->urlDefaultsForMiddleware($this->router->gatherRouteMiddleware($base));

    return new Route($base, $globalUrlDefaults->merge($defaults), $this->forcedScheme, $this->forcedRoot);
});
```

--------------------------------

### GenerateCommand::handle() method signature

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/generate-command.md

The public entry point that executes the generation run. It performs a series of steps including resolving middleware, registering the view namespace, computing URL defaults, and writing generated files. Returns void and does not declare any thrown exceptions.

```php
public function handle()
```

--------------------------------

### show(id, options)

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Generates a URL with query parameters appended.

```APIDOC
## [METHOD] show(id, options)

### Description
Generates a URL for the show action with optional query parameters appended.

### Method
METHOD

### Endpoint
show(id, options)

### Parameters
#### Path Parameters
- **id** (number) - Required - The resource identifier.

#### Query Parameters
- **query** (object) - Optional - An object of query parameters to append to the URL.

### Request Example
```ts
const options = {
    query: {
        page: 1,
        sort_by: "name",
    },
};

show(1, options);
```

### Response
#### Success Response (200)
- **url** (string) - The generated URL with query parameters, e.g., "/posts/1?page=1&sort_by=name"
- **method** (string) - The HTTP method, e.g., "get"

#### Response Example
```json
{
  "url": "/posts/1?page=1&sort_by=name",
  "method": "get"
}
```
```

--------------------------------

### show.url(id, options)

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Returns the URL string with query parameters.

```APIDOC
## [METHOD] show.url(id, options)

### Description
Returns the URL string for the show action with query parameters appended.

### Method
METHOD

### Endpoint
show.url(id, options)

### Parameters
#### Path Parameters
- **id** (number) - Required - The resource identifier.

#### Query Parameters
- **query** (object) - Optional - An object of query parameters to append to the URL.

### Request Example
```ts
const options = {
    query: {
        page: 1,
        sort_by: "name",
    },
};

show.url(1, options);
```

### Response
#### Success Response (200)
- **url** (string) - The generated URL string, e.g., "/posts/1?page=1&sort_by=name"

#### Response Example
```json
"/posts/1?page=1&sort_by=name"
```
```

--------------------------------

### Example — valid omission

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/js-runtime.md

Shows valid calls to validateParameters where only trailing optional parameters are missing. A value of "0" is considered present, not missing.

```TypeScript
import { validateParameters } from "@/wayfinder";

validateParameters({ one: "1" }, ["one", "two", "three"]); // ok — only trailing parts missing
validateParameters({ one: "0" }, ["one", "two", "three"]); // ok — 0 is present, not "missing"
```

--------------------------------

### addUrlDefault(key: string, value: string | number | boolean): void

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/js-runtime.md

Wraps the current defaults with one additional key (non-destructively). Repeated calls compose. Returns undefined.

```APIDOC
## addUrlDefault(key: string, value: string | number | boolean): void

### Description
Wraps the current defaults with one additional key (non-destructively). Repeated calls compose.

### Method
addUrlDefault

### Signature
```ts
addUrlDefault(key: string, value: string | number | boolean): void
```

### Parameters
- **key** (string) - Required - The key of the default to add.
- **value** (string | number | boolean) - Required - The value for the default.

### Returns
`undefined`

### Source
`resources/js/wayfinder.ts:121`
```

--------------------------------

### GenerateCommand constructor with injected dependencies

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/generate-command.md

Constructor injection of Filesystem, Router, View Factory, and UrlGenerator. These dependencies are used for file operations, route reading, template rendering, and URL configuration.

```php
public function __construct(
    private Filesystem $files,
    private Router $router,
    private Factory $view,
    private UrlGenerator $url,
) {
    parent::__construct();
}
```

--------------------------------

### Basic generation command

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/generate-command.md

Runs the Wayfinder generator with default options. This is the simplest invocation to generate actions and routes.

```shell
php artisan wayfinder:generate
```

--------------------------------

### TypeScript::safeMethod

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/typescript.md

Sanitizes a PHP name into a valid JavaScript identifier by replacing invalid characters, camelizing hyphens, handling reserved keywords, and ensuring a valid starting character.

```APIDOC
## TypeScript::safeMethod

### Description
Sanitizes a PHP name into a valid JavaScript identifier. It replaces non-alphanumeric characters with underscores, camelizes hyphens, appends a suffix for reserved keywords, and prepends a lower-cased suffix if the name starts with a digit.

### Method
static safeMethod(string $method, string $suffix): string

### Parameters
- **method** (string) - Required - Name to sanitize (controller method, route name segment, or parameter name)
- **suffix** (string) - Required - Suffix strategy: 'Method' or 'Param' — lower-cased for the prefix strategy

### Returns
- **string** - The JS-safe identifier.

### Examples
| Input | Suffix | Output |
|-------|--------|--------|
| `delete` | `Method` | `deleteMethod` |
| `404` | `Method` | `method404` |
| `default` | `Method` | `defaultMethod` |
| `show` | `Method` | `show` |
| `key` | `Param` | `key` |
| `class` | `Param` | `classParam` |
```

--------------------------------

### Route constructor with promoted properties

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/route.md

Defines the constructor for the Route adapter, accepting a base route, parameter defaults, forced scheme, and forced root. All parameters are stored as promoted private properties.

```php
public function __construct(
    private BaseRoute $base,
    private Collection $paramDefaults,
    private ?string $forcedScheme,
    private ?string $forcedRoot
) {
    //
}
```

--------------------------------

### quoteIfNeeded method signature

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/typescript.md

Signature for the static method that quotes a name when it cannot be a bare property key. Numeric names are returned unchanged, while names starting with a digit are wrapped in quotes.

```php
public static function quoteIfNeeded(string $name): string
```

--------------------------------

### show.form.head(id, options)

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Generates form attributes with HEAD method spoofing and query parameters.

```APIDOC
## [FORM] show.form.head(id, options)

### Description
Generates a `<form>` element's attributes for a HEAD request with query parameters appended.

### Method
FORM

### Endpoint
show.form.head(id, options)

### Parameters
#### Path Parameters
- **id** (number) - Required - The resource identifier.

#### Query Parameters
- **query** (object) - Optional - An object of query parameters to append to the URL.

### Request Example
```ts
const options = {
    query: {
        page: 1,
        sort_by: "name",
    },
};

show.form.head(1, options);
```

### Response
#### Success Response (200)
- **action** (string) - The form action URL with query parameters and `_method=HEAD`, e.g., "/posts/1?page=1&sort_by=name&_method=HEAD"
- **method** (string) - The HTTP method, e.g., "get"

#### Response Example
```json
{
  "action": "/posts/1?page=1&sort_by=name&_method=HEAD",
  "method": "get"
}
```
```

--------------------------------

### CI-safe generation with middleware defaults

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/generate-command.md

Clears cached routes and runs generation with `--path=resources/js`, `--with-form`, and `--skip-database`. `route:clear` avoids stale cached routes, and `--skip-database` documents model bindings from `@property` docblocks when the DB is unreachable.

```shell
php artisan route:clear
php artisan wayfinder:generate --path=resources/js --with-form --skip-database
```

--------------------------------

### Architecture pipeline diagram

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/index.md

Shows the generation flow from Router through Route adapter, Parameter/Verb models, GenerateCommand, Blade templates, to the output TypeScript files.

```text
Router → Route (adapter) → Parameter / Verb models
        ↓
GenerateCommand::handle()
        ↓
Blade templates (resources/method.blade.ts, multi-method.blade.ts,
                  function-arguments.blade.ts, docblock.blade.ts)
        ↓
resources/js/actions/... , resources/js/routes/... , resources/js/wayfinder/index.ts
```

--------------------------------

### resolveTypeAndKey() method signature

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/binding-resolver.md

Resolves [type, key] for a routable model class name. Boots the model instance once per routable, uses the route key name when $key is null, returns [null, $key] for non-Model instances, and resolves columns for Model instances. Returns a tuple [?string, ?string].

```php
public static function resolveTypeAndKey(string $routable, $key): array
```

--------------------------------

### Plain usage - no manual registration

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/service-provider.md

Shows that no application code is required because the provider is auto-discovered from composer.json. The comment indicates that php artisan wayfinder:generate becomes available via the provider's boot().

```php
// bootstrap/app.php — no manual registration needed
$app->loadProviders();
// `php artisan wayfinder:generate` is now available via this provider's boot()
```

--------------------------------

### Importing the entire controller and invoking methods

Source: https://github.com/laravel/wayfinder/blob/main/README.md

You can import the Wayfinder-generated controller definition and call its individual methods. Note that this prevents tree-shaking, so all actions will be included in the final bundle.

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

PostController.show(1);
```

--------------------------------

### wayfinder:generate command signature with options

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/generate-command.md

Defines the command signature with options for output path, skipping actions/routes/database, and generating form variants.

```php
protected $signature = 'wayfinder:generate {--path=} {--skip-actions} {--skip-routes} {--skip-database} {--with-form}';
```

--------------------------------

### safeMethod method signature

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/typescript.md

Signature for the static method that sanitizes a PHP name into a valid JS identifier. It replaces invalid characters, camelizes hyphens, appends a capitalized suffix for reserved keywords, and prepends a lower-cased suffix for names starting with a digit.

```php
public static function safeMethod(string $method, string $suffix): string
```

--------------------------------

### Importing named route for multiple routes to same action

Source: https://github.com/laravel/wayfinder/blob/main/README.md

In most cases it is easier to import the route by name from the generated routes directory. This shows the recommended approach.

```ts
import { index } from "@/routes/clients/payments";

index({ client: 1 }); // { url: "/clients/1/payments", method: "get" }
```

--------------------------------

### parameters method declaration

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/route.md

Returns a Collection of Parameter instances, one per route parameter name.

```php
public function parameters(): Collection
```

--------------------------------

### Append query parameters with options.query

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Shows how to pass a `query` object in the options argument to append query parameters to the resulting URL. Works with all Wayfinder methods, including `form.head`.

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

const options = {
    query: {
        page: 1,
        sort_by: "name",
    },
};

show(1, options); // { url: "/posts/1?page=1&sort_by=name", method: "get" }
show.get(1, options); // { url: "/posts/1?page=1&sort_by=name", method: "get" }
show.url(1, options); // "/posts/1?page=1&sort_by=name"
show.form.head(1, options); // { action: "/posts/1?page=1&sort_by=name&_method=HEAD", method: "get" }
```

--------------------------------

### addUrlDefault

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/configuration.md

Adds a single key-value pair to the current runtime default provider.

```APIDOC
## addUrlDefault

### Description
Adds a single key-value pair to the current runtime default provider.

### Signature
`addUrlDefault(key, value)`

### Parameters
- **key** (string) - Required - The key to add.
- **value** (any) - Required - The value to associate with the key.

### Returns
No return value specified.

```

--------------------------------

### Importing Controllers

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Import the Wayfinder generated controller definition and invoke its individual methods on the imported object.

```APIDOC
## Importing Controllers

### Description
Import the entire controller object and call its methods individually.

### Method
N/A (JavaScript function call)

### Endpoint
N/A

### Parameters
- **parameters** (any) - Required - Route parameters for the specific method.

### Request Example
```ts
import PostController from "@/actions/App/Http/Controllers/PostController";
PostController.show(1);
```

### Response
#### Success Response
- **url** (string) - The resolved URL.
- **method** (string) - The default HTTP method.

#### Response Example
```ts
{ url: "/posts/1", method: "get" }
```
```

--------------------------------

### skipDatabase() method signature

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/binding-resolver.md

Toggles docblock-based column resolution. When the flag changes value, the $columns cache is cleared. Returns void. Called by GenerateCommand::handle() with (bool) $this->option('skip-database').

```php
public static function skipDatabase(bool $skip): void
```

--------------------------------

### setUrlDefaults

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/configuration.md

Replaces the runtime default provider with a new provider, either a plain object or a function returning UrlDefaults.

```APIDOC
## setUrlDefaults

### Description
Replaces the runtime default provider with a new provider, either a plain object or a function returning UrlDefaults.

### Signature
`setUrlDefaults(params | () => UrlDefaults)`

### Parameters
- **params** (UrlDefaults | () => UrlDefaults) - Required - The new default provider, either a plain object or a function returning UrlDefaults.

### Returns
No return value specified.

```

--------------------------------

### show.url(id, options) with mergeQuery and null values

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Removes parameters from the URL by setting them to null or undefined.

```APIDOC
## [METHOD] show.url(id, options)

### Description
Returns the URL string with query parameters merged, removing any parameters set to null or undefined.

### Method
METHOD

### Endpoint
show.url(id, options)

### Parameters
#### Path Parameters
- **id** (number) - Required - The resource identifier.

#### Query Parameters
- **mergeQuery** (object) - Optional - An object of query parameters to merge; parameters with null or undefined values are removed.

### Request Example
```ts
// window.location.search = "?page=1&sort_by=category&q=shirt"

const options = {
    mergeQuery: {
        page: 2,
        sort_by: null,
    },
};

show.url(1, options);
```

### Response
#### Success Response (200)
- **url** (string) - The generated URL string with removed parameters, e.g., "/posts/1?page=2&q=shirt"

#### Response Example
```json
"/posts/1?page=2&q=shirt"
```
```

--------------------------------

### Generate TypeScript definitions with form variants

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Run this artisan command to opt into form variants when generating TypeScript definitions. This enables the `.form` variant for generating `<form>` object attributes.

```shell
php artisan wayfinder:generate --with-form
```

--------------------------------

### Skip actions or routes generation

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Use --skip-actions to skip generating TypeScript definitions for controller methods, or --skip-routes to skip generating definitions for routes. These options can be used independently.

```shell
php artisan wayfinder:generate --skip-actions
```

```shell
php artisan wayfinder:generate --skip-routes
```

--------------------------------

### show.url(id, options) with mergeQuery

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Merges query parameters with existing URL parameters.

```APIDOC
## [METHOD] show.url(id, options)

### Description
Returns the URL string with query parameters merged with existing URL parameters.

### Method
METHOD

### Endpoint
show.url(id, options)

### Parameters
#### Path Parameters
- **id** (number) - Required - The resource identifier.

#### Query Parameters
- **mergeQuery** (object) - Optional - An object of query parameters to merge with existing URL parameters.

### Request Example
```ts
// window.location.search = "?page=1&sort_by=category&q=shirt"

const options = {
    mergeQuery: {
        page: 2,
        sort_by: "name",
    },
};

show.url(1, options);
```

### Response
#### Success Response (200)
- **url** (string) - The generated URL string with merged parameters, e.g., "/posts/1?page=2&sort_by=name&q=shirt"

#### Response Example
```json
"/posts/1?page=2&sort_by=name&q=shirt"
```
```

--------------------------------

### QUERY Method Support

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Routes registered with the QUERY method receive a `query` method like any other verb.

```APIDOC
## QUERY Method Support

### Description
For routes registered with the QUERY method, the generated function can be called directly or via `.query()` to get the URL and method.

### Method
N/A (JavaScript function call)

### Endpoint
N/A

### Parameters
- **parameters** (any) - Optional - Route parameters.

### Request Example
```ts
import { search } from "@/actions/App/Http/Controllers/SearchController";
search(); // { url: "/search", method: "query" }
search.query(); // { url: "/search", method: "query" }
```

### Response
#### Success Response
- **url** (string) - The resolved URL.
- **method** (string) - "query".

#### Response Example
```ts
{ url: "/search", method: "query" }
```
```

--------------------------------

### Programmatic registration in a test suite

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/service-provider.md

Used by the package's feature tests to register the provider via getPackageProviders() in an Orchestra Testbench test case.

```php
use Laravel\Wayfinder\WayfinderServiceProvider;
use Orchestra\Testbench\TestCase;

class GenerationTest extends TestCase
{
    protected function getPackageProviders($app): array
    {
        return [WayfinderServiceProvider::class];
    }
}
```

--------------------------------

### controller method declaration

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/route.md

Returns the FQCN with a leading backslash, used in generated @see docblocks.

```php
public function controller(): string
```

--------------------------------

### Parameter constructor

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/parameter.md

Defines the constructor for the Parameter class, promoting properties and setting `$placeholder` and `$types` based on optionality and resolved types.

```php
public function __construct(
    public string $name,
    public bool $optional,
    public ?string $key,
    public ?string $default,
    public ?ReflectionParameter $bound = null,
) {
    $this->placeholder = $optional ? "{{$name}?}" : "{{$name}}";

    $this->types = implode(' | ', $this->resolveTypes());
}
```

--------------------------------

### Specify a method on the form variant

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Shows how to invoke additional methods on the `form` variant to specify a different HTTP method, such as `put`, which generates `_method=PUT` in the action.

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

const Page = () => (
    <form {...update.form.put(1)}>
        {/* <form action="/posts/1?_method=PUT" method="post"> */}
        {/* ... */}
    </form>
);
```

--------------------------------

### store.form()

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Generates form attributes for a POST request to the store action.

```APIDOC
## [FORM] store.form()

### Description
Generates a `<form>` element's attributes for submitting to the store endpoint via POST.

### Method
FORM

### Endpoint
store.form()

### Parameters
None

### Request Example
```tsx
<form {...store.form()}>
  {/* ... */}
</form>
```

### Response
#### Success Response (200)
- **action** (string) - The form action URL, e.g., "/posts"
- **method** (string) - The HTTP method, e.g., "post"

#### Response Example
```json
{
  "action": "/posts",
  "method": "post"
}
```
```

--------------------------------

### Multiple Routes to Same Action

Source: https://github.com/laravel/wayfinder/blob/main/README.md

When multiple routes point to the same controller method, the generated export becomes a dictionary keyed by URI (or verb-prefixed URI) instead of a callable.

```APIDOC
## Multiple Routes to Same Action

### Description
If two or more routes point to the same controller method, the generated export is a dictionary keyed by URI. If URIs are identical but verbs differ, keys are prefixed with the verb.

### Method
N/A (JavaScript object access)

### Endpoint
N/A

### Parameters
- **parameters** (any) - Required - Route parameters.

### Request Example
```ts
import { index } from "@/actions/App/Http/Controllers/ClientPaymentsController";
index["/clients/{client}/payments"]({ client: 1 });

import ExportController from "@/actions/App/Http/Controllers/ExportController";
ExportController["get /exports/{report}"]({ report: 1 });
ExportController["post /exports/{report}"]({ report: 1 });
```

### Response
#### Success Response
- **url** (string) - The resolved URL.
- **method** (string) - The HTTP method.

#### Response Example
```ts
{ url: "/clients/1/payments", method: "get" }
```
```

--------------------------------

### dotNamespace method declaration

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/route.md

Returns the controller's FQCN with leading backslash removed and remaining backslashes replaced by dots, used as a grouping key.

```php
public function dotNamespace(): string
```

--------------------------------

### Invokable Controllers

Source: https://github.com/laravel/wayfinder/blob/main/README.md

For invokable controllers, simply invoke the imported Wayfinder function directly.

```APIDOC
## Invokable Controllers

### Description
If the controller is invokable, the imported Wayfinder function can be called directly without specifying a method.

### Method
N/A (JavaScript function call)

### Endpoint
N/A

### Parameters
- **parameters** (any) - Optional - Route parameters.

### Request Example
```ts
import StorePostController from "@/actions/App/Http/Controllers/StorePostController";
StorePostController();
```

### Response
#### Success Response
- **url** (string) - The resolved URL.
- **method** (string) - The default HTTP method.

#### Response Example
```ts
{ url: "/store-post", method: "post" }
```
```

--------------------------------

### Importing Named Routes

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Wayfinder can generate methods for named routes, allowing import from the routes directory.

```APIDOC
## Importing Named Routes

### Description
For named routes, import the generated function from the routes directory and call it with parameters.

### Method
N/A (JavaScript function call)

### Endpoint
N/A

### Parameters
- **parameters** (any) - Required - Route parameters.

### Request Example
```ts
import { show } from "@/routes/post";
show(1); // { url: "/posts/1", method: "get" }
```

### Response
#### Success Response
- **url** (string) - The resolved URL.
- **method** (string) - The default HTTP method.

#### Response Example
```ts
{ url: "/posts/1", method: "get" }
```
```

--------------------------------

### verbs method declaration

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/route.md

Returns a Collection of Verb instances built from the base route's methods.

```php
public function verbs(): Collection
```

--------------------------------

### Use .form variant for conventional form submissions

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Shows how to use the `.form` variant to generate `<form>` attributes for store and update actions. The `update.form(1)` includes the `_method=PATCH` spoofing for HTML forms.

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

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

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

--------------------------------

### applyUrlDefaults<T extends UrlDefaults | undefined>(existing: T): T

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/js-runtime.md

Merges the runtime defaults into a caller-supplied argument object. Only keys that are undefined in the existing object and defined in the defaults are filled in; existing values always win. Returns the merged object (a new shallow copy when existing is an object).

```APIDOC
## applyUrlDefaults<T extends UrlDefaults | undefined>(existing: T): T

### Description
Merges the runtime defaults into a caller-supplied argument object. Only keys that are `undefined` in the existing object and defined in the defaults are filled in; existing values always win.

### Method
applyUrlDefaults

### Signature
```ts
applyUrlDefaults<T extends UrlDefaults | undefined>(existing: T): T
```

### Parameters
- **existing** (T extends UrlDefaults | undefined) - Required - The caller-supplied argument object.

### Returns
`T` — the merged object (a new shallow copy when `existing` is an object).

### Source
`resources/js/wayfinder.ts:133`

### Example
```ts
import { setUrlDefaults, applyUrlDefaults } from "@/wayfinder";

setUrlDefaults({ locale: "en" });

const args = applyUrlDefaults({ page: 2 }); // { page: 2, locale: "en" }
const args2 = applyUrlDefaults({ locale: "es" }); // { locale: "es" } — user value wins
```
```

--------------------------------

### Using the query method for QUERY routes

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Routes registered with the QUERY method receive a query method like any other verb. Calling the function directly or via .query() returns the URL and method.

```ts
import { search } from "@/actions/App/Http/Controllers/SearchController";

search(); // { url: "/search", method: "query" }
search.query(); // { url: "/search", method: "query" }
```

--------------------------------

### WayfinderServiceProvider class body

Source: https://github.com/laravel/wayfinder/blob/main/_autodocs/api-reference/service-provider.md

The full class body of WayfinderServiceProvider. It extends Illuminate\Support\ServiceProvider and registers GenerateCommand in boot() when running in console.

```php
class WayfinderServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        if ($this->app->runningInConsole()) {
            $this->commands([
                GenerateCommand::class,
            ]);
        }
    }
}
```

--------------------------------

### Configure Vite plugin in vite.config.js

Source: https://github.com/laravel/wayfinder/blob/main/README.md

Update your vite.config.js to include the wayfinder plugin, which watches for changes to routes and controllers.

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

export default defineConfig({
    plugins: [
        wayfinder(),
        // ...
    ],
});
```
Tokens:
Raw