Sailor Laravel Package

Product Decisions This Supports

• Build vs. buy, for integration layer: Instead of budgeting engineering weeks to hand-roll a client for a third-party GraphQL API (typed request builders, response hydration, error mapping), Sailor generates those classes from the schema. The decision becomes "adopt codegen" vs. "build and maintain a bespoke client" — a cost/risk trade rather than a feature bet.
• Roadmap scoping for integrations: Expanding an integration's surface area (new fields, new objects, new endpoints) becomes a regeneration-and-review task instead of new client code. This lowers the marginal cost of adding scope to a GraphQL-backed feature and should be reflected in estimates.
• Feature feasibility for Laravel backends consuming GraphQL: Makes server-to-server GraphQL consumption (headless CMS, commerce platforms, internal services exposing GraphQL) viable inside a PHP codebase without introducing a Node/TS sidecar purely for typed clients.
• Quality investment and release risk: Typesafe query construction moves upstream schema breakage from runtime (nulls, 400s, partial data in production) to static analysis and CI. That's a concrete argument for shifting effort from QA/manual regression toward PHPStan/CI gates — and for treating schema version pinning as a release-planning dependency.
• Architecture direction (BFF / internal service mesh): Supports a decision to standardize on GraphQL between services, since the PHP side gains a credible typed client story. Conversely, if this package is the only viable PHP client, that weakens a GraphQL-everywhere mandate.
• Dependency and provenance decisions: With a small star count and an unresolved repository reference, adopting this is also a supply-chain decision — pin versions, vendor generated output, and decide whether the team owns the generator if upstream stalls.

When to Consider This Package

Adopt when:

• You have a concrete, reasonably stable GraphQL schema (SDL file or introspection endpoint) and a PHP/Laravel codebase that must consume it.
• Your team values IDE autocompletion and static analysis on query construction, and already runs PHPStan/Psalm in CI.
• You're already in the Lighthouse/GraphQL-in-PHP orbit — same author lineage, familiar conventions, lower conceptual overhead.
• The integration is non-trivial enough to justify codegen — multiple operations, nested types, or an expectation of schema evolution.

Look elsewhere when:

• The API is REST/OpenAPI; use an OpenAPI generator instead. Forcing GraphQL tooling onto REST is a category error.
• You need to author a GraphQL server in Laravel — that's Lighthouse, not Sailor.
• Queries are user-defined or highly dynamic at runtime; generated typed builders assume known operations at build time.
• It's a single throwaway query — a plain HTTP client and an inline query string is cheaper than a codegen pipeline.
• You require vendor support, SLAs, or a large hiring pool — 95 stars and a single-maintainer profile won't satisfy procurement or on-call expectations on their own.
• You need subscriptions/websockets or advanced transport behavior as a first-class concern; validate that explicitly before committing.

Non-negotiable adoption criteria regardless: pin the version, commit generated code to the repo (so it survives upstream abandonment), and confirm the repository/provenance story before it enters your dependency graph.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed code generator that produces a typed PHP client from a GraphQL schema, replacing hand-written integration code. The business case is speed and defect reduction on API integrations — less bespoke code to write, review, and maintain, and upstream API changes surface in CI rather than in production. There's no license cost and no vendor lock-in: the generated code lives in our repository and can be regenerated or discarded if we walk away.

To engineering: Schema-first codegen gives us typed request builders, autocompletion, and static-analysis coverage on every GraphQL call, and it doesn't dictate our HTTP/runtime layer. Generated classes are checked in and version-pinned, so the build is reproducible and the blast radius of an upstream change is a compile error, not a 3 a.m. page.

Honest caveats to state up front: it's a small-community package with a concentrated maintainer risk and an unresolved repository reference — we should treat it as something we may eventually own, budget a modest spike to validate it against our actual schema, and keep a fallback (hand-written client or a different generator) documented before it becomes load-bearing.