Inertia.js Laravel Adapter

https://github.com/inertiajs/inertia-laravel
Admin
The Inertia.js Laravel Adapter enables seamless integration of Inertia.js with the Laravel PHP...
Tokens:89,501
Snippets:708
Trust Score:9.1
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### inertia:start-ssr

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/artisan-commands.md

Starts the Inertia SSR server using the configured runtime and bundle. Supports a --runtime option to specify the executable.

```APIDOC
## [ARTISAN] inertia:start-ssr

### Description
Starts the Inertia SSR server. Launches the configured runtime and bundle as a Symfony Process.

### Command
`php artisan inertia:start-ssr [--runtime=RUNTIME]`

### Options
- **--runtime** (string) - Optional - The runtime to use (e.g. `node`, `bun`, or an absolute path). Defaults to `config('inertia.ssr.runtime', 'node')`.

### Example
```bash
php artisan inertia:start-ssr
php artisan inertia:start-ssr --runtime=bun
```

### Failure Conditions
- Returns `FAILURE` if `inertia.ssr.enabled` is false.
- Returns `FAILURE` if no bundle is found via `BundleDetector`.
- Returns `FAILURE` if `inertia.ssr.ensure_runtime_exists` is true and the runtime is not found.

### Behavior
Stops a running server, launches the process, installs signal handlers, and streams output.
```

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

### Run inertia:start-ssr command

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/artisan-commands.md

Starts the Inertia SSR server. Use --runtime to specify a runtime other than the default (node).

```bash
php artisan inertia:start-ssr
php artisan inertia:start-ssr --runtime=bun
```

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

### Returning a Response directly from a controller

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/response.md

A Response is Responsable, so controllers can return it directly. This example returns a page with related posts data.

```php
public function show(User $user)
{
    return Inertia::render('Users/Show', ['user' => $user])->with('posts', $user->posts);
}
```

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

### Custom HandleInertiaRequests middleware

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/middleware.md

Example of extending Inertia\Middleware to share data and use shareOnce. Includes rootView, withAllErrors, share, and shareOnce methods.

```php
namespace App\Http\Middleware;

use Illuminate\Http\Request;
use Inertia\Middleware;

class HandleInertiaRequests extends Middleware
{
    protected $rootView = 'app';

    protected $withAllErrors = true;

    public function share(Request $request): array
    {
        return [
            ...parent::share($request),
            'auth' => [
                'user' => $request->user()?->only('id', 'name', 'email'),
            ],
            'flash' => [
                'message' => session('message'),
            ],
        ];
    }
    
    public function shareOnce(Request $request): array
    {
        return [
            'user.online' => fn () => Cache::get('user-online-'.$request->user()->id),
        ];
    }
}
```

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

### Applying fragment-following redirect behavior

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/middleware.md

Example of overriding the handle method to customize redirect behavior. Comments note that 409 synthetic responses are fine and real redirects are untouched.

```php
public function handle(Request $request, Closure $next): Response
{
    $response = parent::handle($request, $next);

    // 409 synthetic responses are fine; real redirects are untouched
    return $response;
}
```

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

### GET /_inertia/devtools/entries/{id}

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/endpoints.md

Retrieves the full recorded entry for a given ULID entry ID. Returns 404 if the ID is not a valid ULID or no entry file exists, and 403 if not authorized.

```APIDOC
## [GET] /_inertia/devtools/entries/{id}

### Description
Retrieves the full recorded entry for a given ULID entry ID. Returns 404 if the ID is not a valid ULID or no entry file exists, and 403 if not authorized.

### Method
GET

### Endpoint
/_inertia/devtools/entries/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - ULID entry id

### Response
#### Success Response (200)
- **__meta** (object) - Entry metadata (same structure as index rows)
- **http** (object) - HTTP request/response details
  - **requestHeaders** (object) - Request headers
  - **responseHeaders** (object) - Response headers
  - **requestBody** (object) - Request body capture state
  - **responseBody** (object) - Response body capture state
- **props** (object) - Props
- **propValues** (object) - Prop values
- **route** (object) - Route information
- **renderSource** (object) - Render source file and line
- **componentPath** (string) - Component path

#### Response Example
```json
{
  "__meta": { "id": "…", "tabUuid": null, "batchId": null, "timestamp": "…", "utime": 1.7e9, "method": "GET", "url": "…", "component": "…", "requestType": "navigate", "status": 200, "redirectLocation": null, "serverTimingMs": 12.5, "visitId": null },
  "http": {
    "requestHeaders": {},
    "responseHeaders": {},
    "requestBody": { "status": "empty" },
    "responseBody": { "status": "present", "value": { "component": "…", "props": {}, "url": "/", "version": "" } }
  },
  "props": {},
  "propValues": {},
  "route": { "name": null, "uri": "/", "action": "…", "actionSource": { "file": "…", "line": 1 } },
  "renderSource": { "file": "…", "line": 10 },
  "componentPath": "…"
}
```

#### Error Responses
- **404** - `id` is not a ULID or no entry file exists (`abort(404, 'Not found.')`)
- **403** - Not authorized
```

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

### ReloadRequest constructor and __invoke signature

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/testing.md

Internal helper class constructor and invocation method signature. __invoke() sends GET $url with X-Inertia-Version header, and adds partial headers when only/except are non-blank.

```php
public function __construct(
    protected string $url,
    protected string $component,
    protected string $version,
    protected ?string $only = null,
    protected ?string $except = null,
    protected ?Application $app = null,
)

public function __invoke(): TestResponse
```

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

### Using helpers and request->inertia() check

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/service-provider.md

Shows how to use the inertia() and inertia_location() helpers, and how to check if a request is an Inertia request with $request->inertia(). For client-side visits, return JSON or 409 location responses.

```php
use function inertia;
use function inertia_location;

inertia('Users/Index', ['users' => User::all()]);

if ($request->inertia()) {
    // client-side visit — return JSON or 409 location responses
    return inertia_location('https://example.com/moved');
}
```

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

### GET {ssr.url}/shutdown

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/endpoints.md

Shuts down the SSR server. The connection closing (CURLE_GOT_NOTHING) is treated as success.

```APIDOC
## [GET] {ssr.url}/shutdown

### Description
Shuts down the SSR server. The connection closing (CURLE_GOT_NOTHING) is treated as success.

### Method
GET

### Endpoint
{ssr.url}/shutdown

### Response
#### Success Response
No specific response body is documented; a closed connection is treated as success.
```

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

### GET {ssr.url}/health

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/endpoints.md

Checks the health of the SSR server. A successful (2xx) response indicates the server is healthy.

```APIDOC
## [GET] {ssr.url}/health

### Description
Checks the health of the SSR server. A successful (2xx) response indicates the server is healthy.

### Method
GET

### Endpoint
{ssr.url}/health

### Response
#### Success Response (200)
No specific response body is documented; a 2xx status indicates health.
```

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

### ResolvesOnce::as()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Sets a custom key for the once prop. BackedEnum → `value`, UnitEnum → `name`.

```APIDOC
## ResolvesOnce::as()

### Description
Sets a custom key for the once prop. BackedEnum → `value`, UnitEnum → `name`.

### Method
as

### Endpoint
ResolvesOnce::as(BackedEnum|UnitEnum|string $key)

### Parameters
#### Path Parameters
- **$key** (BackedEnum|UnitEnum|string) - Required - The custom key.

### Response
#### Success Response
- **static** - Returns the instance for chaining.
```

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

### Disable SSR usage examples

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/ssr.md

Shows how to disable SSR globally or conditionally, and exclude specific paths from SSR.

```php
use Inertia\Inertia;

// Disable SSR for all requests (e.g. during maintenance)
Inertia::disableSsr();

// Disable SSR conditionally
Inertia::disableSsr(fn () => $request->is('admin/*'));

// Exclude paths entirely
Inertia::withoutSsr(['/excel-export', '/api/*']);
```

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

### ProvidesInertiaProperties interface

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Implement to provide keyed props via toInertiaProperties(). Objects can be passed to share()/render() or included in props arrays with numeric keys.

```php
interface ProvidesInertiaProperties
{
    public function toInertiaProperties(RenderContext $context): iterable;
}
```

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

### isHealthy(): bool

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/ssr.md

Checks the health of the SSR server by sending a GET request to the health endpoint. Returns true if the request succeeds.

```APIDOC
## `isHealthy(): bool`

### Description
Checks the health of the SSR server by sending a GET request to the health endpoint. Returns true if the request succeeds.

### Method
GET

### Endpoint
`{url}/health`

### Response
- Returns `true` if the GET request succeeds.
- `StrayRequestException` is rethrown; other `Exception` instances return `false`.
```

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

### Equivalent Blade components with <x-inertia::head> and <x-inertia::app>

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/service-provider.md

Alternative root view using Blade components. <x-inertia::head> includes the Vite directive, and <x-inertia::app> renders the app container.

```blade
<html>
<head>@inertia</head>
<body>
    <x-inertia::head>@vite('resources/js/app.js')</x-inertia::head>
    <x-inertia::app id="app" />
</body>
</html>
```

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

### Objects providing props via ProvidesInertiaProperties

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Defines a class implementing ProvidesInertiaProperties to yield props, then shares it with Inertia::share, which resolves per render.

```php
use Inertia\ProvidesInertiaProperties;
use Inertia\RenderContext;

class LayoutData implements ProvidesInertiaProperties
{
    public function toInertiaProperties(RenderContext $context): iterable
    {
        yield 'layout' => ['theme' => session('theme', 'light')];
    }
}

Inertia::share(new LayoutData); // resolved per render
```

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

### Inertia::render with optional, defer, merge, scroll, always, and once props

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Shows how to use Inertia's prop helpers in a single render call: optional for partial reloads, defer for client-side loading, merge for merging with client data, scroll for infinite scroll, always for props present during partial reloads, and once for caching per client visit with custom key and expiry.

```php
use Inertia\Inertia;

return Inertia::render('Users/Index', [
    // loaded on demand via partial reload
    'filters' => Inertia::optional(fn () => $filters),

    // loaded by the client after first paint (group "default")
    'stats' => Inertia::defer(fn () => $stats, group: 'stats', rescue: true),

    // merged with client-side data on partial reload
    'users' => Inertia::merge($paginator->items()),

    // paginated infinite scroll data with computed cursors
    'posts' => Inertia::scroll($paginator),

    // always present even during partial reloads
    'site' => Inertia::always(['name' => config('app.name')]),

    // resolved once per client visit, custom key with expiry
    'banner' => Inertia::once(fn () => Banner::current())->as('banner')->until(now()->addHour()),
]);
```

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

### EntriesController index method signature

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/devtools.md

Handles GET requests to list devtools entries. Supports query parameters for filtering and pagination.

```php
public function index(Request $request): Collection
```

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

### ResolvesOnce::once()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Enables once behavior, optionally setting key and TTL. Once-props are sent once per client visit.

```APIDOC
## ResolvesOnce::once()

### Description
Enables once behavior, optionally setting key and TTL. Once-props are sent once per client visit.

### Method
once

### Endpoint
ResolvesOnce::once(bool $value = true, ?string $as = null, DateTimeInterface|DateInterval|int|null $until = null)

### Parameters
#### Path Parameters
- **$value** (bool) - Optional - Whether to enable once behavior. Defaults to true.
- **$as** (string|null) - Optional - Custom key.
- **$until** (DateTimeInterface|DateInterval|int|null) - Optional - Expiration delay.

### Response
#### Success Response
- **static** - Returns the instance for chaining.
```

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

### Onceable::as()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Sets a custom key for the once prop. BackedEnum → `value`, UnitEnum → `name`.

```APIDOC
## Onceable::as()

### Description
Sets a custom key for the once prop. BackedEnum → `value`, UnitEnum → `name`.

### Method
as

### Endpoint
Onceable::as(BackedEnum|UnitEnum|string $key)

### Parameters
#### Path Parameters
- **$key** (BackedEnum|UnitEnum|string) - Required - The custom key.

### Response
#### Success Response
- **static** - Returns the instance for chaining.
```

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

### Flash assertions with assertInertiaFlash and hasFlash

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/testing.md

Asserts session flash and page payload flash messages after a redirect and subsequent GET request.

```php
$this->post('/users', $valid)->assertRedirect('/users');
$this->get('/users')
    ->assertInertiaFlash('success', 'User created.')
    ->assertInertia(fn (AssertableInertia $page) => $page->hasFlash('success', 'User created.'));
```

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

### EntriesRepository class constructor and public methods

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/devtools.md

Defines the disk storage repository for DevTools entries. The constructor accepts a storage path, an auto-prune interval in hours (default 24), and a Filesystem instance. save() throws InvalidArgumentException for non-ULID ids and writes atomically via Filesystem::replace; all() returns index entries newest first; prune() deletes entries older than the given hours; enforceTabLimit() keeps the newest entries per tab UUID; pruneIfDue() prunes based on the prune_interval config (default 300 seconds) and rebuilds a missing or corrupt index.

```php
public function __construct(
    protected string $path,
    protected int $autoPruneHours = 24,
    protected Filesystem $files = new Filesystem,
)

public function save(string $id, array $data): void
public function get(string $id): ?array
public function all(): array
public function prune(int $hours): void
public function enforceTabLimit(string $tabUuid, int $limit): void
public function pruneIfDue(): void
```

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

### EnsureGetOnRedirect handle method

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/middleware.md

Converts 302 responses to 303 for Inertia requests using PUT/PATCH/DELETE, ensuring the follow-up is a GET. Registered for every kernel by ServiceProvider::registerRedirectMiddleware().

```php
public function handle(Request $request, Closure $next): Response
```

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

### ResolvesOnce::fresh()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Forcefully sends the prop to the client even if already loaded. Once-props are sent once per client visit.

```APIDOC
## ResolvesOnce::fresh()

### Description
Forcefully sends the prop to the client even if already loaded. Once-props are sent once per client visit.

### Method
fresh

### Endpoint
ResolvesOnce::fresh(bool $value = true)

### Parameters
#### Path Parameters
- **$value** (bool) - Optional - Whether to force sending. Defaults to true.

### Response
#### Success Response
- **static** - Returns the instance for chaining.
```

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

### version($version): void

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/response-factory.md

Sets the asset version sent to the client. Accepts a string or a closure that resolves the version.

```APIDOC
## version($version): void

### Description
Sets the asset version sent to the client. Accepts a string or a closure that resolves the version.

### Method
Method

### Signature
`version($version): void`

### Parameters
- **version** (Closure|string|null) - Required - Asset version, or a closure resolving it.

### Behavior
Closures are resolved via `App::call()`.

### Example
```php
Inertia::version(fn () => md5_file(public_path('js/app.js')));
```
```

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

### Basic render through the Inertia facade

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/response-factory.md

Renders a page component with props using Inertia::render. The route returns the Inertia response for the 'Users/Index' component, passing all users and the current search filter as props. Requires the Inertia facade and a User model.

```php
use Inertia\Inertia;

Route::get('/users', function () {
    return Inertia::render('Users/Index', [
        'users' => User::all(),
        'filters' => request('search'),
    ]);
});
```

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

### GET /_inertia/devtools/entries

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/endpoints.md

Retrieves a paginated list of entry metadata (index rows) from the DevTools entries repository, newest first. Supports filtering by component, request type, and pagination via offset and limit.

```APIDOC
## [GET] /_inertia/devtools/entries

### Description
Retrieves a paginated list of entry metadata (index rows) from the DevTools entries repository, newest first. Supports filtering by component, request type, and pagination via offset and limit.

### Method
GET

### Endpoint
/_inertia/devtools/entries

### Parameters
#### Query Parameters
- **component** (string) - Optional - Filter entries whose `component` equals this value
- **type** (string, comma-separated) - Optional - Include only entries whose `requestType` is in the list
- **exclude** (string, comma-separated) - Optional - Exclude entries whose `requestType` is in the list
- **offset** (int) - Optional, default: 0 - Skip `offset` entries (`max(0, …)`)
- **limit** (int) - Optional - Take at most `limit` entries (`max(1, …)`)

### Response
#### Success Response (200)
- **id** (string) - ULID entry id
- **tabUuid** (string|null) - Tab UUID
- **batchId** (string|null) - Batch ID
- **timestamp** (string) - ISO 8601 timestamp
- **utime** (number) - Unix timestamp with milliseconds
- **method** (string) - HTTP method
- **url** (string) - Request URL
- **component** (string|null) - Component name
- **requestType** (string) - One of: `navigate`, `partial`, `deferred`, `poll`, `prefetch`, `initial`, `http`, `precognition`
- **status** (integer) - HTTP status code
- **redirectLocation** (string|null) - Redirect location
- **serverTimingMs** (number) - Server timing in milliseconds
- **visitId** (string|null) - Visit ID

#### Response Example
```json
{
  "id": "01J…ULID",
  "tabUuid": "…|null",
  "batchId": "…|null",
  "timestamp": "2026-10-21T12:00:00.000Z",
  "utime": 1771612800.123,
  "method": "GET",
  "url": "https://…",
  "component": "Users/Index|null",
  "requestType": "navigate",
  "status": 200,
  "redirectLocation": null,
  "serverTimingMs": 12.5,
  "visitId": "…|null"
}
```
```

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

### shareOnce(string $key, callable $callback): OnceProp

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/response-factory.md

Creates a OnceProp from the callback and immediately shares it under the given key.

```APIDOC
## shareOnce(string $key, callable $callback): OnceProp

### Description
Creates a OnceProp from the callback and immediately shares it under the given key.

### Method
shareOnce

### Parameters
- **key** (string) - Required - The key under which to share the prop
- **callback** (callable) - Required - The callback to resolve

### Returns
OnceProp
```

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

### version() method signature

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/response-factory.md

Sets the asset version sent to the client. Accepts a string, null, or a Closure that is resolved via App::call().

```php
public function version($version): void
```

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

### ScrollMetadata constructor and fromPaginator signature

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Constructor accepts page name and optional pagination values. fromPaginator() unwraps JsonResource and handles CursorPaginator, LengthAwarePaginator, and Paginator; throws InvalidArgumentException for other values.

```php
public function __construct(
    protected string $pageName,
    protected int|string|null $previousPage = null,
    protected int|string|null $nextPage = null,
    protected int|string|null $currentPage = null,
)

public static function fromPaginator(mixed $value): self
```

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

### Mergeable::prependsAtRoot()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Returns true when prepending and no nested paths are set. Merging metadata is emitted as `prependProps` on the page object.

```APIDOC
## Mergeable::prependsAtRoot()

### Description
Returns true when prepending and no nested paths are set. Merging metadata is emitted as `prependProps` on the page object.

### Method
prependsAtRoot

### Endpoint
Mergeable::prependsAtRoot()

### Parameters
None

### Response
#### Success Response
- **bool** - True if prepending at root.
```

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

### Mergeable::prependsAtPaths()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Returns the nested prepend paths. Merging metadata is emitted as `prependProps` on the page object.

```APIDOC
## Mergeable::prependsAtPaths()

### Description
Returns the nested prepend paths. Merging metadata is emitted as `prependProps` on the page object.

### Method
prependsAtPaths

### Endpoint
Mergeable::prependsAtPaths()

### Parameters
None

### Response
#### Success Response
- **array** - The nested prepend paths.
```

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

### ResolvesOnce::getKey()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Returns the custom once key. Once-props are sent once per client visit.

```APIDOC
## ResolvesOnce::getKey()

### Description
Returns the custom once key. Once-props are sent once per client visit.

### Method
getKey

### Endpoint
ResolvesOnce::getKey()

### Parameters
None

### Response
#### Success Response
- **string|null** - The custom once key, or null if not set.
```

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

### getVersion(): string

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/response-factory.md

Resolves the current asset version. If a closure was set, it is resolved via App::call; otherwise the stored version is returned.

```APIDOC
## getVersion(): string

### Description
Resolves the current asset version. If a closure was set, it is resolved via App::call; otherwise the stored version is returned.

### Method
Method

### Signature
`getVersion(): string`

### Returns
- The resolved version as a string.

### Example
```php
$version = Inertia::getVersion();
```
```

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

### inertia()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/service-provider.md

Renders an Inertia page or returns the ResponseFactory instance. When called with a component name and optional props, it is a shortcut for Inertia::render(). When called with no arguments, it returns the ResponseFactory instance.

```APIDOC
## Function: inertia()

### Description
Renders an Inertia page or returns the ResponseFactory instance. When called with a component name and optional props, it is a shortcut for `Inertia::render()`. When called with no arguments, it returns the `ResponseFactory` instance.

### Signature
```php
function inertia($component = null, $props = [])
```

### Parameters
- **$component** (string|null) - Optional - The component name (e.g., 'Component/Name'). If null, returns the ResponseFactory.
- **$props** (array) - Optional - The props to pass to the component.

### Return Value
- If `$component` is null: `ResponseFactory`
- Otherwise: `Response`

### Usage Example
```php
inertia('Users/Index', ['users' => User::all()]);
```
```

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

### component method signature

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/testing.md

Asserts the component name and optionally verifies the page file exists via the view finder. Fails with 'Inertia page component file [%s] does not exist.' when the file is missing.

```php
public function component(?string $value = null, $shouldExist = null): self
```

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

### Helper function signatures: inertia() and inertia_location()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/service-provider.md

Autoloaded helper functions from helpers.php. inertia() returns a ResponseFactory when called with no arguments, or a Response when given a component. inertia_location() returns a Symfony Response for external redirects.

```php
function inertia($component = null, $props = [])
// ($component is null ? ResponseFactory : Response)

function inertia_location($url)
// Symfony\Component\HttpFoundation\Response
```

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

### Inertia\View\Components\App constructor

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/service-provider.md

Constructor for the App Blade component. Dispatches SSR via app(SsrState::class)->dispatch() and JSON-encodes the page with JSON_HEX_TAG. render() emits the SSR response body if present, otherwise a script tag with the page JSON and a div.

```php
public function __construct(
    public string $id = 'app',
)
```

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

### Onceable::once()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Enables once behavior, optionally setting key and TTL. Once-props are sent once per client visit.

```APIDOC
## Onceable::once()

### Description
Enables once behavior, optionally setting key and TTL. Once-props are sent once per client visit.

### Method
once

### Endpoint
Onceable::once(bool $value = true)

### Parameters
#### Path Parameters
- **$value** (bool) - Optional - Whether to enable once behavior. Defaults to true.

### Response
#### Success Response
- **static** - Returns the instance for chaining.
```

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

### Basic assertInertia usage with component, url, has, where, missing

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/testing.md

Shows how to assert Inertia page properties: component name, URL, presence of props, exact values, and absence of props.

```php
use Inertia\Testing\AssertableInertia;

$response = $this->get('/users');

$response->assertInertia(function (AssertableInertia $page) {
    $page
        ->component('Users/Index')
        ->url('/users')
        ->has('users', 3)
        ->where('filters.search', 'john')
        ->where('auth.user.name', 'Jonathan')
        ->missing('admin_panel');
});
```

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

### MergesProps::prependsAtPaths()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Returns the nested prepend paths. Merging metadata is emitted as `prependProps` on the page object.

```APIDOC
## MergesProps::prependsAtPaths()

### Description
Returns the nested prepend paths. Merging metadata is emitted as `prependProps` on the page object.

### Method
prependsAtPaths

### Endpoint
MergesProps::prependsAtPaths()

### Parameters
None

### Response
#### Success Response
- **array** - The nested prepend paths.
```

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

### Run inertia:middleware command

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/artisan-commands.md

Creates a new Inertia middleware. Use --force to overwrite an existing middleware class.

```bash
php artisan inertia:middleware
php artisan inertia:middleware AdminMiddleware --force
```

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

### ProvidesInertiaProperties::toInertiaProperties

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Returns an iterable of keyed props to be shared or rendered. Objects implementing this interface can be passed to share()/render() or included in props arrays.

```APIDOC
## ProvidesInertiaProperties::toInertiaProperties

### Description
Returns an iterable of keyed props to be shared or rendered. Objects implementing this interface can be passed to share()/render() or included in props arrays.

### Method
`toInertiaProperties`

### Signature
`public function toInertiaProperties(RenderContext $context): iterable`

### Parameters
- **context** (RenderContext) - Required - The render context containing the component and request.

### Returns
- **iterable** - An iterable of keyed props.

```

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

### ExceptionResponse::usingMiddleware()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/exception-response.md

Specifies a middleware to be used when rendering the error page. Returns the ExceptionResponse instance for chaining.

```APIDOC
## ExceptionResponse::usingMiddleware()

### Description
Specifies a middleware to be used when rendering the error page. Returns the ExceptionResponse instance for chaining.

### Method
Instance method on ExceptionResponse

### Signature
`$error->usingMiddleware(string $middleware)`

### Parameters
- **middleware** (string) - Required - The middleware class name.

### Usage Example
```php
return $error
    ->render('Error/Page')
    ->usingMiddleware(\App\Http\Middleware\HandleInertiaRequests::class)
    ->withSharedData();
```
```

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

### MergesProps::prependsAtRoot()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Returns true when prepending and no nested paths are set. Merging metadata is emitted as `prependProps` on the page object.

```APIDOC
## MergesProps::prependsAtRoot()

### Description
Returns true when prepending and no nested paths are set. Merging metadata is emitted as `prependProps` on the page object.

### Method
prependsAtRoot

### Endpoint
MergesProps::prependsAtRoot()

### Parameters
None

### Response
#### Success Response
- **bool** - True if prepending at root.
```

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

### EntriesController show method signature

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/devtools.md

Returns a single devtools entry by its ULID. Aborts with 404 if the entry does not exist.

```php
public function show(string $id): array
```

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

### Advanced merge configuration with deepMerge and matchOn

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Configures Inertia::merge with deep merging and item-level upserts using matchOn, and prepending at a specific path. The comment notes that matchOn is an alternative to deepMerge for item-level upserts.

```php
use Inertia\Inertia;

return Inertia::render('Chat/Index', [
    'messages' => Inertia::merge($newMessages)
        ->deepMerge()                 // or matchOn for item-level upserts
        ->matchOn('id')
        ->prepend('data', 'id'),      // prepend at path data, matching on data.id
]);
```

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

### Onceable::getKey()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Returns the custom once key. Once-props are sent once per client visit.

```APIDOC
## Onceable::getKey()

### Description
Returns the custom once key. Once-props are sent once per client visit.

### Method
getKey

### Endpoint
Onceable::getKey()

### Parameters
None

### Response
#### Success Response
- **string|null** - The custom once key, or null if not set.
```

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

### MergesProps::prepend()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Prepends the prop at the root or at nested path(s). Arrays map `key => path` pairs. Merging metadata is emitted as `prependProps` on the page object.

```APIDOC
## MergesProps::prepend()

### Description
Prepends the prop at the root or at nested path(s). Arrays map `key => path` pairs. Merging metadata is emitted as `prependProps` on the page object.

### Method
prepend

### Endpoint
MergesProps::prepend(bool|string|array $path = true, ?string $matchOn = null)

### Parameters
#### Path Parameters
- **$path** (bool|string|array) - Optional - The path to prepend at. Defaults to true (root).
- **$matchOn** (string|null) - Optional - The property to match on for item-level merge.

### Response
#### Success Response
- **static** - Returns the instance for chaining.
```

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

### withSharedData(): static

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/exception-response.md

When set, the resolved middleware's share() and shareOnce() output is shared before rendering.

```APIDOC
## withSharedData(): static

### Description
When set, the resolved middleware's share() and shareOnce() output is shared before rendering.

### Method
withSharedData

### Returns
- **static** - The current instance for chaining.
```

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

### Sharing, versioning, and error handling with Inertia facade

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/response-factory.md

Shows several Inertia facade methods: share() for global props (auth and flash), disableSsr() and withoutSsr() for maintenance mode, version() with a closure for asset versioning, and flash() for one-time notifications. The flash data is not kept in history. The version closure is resolved per request.

```php
use Inertia\Inertia;

Inertia::share('auth', fn () => [
    'user' => auth()->user()?->only('id', 'name', 'email'),
]);

Inertia::share('flash', [
    'success' => session('success'),
]);

// Register an alternative SSR server or disable it on a schedule
if (app()->isDownForMaintenance()) {
    Inertia::disableSsr();
    Inertia::withoutSsr(['/maintenance*']);
}

// Asset version as a closure (resolved per request)
Inertia::version(fn () => md5_file(public_path('build/manifest.json')));

// Flash data for one-time notifications (not kept in history)
Inertia::flash('success', 'Account created.');
return Redirect::route('users.show', $user);
```

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

### Mergeable::appendsAtPaths()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Returns the nested append paths. Merging metadata is emitted as `prependProps` on the page object.

```APIDOC
## Mergeable::appendsAtPaths()

### Description
Returns the nested append paths. Merging metadata is emitted as `prependProps` on the page object.

### Method
appendsAtPaths

### Endpoint
Mergeable::appendsAtPaths()

### Parameters
None

### Response
#### Success Response
- **array** - The nested append paths.
```

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

### Mergeable::appendsAtRoot()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Returns true when appending and no nested paths are set. Merging metadata is emitted as `prependProps` on the page object.

```APIDOC
## Mergeable::appendsAtRoot()

### Description
Returns true when appending and no nested paths are set. Merging metadata is emitted as `prependProps` on the page object.

### Method
appendsAtRoot

### Endpoint
Mergeable::appendsAtRoot()

### Parameters
None

### Response
#### Success Response
- **bool** - True if appending at root.
```

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

### urlResolver(): ?Closure

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/middleware.md

Return a callback fn (Request $request) => string to customize the page url; null keeps the default.

```APIDOC
## urlResolver(): ?Closure

### Description
Return a callback fn (Request $request) => string to customize the page url; null keeps the default.

### Method
urlResolver

### Endpoint
N/A (PHP method)

### Parameters
None

### Return Value
- **?Closure** - A closure that takes a Request and returns a string, or null.

### Example
```php
public function urlResolver()
{
    return null;
}
```
```

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

### Catching ComponentNotFoundException in an exception reporter

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/exception-response.md

Catches ComponentNotFoundException when rendering a page and aborts with a 404 status if the component is missing.

```php
use Inertia\ComponentNotFoundException;

try {
    return Inertia::render('Users/Show', $props);
} catch (ComponentNotFoundException $e) {
    abort(404);
}
```

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

### share() method signature

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/response-factory.md

Shares data across all Inertia responses. Accepts a string key with a value, an array of props, an Arrayable, or an object implementing ProvidesInertiaProperties.

```php
public function share($key, $value = null): void
```

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

### MergesProps::matchOn()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Sets the properties to match on for item-level merge (upsert). Merging metadata is emitted as `matchPropsOn` on the page object.

```APIDOC
## MergesProps::matchOn()

### Description
Sets the properties to match on for item-level merge (upsert). Merging metadata is emitted as `matchPropsOn` on the page object.

### Method
matchOn

### Endpoint
MergesProps::matchOn(string|array<int, string> $matchOn)

### Parameters
#### Path Parameters
- **$matchOn** (string|array<int, string>) - Required - The properties to match on.

### Response
#### Success Response
- **static** - Returns the instance for chaining.
```

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

### ProvidesInertiaProperty::toInertiaProperty

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Called on a resolved prop value to transform it. The PropertyContext provides the key, sibling props, and request.

```APIDOC
## ProvidesInertiaProperty::toInertiaProperty

### Description
Called on a resolved prop value to transform it.

### Method
`toInertiaProperty`

### Signature
`public function toInertiaProperty(PropertyContext $prop): mixed`

### Parameters
- **prop** (PropertyContext) - Required - The property context containing the key, sibling props, and request.

### Returns
- **mixed** - The transformed prop value.

```

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

### inertia() helper function

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/response-factory.md

Global helper that returns a Response when a component is passed, or the ResponseFactory instance when called with no arguments. Used as an alternative to the Inertia facade.

```php
// helpers.php
function inertia($component = null, $props = [])
{
    $instance = Inertia::getFacadeRoot();

    if ($component) {
        return $instance->render($component, $props);
    }

    return $instance;
}
```

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

### configureSsrRequestUsing(?Closure $callback = null): void

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/response-factory.md

Configures the SSR request using the given callback. Throws LogicException when the gateway does not implement Inertia\Ssr\ConfiguresSsrRequests.

```APIDOC
## configureSsrRequestUsing(?Closure $callback = null): void

### Description
Configures the SSR request using the given callback. Throws LogicException when the gateway does not implement Inertia\Ssr\ConfiguresSsrRequests.

### Method
configureSsrRequestUsing

### Parameters
- **callback** (?Closure) - Optional - Default: null - Callback receiving the PendingRequest and returning it (or a modified one)

### Returns
void

### Exceptions
- **LogicException** - When the gateway does not implement Inertia\Ssr\ConfiguresSsrRequests.
```

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

### ResolvesOnce::shouldResolveOnce()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Determines whether the prop should be resolved once. Once-props are sent once per client visit.

```APIDOC
## ResolvesOnce::shouldResolveOnce()

### Description
Determines whether the prop should be resolved once. Once-props are sent once per client visit.

### Method
shouldResolveOnce

### Endpoint
ResolvesOnce::shouldResolveOnce()

### Parameters
None

### Response
#### Success Response
- **bool** - True if the prop should be resolved once.
```

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

### MergesProps::appendsAtPaths()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Returns the nested append paths. Merging metadata is emitted as `prependProps` on the page object.

```APIDOC
## MergesProps::appendsAtPaths()

### Description
Returns the nested append paths. Merging metadata is emitted as `prependProps` on the page object.

### Method
appendsAtPaths

### Endpoint
MergesProps::appendsAtPaths()

### Parameters
None

### Response
#### Success Response
- **array** - The nested append paths.
```

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

### back(int $status = 302, array $headers = [], mixed $fallback = false): RedirectResponse

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/response-factory.md

Delegates to `Redirect::back($status, $headers, $fallback)` — a redirect to the previous location with inertia-aware previous URL handling.

```APIDOC
## back(int $status = 302, array $headers = [], mixed $fallback = false): RedirectResponse

### Description
Delegates to `Redirect::back($status, $headers, $fallback)` — a redirect to the previous location with inertia-aware previous URL handling.

### Parameters
- **status** (int) - Optional - HTTP status code (default: 302)
- **headers** (array) - Optional - Response headers
- **fallback** (mixed) - Optional - Fallback URL or value (default: false)

### Returns
- **RedirectResponse** - The redirect response.
```

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

### BundleDetector::detect()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/ssr.md

Detects the first existing SSR bundle file from a predefined list of paths. Returns null if none exist.

```APIDOC
## BundleDetector::detect()

### Description
Detects the first existing SSR bundle file from a predefined list of paths.

### Method
`detect`

### Returns
- **string|null** - The path to the first existing bundle file, or null if none exist.

### Usage Example
```php
$bundle = (new BundleDetector)->detect();
```
```

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

### MergesProps::matchesOn()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Returns the properties to match on for item-level merge (upsert). Merging metadata is emitted as `matchPropsOn` on the page object.

```APIDOC
## MergesProps::matchesOn()

### Description
Returns the properties to match on for item-level merge (upsert). Merging metadata is emitted as `matchPropsOn` on the page object.

### Method
matchesOn

### Endpoint
MergesProps::matchesOn()

### Parameters
None

### Response
#### Success Response
- **array** - The properties to match on.
```

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

### MergesProps::append()

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/props.md

Appends the prop at the root or at nested path(s). Arrays map `key => path` pairs. Merging metadata is emitted as `prependProps` on the page object.

```APIDOC
## MergesProps::append()

### Description
Appends the prop at the root or at nested path(s). Arrays map `key => path` pairs. Merging metadata is emitted as `prependProps` on the page object.

### Method
append

### Endpoint
MergesProps::append(bool|string|array $path = true, ?string $matchOn = null)

### Parameters
#### Path Parameters
- **$path** (bool|string|array) - Optional - The path to append at. Defaults to true (root).
- **$matchOn** (string|null) - Optional - The property to match on for item-level merge.

### Response
#### Success Response
- **static** - Returns the instance for chaining.
```

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

### Route-defined Inertia pages with Route::inertia

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/service-provider.md

Use Route::inertia to render Inertia pages directly from routes. The second argument is the component name, and the third optional argument provides props, which can be lazy closures.

```php
use Illuminate\Support\Facades\Route;

Route::inertia('/', 'Home/Index');

Route::inertia('/users', 'Users/Index', [
    'users' => fn () => User::all(),
]);
```

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

### version(Request $request): ?string

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/middleware.md

Determines the current asset version. Default implementation hashes app.asset_url (xxh128), then public/build/manifest.json, then public/mix-manifest.json; returns null if none exist. Called per request and fed into Inertia::version().

```APIDOC
## version(Request $request): ?string

### Description
Determines the current asset version. Default implementation hashes app.asset_url (xxh128), then public/build/manifest.json, then public/mix-manifest.json; returns null if none exist. Called per request and fed into Inertia::version().

### Method
version

### Endpoint
N/A (PHP method)

### Parameters
- **$request** (Request) - Required - The incoming HTTP request.

### Return Value
- **?string** - The asset version string or null.

### Example
```php
public function version(Request $request)
{
    if (config('app.asset_url')) {
        return hash('xxh128', config('app.asset_url'));
    }

    if (file_exists($manifest = public_path('build/manifest.json'))) {
        return hash_file('xxh128', $manifest);
    }

    if (file_exists($manifest = public_path('mix-manifest.json'))) {
        return hash_file('xxh128', $manifest);
    }

    return null;
}
```
```

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

### ExceptionResponse constructor

Source: https://github.com/inertiajs/inertia-laravel/blob/3.x/_autodocs/api-reference/exception-response.md

Constructor for Inertia\ExceptionResponse, wrapping the exception, request, response, router, and kernel. Instances are created by ResponseFactory::handleExceptionsUsing() and passed to the registered callback.

```php
public function __construct(
    public readonly Throwable $exception,
    public readonly Request $request,
    public readonly Response $response,
    protected readonly Router $router,
    protected readonly KernelContract $kernel,
) {}
```
Tokens:
Raw