{"id":21032124,"url":"https://github.com/daltonmccleery/remote-models","last_synced_at":"2025-05-15T13:30:49.221Z","repository":{"id":247593165,"uuid":"826370766","full_name":"DaltonMcCleery/remote-models","owner":"DaltonMcCleery","description":"Sometimes you want to use Eloquent, but that data is in another database on a different application.","archived":false,"fork":false,"pushed_at":"2025-02-24T20:57:53.000Z","size":60,"stargazers_count":30,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-12T02:50:55.872Z","etag":null,"topics":["laravel","package","php","remote","remote-models"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DaltonMcCleery.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["daltonmccleery"]}},"created_at":"2024-07-09T15:21:40.000Z","updated_at":"2025-02-24T20:55:51.000Z","dependencies_parsed_at":"2024-07-16T15:47:05.107Z","dependency_job_id":"1618dcbe-665e-4eef-a6f9-668c0f84700e","html_url":"https://github.com/DaltonMcCleery/remote-models","commit_stats":null,"previous_names":["daltonmccleery/remote-models"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaltonMcCleery%2Fremote-models","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaltonMcCleery%2Fremote-models/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaltonMcCleery%2Fremote-models/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DaltonMcCleery%2Fremote-models/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DaltonMcCleery","download_url":"https://codeload.github.com/DaltonMcCleery/remote-models/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254349231,"owners_count":22056303,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["laravel","package","php","remote","remote-models"],"created_at":"2024-11-19T12:40:49.729Z","updated_at":"2025-05-15T13:30:48.848Z","avatar_url":"https://github.com/DaltonMcCleery.png","language":"PHP","funding_links":["https://github.com/sponsors/daltonmccleery"],"categories":[],"sub_categories":[],"readme":"# Remote Models\n\nSometimes you want to use Eloquent, but that data is in another database on a different application.\n\nThis package is used for both the \"host\" application and the \"remote\" application. Both use cases are detailed below, or \nyou can look at [these examples](EXAMPLES.md).\n\n## Requirements\n\nThe [`pdo-sqlite` PHP extension](https://www.php.net/manual/en/ref.pdo-sqlite.php) must be installed on your system to use this package.\n\nYou will need to set up any endpoints on the host application where the data is stored.\n\n## Install\n```\ncomposer require daltonmccleery/remote-models\n```\n\n### Publishing the Config\n\nIt is recommended to publish the config file; this will allow you to add a host domain, API pathing, and any Models.\n\n```console\nphp artisan vendor:publish --provider=\"RemoteModels\\RemoteModelsServiceProvider\" --force\n```\n\n## Remote Use\n\nUsing this package consists of two steps:\n1. Add the `RemoteModel` trait to a model.\n\nThat's it.\n\n```php\nclass Celebrity extends Model\n{\n    use \\RemoteModels\\RemoteModel;\n}\n```\n\nNow, you can use this model anywhere you like, and it will behave as if the table exists in your application.\n```php\n$celebrity = Celebrity::where('name', 'Dwayne Johnson')-\u003efirst();\n```\n\nThis will allow you to add a host domain, API pathing, and any Models.\n\n### Custom Endpoint\n\nYou may provide a custom endpoint to your Remote Model that will be called when the model is loaded. If you do this and\nhave this package installed on your host application, you will need to create your own API endpoint.\n\n```php\nclass Celebrity extends Model\n{\n    use \\RemoteModels\\RemoteModel;\n\n    protected $remoteEndpoint = '/v1/celebrities';\n}\n```\n\n### Custom Schema\n\nRemote Models will auto-discover the schema from the first API call, however, if you want more control over the schema or\nwhat fields are saved locally, you may add them to a `$schema` property with a type cast for the column.\n\n```php\nclass Celebrity extends Model\n{\n    use \\RemoteModels\\RemoteModel;\n\n    protected $remoteSchema = [\n        'name' =\u003e 'string',\n        'birthday' =\u003e 'datetime' \n    ];\n}\n```\n\n## Host Use\n\nThis package is dependent on a separate Laravel application that \"hosts\" the Models and their data. You will need to either\ninstall this package on the host application as well and enter the \"remote\" models you wish to expose to the \"remote\" application.\n\n```php\n// config/remote-models.php\n'host-models' =\u003e [\n    \\App\\Models\\Celebrity::class\n]\n```\n\n### Custom Endpoint\n\nIf you use a custom endpoint on the remote application, you will need to set up that custom route. You can use the following as an example:\n\n```php\nRoute::post(\n    config('remote-models.api-path') . '/v1/celebrities',\n    fn (\\RemoteModels\\Http\\Requests\\CustomRemoteModelRequest $request) =\u003e $request-\u003ereturnRemoteModels(Celebrity::class)\n);\n```\n\nIf you do **not** install this package on the \"host\" application, a custom endpoint will need to be set up for each Remote Model\nyou plan on using. You will also need to manually validate the given API Key. You can use the following as an example:\n\n```php\nRoute::post('/api/_remote/_models/v1/celebrities', fn () =\u003e response()-\u003ejson(Celebrity::paginate())));\n```\n\nYou are not required to install this package on the \"host\" application. If you don't, you will need to set up your own API\nendpoints for the models you wish to use. It is recommended to use Laravel's default [pagination](https://laravel.com/docs/11.x/pagination#paginating-eloquent-results).\n\n## Cache Interval\n\nYou can set how long to cache the remote data for using the `cache-ttl` config option. These values follow the standard \n[DateTime Interval](https://www.php.net/manual/en/class.dateinterval.php properties. Below are a few examples:\n\n```php\n// config/remote-models.php\n'cache-ttl' =\u003e '1m | 1w | 1d | 1h' // 1 month | 1 week | 1 day | 1 hour\n```\n\n## External Host Data\n\nThere may be instances where you do not control the \"host\" application, i.e. it could be a Google Spreadsheet or a 3rd \nparty API, but would still like a way to query that data using Eloquent. \n\nYou'll need to have your Model implement the `RemoteModelInterface` and include the base `RemoteModelManagement` trait.\nThis will have you implement 2 methods for setting up a custom schema (optional) and recursively fetching the data. In this instance, \nthe `$remoteEndpoint` is optional.\n\nYou can create your own Remote Model by following this example:\n\n```php\nclass Celebrity extends Model implements \\RemoteModels\\Interfaces\\RemoteModelInterface\n{\n    use \\RemoteModels\\RemoteModelManagement;\n\n    public function migrate(): void\n    {\n        $this-\u003ecreateRemoteModelTable(schemaCallback: function (array $schema) {\n        \n            // Make any modifications to the column schema before the sqlite table is created.\n\n            return $schema;\n        });\n\n        $this-\u003eloadRemoteModelData();\n    }\n    \n    public function loadRemoteModelData(int $page = 1): void\n    {\n        // Normal operation is a POST request with the config API key,\n        // but you are free to modify the API call as you like.\n        $response = \\Illuminate\\Support\\Facades\\Http::get($this-\u003egetRemoteModelEndpoint());\n        \n        $data = $response-\u003ejson();\n\n        // `insertRemoteModelData` is available and takes an array of data to be inserted.\n        $this-\u003einsertRemoteModelData($data['data'], $data['per_page'] ?? 15);\n\n        // Call the next page, if available.\n        if ((int) $data['current_page'] \u003c (int) $data['last_page']) {\n            $this-\u003eloadRemoteModelData((int) $data['current_page'] + 1);\n        }\n    }\n}\n```\n\n## How It Works\n\nWhen a Model is called, it will make an API call to the either a custom endpoint or to a predefined endpoint using the Model's\nname. This predefined API endpoint can be configured in the config file.\n\nUnder the hood, this package creates and caches a SQLite database just for this model and all its data.\nIt creates a table and populates it with the returned, paginated API data.\nIf, for whatever reason, it can't cache a .sqlite file, it will default to using an in-memory sqlite database.\n\nThis package was _heavily_ inspired by Caleb Porzio's [Sushi](https://github.com/calebporzio/sushi) package.\n\n## Upcoming Features\n\n- Add command for pre-caching all Remote Models for deployment.\n- Add local database fallback\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaltonmccleery%2Fremote-models","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaltonmccleery%2Fremote-models","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaltonmccleery%2Fremote-models/lists"}