Remote Models Laravel Package

Getting Started

• Install with composer require daltonmccleery/remote-models. As of 1.3.0 the package supports Laravel 12, so it can be installed on current Laravel apps without --ignore-platform-reqs or Composer constraint workarounds. Confirm your app's PHP version matches the package's composer.json (Laravel 12 requires PHP 8.2+).
• Publish the package config first: php artisan vendor:publish --tag=remote-models-config. Put the remote API base URL, timeout, and credentials in config/remote-models.php and reference them from .env — never hard-code them in model classes.
• Look at the package's base remote model class and the published config before writing anything. Those two files tell you the supported knobs (connection name, endpoint, pagination keys, hydration behavior) faster than the README.
• First use case: take an existing hand-rolled Http::get('.../users') call in a controller or service and replace it with a model class extending the package's base model, setting its endpoint to users. You immediately get a query-builder-style API (User::query()->where(...)->get()) instead of manually decoding JSON and mapping arrays.

Implementation Patterns

• One model per remote resource. Define a class per endpoint with the endpoint path, attribute casts, and $hidden/$appends mirroring what you'd normally put on an Eloquent model. This keeps controllers free of transport concerns and makes the remote resource swappable later.
• Treat the model as a read layer, not a persistence layer. Use it for reads and query composition; keep writes in a dedicated service or HTTP client class unless the package explicitly supports save()/delete() against your API.
• Multi-connection setup. If you talk to more than one API, define named connections in config (base URL + headers) and select per model. Centralize auth headers there so token rotation happens in one place.
• Pagination mapping. Remote APIs rarely use page/per_page. Normalize the request and response keys in config or by overriding the relevant method on the model, then expose paginate() consistently so Blade/API resources don't need per-endpoint conditionals.
• Caching. Wrap frequently hit, slow-changing endpoints in Cache::remember() with keys derived from endpoint + query parameters. Invalidate on write operations in the system of record, or use short TTLs for volatile data.
• Relationships. Where the remote API supports nested includes, eager-load them to avoid per-record calls. Where it doesn't, resolve related models in a single batched query ( whereIn on IDs ) after the parent fetch rather than inside a loop.
• Resilience. Set explicit timeouts and retry counts per connection. Convert transport failures into domain exceptions so controllers can return 503s rather than leaking HTTP client exceptions.
• Testing. Use Http::fake() with fixtures per endpoint and Http::preventStrayRequests() in the test suite. Assert both the hydrated model attributes and the outgoing request (URL, query string, headers) — the latter catches pagination and auth regressions early.
• Migration path. Introduce remote models alongside existing service classes; replace call sites one at a time. This keeps the blast radius small and lets you compare outputs during rollout.

Gotchas and Tips

• It is not Eloquent. No database transactions, no refresh() against a local store, no migrations, and no query log in the usual place. Don't assume ->save(), ->update(), or model events behave like the database-backed equivalents.
• N+1 is still your problem. Hydrating a collection and then touching a relationship per item will fire one HTTP request per record. Batch or eager-load deliberately.
• Pagination key mismatches are the most common source of "empty page 2" bugs. Verify how the package reads data, meta, total, and last_page from your API's envelope and override if needed.
• Cache keys must include query parameters and auth scope. Two tenants hitting the same endpoint with different tokens must not share cache entries.
• config:cache traps. Resolve env values inside config/remote-models.php, not via env() calls scattered in model classes — otherwise deployed config silently diverges from local.
• Token expiry. A long-lived process (queue worker, Octane) will hold a stale token. Handle 401s with a refresh-and-retry path rather than failing the job.
• Laravel 12 upgrade note. 1.3.0 is a compatibility release, not a behavioral one; existing 1.2.x usage should carry over. Still re-run your test suite on Laravel 12 — framework-level HTTP client and collection changes can surface in hydration code even when the package itself is unchanged.
• Debugging. Log the outgoing request and a trimmed response body behind a config flag. When hydration looks wrong, dump the raw payload first — most "missing attribute" issues are envelope or key-casing differences, not package bugs.
• Extension points. Prefer overriding the request/hydration hooks on a base model class in your app (e.g. App\Models\Remote\BaseRemoteModel) over editing vendor code, so future upgrades stay painless.