Download the PHP package edulazaro/larasources without Composer

On this page you can find all versions of the php package edulazaro/larasources. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package larasources

Larasources - External data sources for Laravel models

Tests Latest Stable Version Total Downloads PHP Version License

A Laravel package for integrating external data sources into your models, with a write-through cache in your own database. Work with external APIs using model-like abstractions, without forcing those APIs to live in your own tables.

Why

Larasources lets your Eloquent models pull and push data from external services through a typed, declarative Source API. Each source declares its fillable fields, casts, mappings, and origin (the API client). Your domain model stays clean, the integration layer stays separated, and the cached external state lives in a single dedicated table.

Features

Requirements

Continuous integration runs the suite against every supported PHP and Laravel combination, plus PHP nightly as an early warning.

Installation

Run the migrations:

Configuration

The package has no configuration file and no environment variables of its own. What an origin needs is the integration's own, and config() is where it resolves it.

config() works like Laravel's config() helper without the prefix: the origin puts larasources.origins.{alias} in front and the caller only names the key, so static credentials can live in a config of your own:

When the credentials are not static, which is the usual case in multi-tenant applications, override config() and read them from wherever they live:

timeout and retry go through the same method, so an origin that builds its requests with $this->http() gets the timeout and the retries of that integration. Without them the client makes a single attempt with the origin's $timeout property.

A Source has the same accessor over its own block, larasources.sources.{name}, where the name is the key it is mapped under on the model:

Override it the same way when those settings are not static, for instance to serve them from the origin's integration.

Usage

1. Add the HasSources trait to your model

2. Read and write through the source

3. Define a Source

4. Define an Origin (the API client)

5. Arguments that point at something else

An argument can point at a model, or at another source, instead of carrying a value:

It is a pointer, not a copy: the origin reads that source's payload as it is when it reads it, so a pipeline where one source is built out of another never carries a stale copy from one row to the next. The payload arrives uncast, because casts belong to the source that owns those fields.

The pointer is stored, so it is still there on a later read, and forgetArgument('scraped') removes it. A name points at one thing only.

6. Variants and arguments

Use variants to handle multiple modes per source (for example, sale vs rent for a property listing, or current vs forecast for weather):

The arguments() map declares which attribute of the model feeds each argument, and resolveArguments() turns it into values: with ['city_id' => 'external_id'] the origin receives ['city_id' => $city->external_id], or null when the attribute is empty. Precedence, from lowest to highest: the $arguments property, the arguments() method, the arguments stored on the SourceRecord, and the runtime arguments passed to source().

Arguments that do not come from the model live on the record, either in its arguments JSON column or as SourceArgument rows pointing at another model or record. They are written by your app, not by persist(), which only refreshes the cached attributes: a resolved value stored there would shadow the model from then on.

Caching

Sources are cached automatically in the sources table (the SourceRecord model). Each record is keyed by (sourceable, name, variant).

Reading an attribute autoloads: it fills from the cached record when there is one, and goes to the origin when there is not. When the origin cannot answer that first read, the source falls back to build() in memory and nothing is stored: a record written there would say the origin has data it has never seen, and every later read would trust it. The next read goes back to the origin. Only OriginException is caught, so a bug in an origin surfaces instead of looking like a service being down. fetch() always goes to the origin and writes the result through to the record, so the cache is never left behind after a live read. A source with no model attached has nothing to cache, and fetch() just fills the instance.

The cache does not expire on its own: once a record exists, reading attributes never calls the origin again. Refresh it when your app decides to, with fetch().

Records the origin has not finished with

Some services take the payload and publish it later. An origin says so by returning an OriginResult from save() instead of the response array:

The status is stored on the record, so a processing row says "the service took this and had not finished with it". Reading it never calls the origin: nothing in this package goes to a service while you read an attribute of a record that exists.

What is still waiting is a query, not something your app has to remember:

And reconcile() resolves one. It re-reads from the origin when the record is still processing and leaves it alone when it is not, which is the only thing that turns it into saved. It converges on whatever the service really ended up with, even when the payload was rejected in the end:

A record only exists because an origin took the data, so status holds saved or processing, never failed.

Operations beyond fetch, save and delete

An origin's own methods are callable, because origin() is public. Use that when you just want the answer:

And when the answer is the source's new state, name it on your source and write it through with the same two public calls fetch() uses:

Typed, autocompleted, and the name says what it does. The package deliberately has no run('someMethod') dispatcher: it would trade methods for strings and let a caller fill a source from something that is not the source's data.

What the service calls it

A write usually comes back with the service's own id for the resource. An origin reports it and the row keeps it, which is optional: an origin that reports nothing leaves it empty and nothing is read out of the response to guess it.

It buys two things. The next write knows whether to create or update without the application passing the id in:

And an id arriving from the outside, in a webhook or a reconciliation listing, finds the local model it belongs to:

A fetch() never clears it, because reading does not report one.

Sources with no model yet

A row is identified by its model or, when there is none, by the external id. That covers the flow where the payload comes first and the thing it describes is derived from it: a scraper that reads a listing, stores each item, and only then decides what it becomes.

Two things to know about it:

With neither a model nor an external id, nothing is stored: ListingSource::make()->fetch() reads the origin and fills the instance, which is what you want for a throwaway read.

Error handling

An origin signals failure by throwing: returning means it took the data, and the source persists its record right after the call returns. So a failure that returns instead of throwing is stored as if it had worked.

That is what a queued job wants: it catches, backs off and retries. When the caller would rather branch than catch, typically because it renders, trySave() returns the outcome and persists nothing unless the origin took the data:

Nothing is written when a save fails, so what was already stored stays untouched: the record never gets ahead of the origin.

Testing

Mock a source so it returns a fixed instance instead of hitting the origin:

API reference

Source

Origin

SourceRecord

OriginResult

What the origin reports about a write. status is an OriginStatus (Saved, Processing, Failed), data the response, message the reason when there is one, exception the cause of a failure and externalId the service's own id for the resource.

Bundled abstract Origins

Testing

The suite runs on Testbench with an in-memory SQLite database. tests/Fixtures holds a sourceable model, a source and two origins (one plain, one going through the package's HTTP client) that the tests build on.

Sponsors

Larasources is supported by the following sponsors. Thank you for keeping it growing:

Kenodo     AndorraDev

Author

Created by Edu Lazaro

License

Larasources is open-sourced software licensed under the MIT license.


All versions of larasources with dependencies

PHP Build Version
Package Version
Requires php Version >=8.4
illuminate/support Version >=12.0
illuminate/database Version >=12.0
illuminate/http Version >=12.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package edulazaro/larasources contains the following files

Loading the files please wait ...