Larasources
Larasources integrates external data sources into your Eloquent models, with a write-through cache in your own database. You work with external APIs through model-like abstractions, without forcing those APIs into your own tables.
Every integration starts the same way: a client with the endpoints, a function that turns your model into their payload, a column or two to remember what the other side answered, and a job that pushes changes. Then the second provider arrives and you write it again, because the shape of their JSON is different even though everything around it is identical.
What gets you is not the HTTP. It is the four things around it:
- Where the mapping lives.
- Where the remote state is cached.
- How you know whether what the screen shows is current.
- Whose credentials you are using.
Larasources is those four things.
The two pieces
A Source is a model-like class that declares the remote resource: fillable fields, casts, accessors, and how your record becomes their payload. It is the shape, and it knows nothing about transport.
An Origin is the client. It knows the endpoints, the credentials and the protocol, and nothing about your columns.
Between them, one table. The payload each source holds is cached in sources, keyed by the model it hangs from, the name it is mapped under and the variant, so nothing about an external service leaks into your schema and nothing about your schema leaks into the client.
$weather = $city->source('weather'); $weather->temperature; // from the row, or from the provider the first time $weather->feels_like; // an accessor of yours, over cached data
Nothing about the package assumes the other side is an API. One of the applications using it reads a car listing by scraping the page, and the Source still describes it as a typed resource with casts and accessors.
What it does not do
It does not expire the cache on its own. Once the row exists, reading attributes never calls the origin again, and you refresh when your application decides to. A TTL that fires on attribute access sounds handy until a listing page paints twenty cards and makes twenty API calls.
It does not decide whether a write worked. Only the origin can know that, so the origin throws when a service refuses something, and the package writes the row only after the call has returned.
And it ships no configuration. Credentials belong to the integration, which in a multi-tenant application means a row next to the tenant that owns them, not an environment variable.
Installation
composer require edulazaro/larasources php artisan migrate
Requirements: PHP 8.4+, Laravel 12+.
There is no config file to publish and no environment variable to set. If you would rather keep the migrations in your own repository:
php artisan vendor:publish --tag=larasources-migrations
The two tables
sources is the cached state. One row per model, source and variant, holding:
| Column | What it holds |
|---|---|
sourceable_type, sourceable_id |
The model it belongs to, nullable: a row can exist before it |
name |
How its owner calls it, which is the key the model maps the class under |
variant |
The mode, when the same source has several |
origin |
The alias of the client that wrote it |
attributes |
The payload, as JSON |
signature |
An md5 of that payload, for telling whether anything changed |
status |
What the origin last said: saved or processing |
external_id |
What the service calls the resource, when it says |
arguments |
Arguments pinned to this row |
source_arguments holds arguments that point at something instead of carrying a value, which is what lets one source feed another.
Every later change to either table arrives as a migration that checks before it writes, so php artisan migrate is the whole upgrade. Columns get added, indexes get moved onto the keys the code actually writes, and nothing is dropped from under an installation that is using it.
Where to go next
Quick start builds a working integration end to end. After that, Sources and Origins are the two halves in detail, and Reading and writing is where the rules about the cache live.