Remote Model Laravel Package

Technical Evaluation

Architecture fit. torann/remote-model is a thin, Eloquent-shaped HTTP adapter: a model class maps to a remote endpoint, and find/where/paginate/save forward to that API. Architecturally it belongs as an anti-corruption layer / migration seam between our domain code and an external system — internal admin dashboards over CRM/ERP/legacy REST, prototype integrations, and read-through layers during a system replacement. It is not a fit for customer-facing, write-heavy, or transactional flows. The core framing question for the team is whether remote data should be modeled as Eloquent models at all; this package forces that decision deliberately rather than by default, which is itself a useful outcome of the evaluation.

Integration feasibility. Feasibility splits cleanly by stack:

On a modern stack composer require will almost certainly fail dependency resolution. The README-era install instructions no longer apply, so the realistic proposal is adopt as a pattern, not as a dependency: treat the repo as an unmaintained reference implementation and budget the fork explicitly.

Technical risk. The risk profile is dominated by decay, not licensing (BSD-2-Clause is permissive and low-friction). The high-severity items are:

Key questions to resolve before committing.

• Which stack are we actually on, and is a fork approved or is legacy-only acceptable?
• Is the remote API stable, well-documented, and record-shaped (per-record CRUD) rather than aggregate/query-heavy?
• Read-mostly or write-bearing? If writes, are they isolated single-record operations?
• Do we have a named internal owner and a sunset date, or is this permanent infrastructure?
• Does the remote API's pagination semantics match what the package forwards (and has that been verified against 0.2.1)?
• How does auth token expiry/refresh work, and who owns the retry handler?
• What is the degradation behavior per call site when the remote is slow or down — cached value, empty result, or user-facing fallback?
• What is the measured fork effort against building an equivalent internal adapter from scratch?

Integration Approach

Stack fit and decision gate. Sequence the decision so the fork cost is measured, not assumed:

1. Day 1–2 spike. Vendor the source into a scratch branch on the target stack, port the transport to Laravel Http, and get a single User::find(42) working end-to-end against a real endpoint (correct URL, correct auth, attributes hydrated). This validates the whole path — everything harder is additive scope.
2. Fork verdict. Compare measured port effort (~1–2 sprints with tests) against building a minimal internal adapter. Because the package is a thin wrapper, internal build is a credible alternative; the decision should hinge on measured effort, not the README.
3. Go/no-go. Proceed only with an assigned internal owner and a documented sunset or upgrade path.

Compatibility and migration path. On the modern path: vendor to app/Remote/, register the service provider from our own provider (the package predates auto-discovery), port the transport to Guzzle 7 / Laravel Http, and port the model base class to Laravel 10/11 contract signatures. Publish and own config/remote-model.php in-repo — host/prefix joining is the single most common source of "package bugs," so that file must be under our change control. Substitute Http::fake() for Guzzle mocks in tests so the test suite does not depend on legacy Guzzle.

Sequencing. Deliver in risk-ascending order:

• Phase 0 — Spike and verdict (2–3 days): one find() end-to-end, port effort estimated, owner named.
• Phase 1 — Seam (1 sprint): one model class per remote resource; wrap it behind an internal interface (CustomerRepository) so domain code never depends on App\Remote\*. This is the highest-leverage pattern — it is what makes the fork survivable and caps the blast radius at one class.
• Phase 2 — Hardening (1 sprint): cache decorator above the repository backed by Redis/memcached with a stampede lock; retry with exponential backoff on 5xx/timeouts; circuit breaker; explicit auth-refresh handler; 404-vs-transport error distinction in try/catch.
• Phase 3 — Test net: recorded fixtures in the repo, hydration assertions, pagination shape and count assertions, error-path assertions, and contract tests so upstream schema drift fails a test instead of producing silent nulls.
• Phase 4 — First production use case: a read-only, low-risk surface — an admin dashboard lookup against a CRM, or a migration bridge pointing at the system we are replacing. The migration bridge is the highest-value use case: call sites read through the internal interface while the new implementation is swapped in behind it, with a defined sunset.
• Phase 5 — Sunset/upgrade cadence: tie fork upgrades to Laravel major versions; revisit replace-vs-maintain at each major.

Explicit non-goals. Do not build multi-step workflows depending on two remote writes; do not rely on relationships/lazy loading; do not treat where() as a local query builder; do not place the package on a customer-facing critical path.

Operational Impact

Maintenance. Every future bug fix, framework bump, and security patch is ours. There is no maintainer, no community, and 0 dependents — no external bug-fixing velocity and no knowledge base to lean on. Operationally this means: the fork lives in our repo, follows our dependency policy, and gets an owner in the on-call rotation. Budget a recurring small allocation (a few days per Laravel major) rather than a one-time cost. Treat the dependency as unmaintained code sample in the dependency register so intake criteria for future packages are informed by this profile.

Support. No upstream escalation path exists. Remote failures surface as hard exceptions in our request path because the package has no retries, backoff, rate limiting, or circuit breaking. Support therefore requires:

• A runbook with the debugging order: config/remote-model.php → model $endpoint → raw remote response → transport/Guzzle request log.
• Guzzle request/response logging behind a local debug flag — most "package bugs" are config or auth.
• Reproduction protocol: get a single find() failing before debugging scopes or pagination.
• Clear ownership of the remote system's availability, which is now coupled to ours.

Scaling. Each model operation is a synchronous HTTP call, so latency and throughput are bound by the remote API, not by us. Watch for:

• N+1 remote fan-out — no relationships means loops over models become loops over HTTP calls; enforce batching or denormalization at the repository interface.
• Rate limits on the remote — the package does not respect them; throttling is our responsibility.
• Cache correctness across pods — the bundled caching gives inconsistent reads and stampede-on-expiry in multi-instance deployments. Cache above the repository with a shared store and a lock keyed on resource + primary key.
• Auth token rotation — tokens expiring under load become an outage pattern; the refresh-and-retry handler is mandatory, not optional.

Failure modes and required behavior.

Ramp-up. The dominant onboarding risk is the Eloquent illusion: the API looks like Eloquent and invites assumptions it cannot honor — no relationships/lazy loading, no real query scopes, no transactions, no persistence. Junior engineers will write Eloquent-shaped code that fails at runtime unless onboarding leads with these limits. Ramp-up plan: a short internal doc covering the limits, the repository-interface pattern, the fixture set, and the debugging order; plus the contract tests as the working reference for what the remote actually returns. Given 0 dependents and no upstream tests, our fixture suite is the only reliable regression net — it should exist before the first production call site, not after.

Success metrics and exit criteria. Track mean integration time per new remote resource (the velocity claim the package makes), incident count attributable to remote calls, contract-test drift catches, and cache hit rate / remote call volume after the decorator lands. Exit criteria: sunset date reached, remote system replaced, or fork maintenance cost exceeds the internal-adapter alternative — at which point the repository interface means replacement touches one class.