Partner Laravel Package

Getting Started

gando/partner is a Speakeasy-generated PHP SDK for the Partner API (OpenAPI 1.0.0), published to Packagist. v0.1.11 is a straight regeneration — no documented feature or breaking changes — so treat it as a routine rebuild of the same surface.

First steps:

1. composer require gando/partner (pin the version — see Gotchas).
2. Read vendor/gando/partner/README.md and the generated composer.json for the required PHP version and Guzzle constraint. Speakeasy output assumes a modern PHP (8.1+) and pulls its own HTTP layer.
3. Skim src/ for the top-level client/connector class, the per-resource service classes, and the Models/ and Errors/ directories. That directory layout is your real API documentation — the OpenAPI spec is baked into those classes.
4. Get a key into .env as PARTNER_API_KEY, then make one read call in php artisan tinker before writing any app code. Success there proves auth, base URL, and Guzzle wiring all at once.

First real use case: a scheduled or queued sync job that pulls a single resource (one list endpoint plus one get-by-id) and writes it into Eloquent. Don't start with writes — a read-only smoke test distinguishes auth/config problems from payload-shape problems.

Implementation Patterns

Bind the client as a singleton. Generated SDKs ship no Laravel service provider, so wire it yourself in AppServiceProvider:

$this->app->singleton(PartnerClient::class, fn () => (new PartnerClient())
    ->setSecurity(config('services.partner.token')));

Add config/services.php → 'partner' => ['token' => env('PARTNER_API_KEY'), 'base_url' => env('PARTNER_BASE_URL')]. Keeping base URL in config is what makes sandbox/staging switching painless.

Wrap, don't call directly. Generated classes are regenerated wholesale on every release. Put a thin App\Services\Partner\PartnerGateway around the SDK that exposes only the calls your app actually uses, and always inject the interface, never the concrete generated class. When the SDK's model properties or method names shift, you fix one file instead of forty.

Translate errors at the boundary. Catch the generated typed exceptions in the gateway and rethrow as domain exceptions. This keeps vendor error classes out of your controllers and jobs.

Queue the writes. Any create/update call belongs in a job with $tries, backoff(), and idempotency handled by your own correlation key — retries are configured on the client, but those are transport retries, not business-level idempotency.

Use the SDK's own pagination helpers rather than hand-rolling offset loops; generated iterators handle the cursor/next-token plumbing and are the part most worth not reimplementing.

Testing: don't reach for Http::fake() — the SDK doesn't use Laravel's HTTP client, so those fakes are invisible to it. Instead bind a fake gateway behind your interface for feature tests, and reserve the real SDK for a small, tagged integration suite that hits a sandbox.

Gotchas and Tips

• 0.x semver is a trap. ^0.1.11 resolves to >=0.1.11 <0.2.0, but pre-1.0 minor bumps routinely carry breaking changes. Pin exact (0.1.11) or use a narrow 0.1.* and actually read the release diff. This release is a no-op regeneration; the next one may not be.
• Regeneration is a full-file overwrite. Never patch anything under vendor/gando/partner. If the generated code has a bug or a shape you dislike, adapt in your gateway. Otherwise your fix silently disappears at the next composer update.
• vendor/ diffs are your changelog. These release notes are machine-generated and say nothing about the API surface. On upgrade, diff the tags (git diff v0.1.10..v0.1.11 -- src/) or just diff -r two vendor directories. Property renames and nullability changes appear there and nowhere else.
• Guzzle constraint collisions. The SDK pins its own Guzzle range. If you also use Laravel's Http client or another SDK, check composer why guzzlehttp/guzzle before blaming the new release for an unresolvable dependency.
• Serialization surprises. Generated models often use DateTimeImmutable and nullable union types. Passing a plain string where a DateTimeInterface is expected, or forgetting a required field is non-nullable, surfaces as a transport-level validation error rather than a clear PHP type error — read the exception body, not just the message.
• Auth and base URL are set on the client instance, not per-call. In long-running Octane or queue workers, make sure the singleton is configured once at boot; mutating a shared client mid-request is a race.
• Extension points are limited by design. If you need custom headers, a specific timeout, or middleware, do it through the client's configuration rather than subclassing generated service classes — subclasses won't survive regeneration either.
• Bump cadence is high (this is a patch-level regeneration cadence). Budget a recurring dependency-update task rather than pinning forever; pinning an abandoned 0.1.x build will eventually block PHP upgrades.