Laravel Integrations Adapters Laravel Package

Getting Started

• Install with composer require solmyrhq/laravel-integrations-adapters, then publish the config (php artisan vendor:publish --tag=integrations-config) and add provider credentials to .env — the package is credential-driven, so nothing works until at least one adapter is configured.
• Look first at the README's "Adapters" table to see which providers ship out of the box (GitHub is the mature one) and at config/integrations.php to understand how an adapter is registered and resolved. Then read the adapter class itself — the mapping between the provider's payload and your models is where all the real behaviour lives.
• First use case: mirror GitHub issues and their comments into local Eloquent models so you can build an inbox/dashboard without hitting the GitHub API on every page load. Point the adapter at a repo, run the sync command once manually, and inspect the resulting rows before wiring it into a schedule.

Implementation Patterns

• Adapter-per-provider, resolved from the container. Treat each adapter as a thin translation layer: authenticate, paginate, map to a normalised payload. Keep your own persistence (models, upserts, observers) outside the adapter so swapping or adding a provider doesn't ripple into your domain code.
• Idempotent upserts keyed on the external ID. Every sync run should updateOrCreate against a (provider, external_id) unique index. This makes re-runs safe, makes backfills cheap, and is the only sane way to recover after a failed or partial sync.
• Scheduled incremental sync, not full sync. Run a queued job on a short schedule (every 5–15 minutes) that passes a watermark — the last successful sync timestamp — into the adapter. Keep a separate, infrequent full-reconcile job for drift correction and deletions.
• Webhooks as an accelerator, polling as the source of truth. If you register GitHub webhooks, use them to trigger an immediate targeted sync of a single issue rather than to write data directly. Payload trust and ordering are both problems you don't want; the scheduled cursor-based sync stays authoritative.
• Map to your own shape early. Normalise provider payloads into your models at the boundary, then let your app work only with your models. Provider field names (body, state, user.login) leak everywhere otherwise and every adapter upgrade becomes a grep-and-replace exercise.
• Test with recorded fixtures. Because adapters are HTTP-boundary code, Http::fake() with captured JSON is the highest-value test you can write — especially for pagination and for the "resource exists but child collection is stale" cases.

Gotchas and Tips

• Eventual consistency between list and child endpoints is real. 6.1.0 fixes exactly this: a new comment can exist on an issue that the issues list endpoint hasn't caught up with yet, so a naive "sync issues, then sync comments for issues whose updated_at changed" loop silently drops comments. Don't assume the list response is a fresh index — fetch comments per issue with an overlapping since window, and re-check issues that were touched recently rather than only those the list flagged.
• Overlap your cursors. Always re-query a few minutes behind your stored watermark. Clock skew and provider-side write lag both cause missed records at the boundary, and the cost of a small overlap is one redundant upsert.
• Watch rate limits and pagination together. A sync that pages correctly but ignores the remaining-quota headers will work fine in dev and die in production on a busy repo. Fail the job loudly on 403/429 and let the next scheduled run resume from the watermark.
• Run php artisan config:cache deliberately. Credentials read via env() outside the config file return null once config is cached — a classic "works locally, breaks in CI" failure with packages like this.
• Handle deletions explicitly. Providers rarely tell you something was deleted; you either reconcile the full ID set periodically or live with tombstones. Decide which, write it down.
• Extension points worth knowing: custom adapter registration in the config, any mapping/transformer hook the adapter exposes (use it instead of forking), and the events dispatched after a sync completes — those are the right place to hang cache invalidation or notifications rather than editing package code.
• Pin the minor version and read the changelog on bumps. This release is a pure bug fix with no API surface change, but sync correctness fixes are the kind that silently backfill data — run a full reconcile once after upgrading to 6.1.x to pick up comments the previous version missed.