Eloquent External Laravel Package

Getting Started

likesistemas/eloquent-external extends Eloquent so a model can read/write against an external data source instead of (or alongside) your app's default connection. It's a small, single-maintainer package — the practical path is: install, read the source, then build one model against one external source before committing to it broadly.

composer require likesistemas/eloquent-external

Where to look first, in order:

1. The README — this package's docs are the primary reference; there is no large ecosystem of blog posts or Stack Overflow answers to fall back on.
2. src/ — the service provider and the model base class/trait are the whole contract. Read them end-to-end (usually a few hundred lines). You need to know exactly which Eloquent methods are intercepted and which fall through to the normal query builder.
3. Published config (if the package exposes one): php artisan vendor:publish --provider="Likesistemas\...\ServiceProvider" and inspect the resulting file for connection/credential keys.

First use case to validate against: a read-only reporting model pointed at an external database or endpoint. Define one model, run a where() + get(), then run a create() to confirm whether writes are supported. That single experiment tells you more than the docs about whether the package fits your workload.

If you use barryvdh/laravel-ide-helper, install >=2.1.1 — see Gotchas, this release exists specifically to unblock that workflow.

Implementation Patterns

Wrap the package behind your own layer. Because the package owns the model's persistence behaviour, don't let it leak into your domain code. Give each external source a repository/interface implemented by the package model, so swapping to a hand-rolled HTTP client or a second DB connection later is a one-file change:

interface ProductRepository { public function find(int $id): ?ProductData; }

class ExternalProductRepository implements ProductRepository { /* uses the package model */ }

One model class per external source. Connection/endpoint details usually live on the model or its parent. Do not try to multiplex a single model across tenants or environments — subclass or use distinct model classes, and bind the concrete class in a service provider per environment.

Keep credentials in config/. Never on the model. Reference config('services.external.…') / env() only inside config files, and remember php artisan config:cache in deploy — stale config after an env change is a classic first-day bug here.

Test around the boundary, not through it. In tests, either bind a fake implementation of your repository interface, or point the package at a local SQLite/HTTP fake. Asserting on the package's own internals is brittle; assert on your repository's contract.

Use it in queued jobs, not in request paths, for bulk work. External sources are slower and less predictable than a local connection. Sync jobs with ShouldQueue, retries and backoff() are the natural home for large imports/exports, and they isolate timeouts from user-facing requests.

Regenerate IDE metadata in CI or on a pre-commit hook. With >=2.1.1 you can run php artisan ide-helper:models --write against your external models and commit the generated docblocks (or generate into a _ide_helper_models.php you exclude from git and build at bootstrap). Treat it like a build artefact.

Gotchas and Tips

• The v2.1.1 fix is narrow but real. Prior to this release, php artisan ide-helper:models errored out when the package's models were scanned. If you already run laravel-ide-helper, pin likesistemas/eloquent-external:^2.1.1 — otherwise your model-generation step (and anything gated on it, like static analysis baselines) breaks. If you don't use ide-helper, this release is a no-op for you: no API changes, no breaking changes, safe to take on a patch bump.
• After upgrading, regenerate rather than trust old docblocks. Delete the generated _ide_helper_models.php and re-run ide-helper:models --write, otherwise you'll keep the incomplete/stale docblocks that the bug produced.
• Patch-level maturity signal. v2.1.x has had at least one fix in this area within the 2.1 line. Pin with a caret constraint and read the changelog on each bump — the surface is small enough that a patch release can still touch model hydration.
• No schema, no docblocks. ide-helper derives property docblocks from the connection's schema. If the external source can't report one, generated docblocks will be thin — supplement with an @property block written by hand or a PHPStan stub.
• Debugging: wrap suspect calls in DB::listen() when the external source is a SQL connection; for HTTP-backed sources, log the outgoing request and response body. Set Model::preventLazyLoading() and preventAccessingMissingAttributes() in non-production to surface N+1s and silent nulls early — external round-trips make both much more expensive.
• Watch for Eloquent features that quietly don't apply. Relationships, whereHas, withCount, chunking and upsert may or may not be implemented; verify each one you rely on rather than assuming Eloquent parity. Builder methods that fall through to the base query builder are where the surprising failures live.
• Extension points are the model's newEloquentBuilder() / newQuery() and (if present) the package's connection resolver. Overriding the builder is the cleanest place to add caching, logging, or retry logic without forking.
• Bus factor. One maintainer, low download volume. Vendor the package or keep a fork-ready branch, and keep the repository interface in front of it so a stalled upstream isn't a rewrite.