Laravel Inertia Dataproviders Laravel Package

Getting Started

v4.0.0 is a framework-alignment major: the only documented change is support for Laravel 13 (plus a comprehensive test suite). There are no new features, deprecations, or API changes called out in the release notes — so treat this as a compatibility gate, not a new API to learn.

Before you install

1. Upgrade the host app to Laravel 13 first. This package's ^4.0 constraint will not install alongside Laravel 10–12.
2. Confirm the rest of the Inertia stack supports L13 — inertiajs/inertia-laravel, tightenco/ziggy, and your starter kit (Breeze/Jetstream) are the usual blockers. A common failure mode is the app being on L13 while inertia-laravel is still pinned to a version that doesn't allow it.
3. Check PHP: Laravel 13's floor applies transitively. If CI still runs an older PHP image, the composer solve fails before the package is even the problem.

composer require foxbytehq/laravel-inertia-dataproviders:^4.0

Where to look first

• The README's provider example — the class contract is the whole package. Everything else (partial reloads, only/except, nesting) hangs off it.
• vendor/foxbytehq/laravel-inertia-dataproviders/src — the base DataProvider is small; reading it is faster than guessing at behaviour when a prop is missing.
• The new v4 test suite. With no prior public tests, this is now the most reliable reference for edge cases (empty props, partial reloads, nested providers). Read the tests before filing an issue.

First use case

The natural entry point is a controller that currently builds a fat props array. Move that array into a provider class and return the provider from Inertia::render() instead. You get a named, testable, reusable place for page data — and, critically, the ability to compute expensive props only when the client actually asks for them.

Start with one page (a dashboard or index is ideal: several independent queries). Don't refactor the whole app in the first pass — the value shows up when a page has props with genuinely different costs.

Implementation Patterns

One provider per page, not per model. Providers map to Inertia pages/components. A DashboardDataProvider that composes stats, recentOrders, and notifications beats three model-shaped providers the controller has to merge.

Lean on partial reloads. The package's core value is that Inertia's X-Inertia-Partial-Data header is respected: a link with only: ['stats'] should not run the recentOrders query. Structure data() so each key is independently cheap, and verify with DB::listen() or Telescope that only the requested keys execute. If every key runs regardless, your provider is doing eager work outside the per-key boundary.

Split expensive props into their own keys. Anything that hits an external API, does an aggregate, or paginates should be its own prop key so clients can defer or skip it. Cheap scalars can share.

Compose shared data deliberately. Auth user, flash messages, and menu counts are usually better handled by Inertia's share() middleware than by every provider. Duplicating them per provider makes partial reloads noisy and drifts over time.

Inject, don't reach for globals. Providers are resolved from the container in normal usage, so constructor injection of repositories/services keeps them testable. Avoid auth()->user() scattered through data(); pass the user in or resolve it once.

Authorisation belongs in the provider, not the controller. If a prop contains tenant-scoped or role-scoped data, gate it where the data is built. A provider that silently returns rows the controller forgot to authorise is the most likely security bug in this pattern — especially once partial reloads mean a prop can be requested directly by name.

Testing. Providers are plain classes: instantiate them, call the data method, assert the array. For HTTP-level tests, assertInertia() with ->has('stats') / ->missing('recentOrders') verifies the partial-reload contract end to end. Add at least one test per page asserting the only behaviour, because that's the property most likely to regress during refactors.

Upgrade pattern for v4. Do the framework upgrade and the package bump in one branch, run the app's Inertia test suite, then check the front end for undefined props — a provider that throws during resolution often surfaces as a missing prop on the client rather than a 500.

Gotchas and Tips

This is a hard major on the framework axis. ^4.0 requires Laravel 13. If you maintain a package or a monorepo that supports multiple Laravel versions, you cannot adopt v4 across the board — either stay on 3.3 for the older line or require both (^3.3 || ^4.0) with the framework constraint doing the work. Do not assume a shim exists.

No migration guide means no API changes — but verify. The changelog lists only the Laravel 13 upgrade. Still, run composer update --with-dependencies and check the resolved inertia-laravel version; Inertia majors have historically changed prop resolution and the deferred/optional props behaviour that this package builds on. If props silently stop appearing, look there before blaming the provider.

Partial reload prop names must match exactly. only: ['stats'] when the provider returns statistics produces no error — you just get an empty or fully-hydrated response depending on the path. Keep provider keys and front-end only/except arrays in sync; a typo is silent.

Closures and lazy values capture scope. If your props are closures, anything they reference ($this->request, route models) must be resolved at execution time, not at provider construction. Capturing a stale request object is a classic source of "wrong user's data on a cached page".

Serialisation happens late. Return arrays of resources/JsonResource, plain arrays, and scalars. Returning an Eloquent Builder or a collection of models works until it doesn't (lazy-loading prevention, Model::preventLazyLoading() in non-production). Prefer explicit resources so the shape is stable and N+1s surface in dev.

Config caching. If the package publishes config, php artisan config:cache during deploy is fine, but remember config:clear locally when toggling debug/tracing options — stale cached config is the usual reason "the config change did nothing".

Debugging a prop. dump()/dd() inside data() will corrupt the Inertia JSON response or land in the network tab rather than your terminal. Use Log::debug() or Laravel Telescope's dump watcher instead; for header-level issues (is the partial-data header even reaching the server?), check the request in Telescope before touching provider code.

Extension points. The base provider class is the seam: subclass it for app-wide conventions (consistent envelope, common authorisation checks, timing instrumentation) rather than editing vendor code. Nested providers are the other lever — a page-level provider that delegates to section providers keeps individual files small and independently testable.

Adoption signal. The addition of a comprehensive suite is the strongest part of this release for day-to-day confidence: previously untested behaviour around partial reloads is now pinned. If you evaluated the package earlier and passed because of thin tests, v4 on Laravel 13 is the version to re-evaluate — but only once the rest of your Inertia stack is on 13.