Sailor Laravel Package

Technical Evaluation

Architecture fit

• Sailor is a client-side GraphQL code-generation package, not a GraphQL server or Laravel-native framework component. It fits Laravel/PHP applications that consume external or internal GraphQL APIs and want typed PHP classes instead of hand-written query strings.
• Best placement is an integration/service layer: generated client types and operations should not leak into domain models. Wrap Sailor behind application-specific interfaces so GraphQL transport details remain replaceable.
• If the Laravel application already exposes GraphQL via Lighthouse or another server, Sailor does not replace that server. It may still be useful for internal service-to-service clients, admin tooling, or contract tests against the schema.

Integration feasibility

• Feasible for a Composer-based Laravel app: install the package, point it at a schema or introspection endpoint, generate client code, and bind the generated client through a Laravel service provider.
• The main uncertainty is HTTP transport integration. Confirm whether Sailor supports PSR-18, Guzzle, or Laravel’s HTTP client directly; otherwise add a thin adapter and centralize auth headers, retries, timeouts, and logging.
• Code generation must be part of the build/CI workflow rather than a manual developer step. Treat generated files as build artifacts or reviewed generated code, not hand-edited source.

Technical risk

• Adoption signal is weak: 95 GitHub stars and an overall score around 20.46 indicate a niche package with limited ecosystem validation. Maintainer concentration and long-term support are real risks.
• Release metadata shows a future-dated release relative to the current date; verify actual release cadence, tags, and package health before committing.
• Type safety is only as strong as the schema and generation workflow. Schema drift, nullable-field changes, deprecated fields, and partial GraphQL errors can still cause runtime failures.
• Generated-code churn can create noisy diffs and merge conflicts. Dependency constraints around PHP, PSR interfaces, Guzzle, and GraphQL libraries need validation against the target Laravel version.

Key questions

• Which GraphQL endpoints and operations are in scope: queries, mutations, subscriptions, file uploads, persisted queries?
• Who owns the GraphQL schema contract, and how are breaking changes communicated?
• Does Sailor support the required auth model: bearer tokens, cookies, mTLS, custom headers, tenant routing?
• Can it use Laravel’s HTTP client or a PSR-18 client with Laravel-compatible middleware?
• Is code generation deterministic and CI-friendly? Can it run offline from a checked-in schema?
• How are GraphQL errors, partial responses, HTTP failures, and retries represented in generated types?
• What PHP/Laravel versions are supported, and what is the dependency footprint?
• Is there an internal owner and fallback plan if the package becomes unmaintained?

Integration Approach

Stack fit

• Suitable for Laravel/PHP services that need a typed GraphQL client and already use Composer, PSR autoloading, and CI-based builds.
• Wrap Sailor in a Laravel service provider or small adapter layer. Inject the client into actions, jobs, and integration services rather than calling it directly from controllers.
• Store generated code in a clearly named namespace, such as App\Integrations\GraphQL\Generated, and exclude it from domain-level imports.
• If Sailor does not natively use Laravel’s HTTP client, bind a PSR-18/Guzzle client configured with Laravel-style middleware for auth, correlation IDs, retries, and logging.

Migration path

• Start with a time-boxed spike against one non-critical GraphQL operation. Generate types, call the endpoint, and compare behavior with the existing manual client.
• Introduce an application-level interface around the GraphQL operation before migrating callers. This keeps the migration reversible.
• Pin the schema used for generation, add contract tests for representative responses, and only then expand to additional operations.
• Avoid a big-bang migration. Move one bounded use case at a time and retain the existing client until parity is proven.

Compatibility

• Verify PHP and Laravel version constraints, PSR interface versions, Guzzle/Symfony dependency overlap, and compatibility with existing static analysis such as PHPStan or Psalm.
• Confirm that schema introspection is available in CI and non-production environments, or check in a schema file and generate offline.
• Validate generated code style against project standards. If generated files are committed, add them to formatting/lint exclusions or establish a review policy.
• Run Composer audit and dependency-resolution checks in a branch before adopting.

Sequencing

1. Run a technical spike: install, generate one operation, authenticate, and exercise error cases.
2. Define schema ownership, version pinning, and code-generation commands.
3. Add generation to CI and fail builds on schema drift or generation failure.
4. Build a Laravel adapter for transport, auth, retries, logging, and error mapping.
5. Integrate one read-only query, then one mutation with idempotency and failure handling.
6. Add contract tests, monitoring, and a rollback path to the existing client.
7. Expand operation coverage only after the first use case is stable.

Operational Impact

Maintenance

• Requires ongoing ownership of the generator configuration, schema pinning, and generated-code review process. Generated files should never be edited manually.
• Low package activity increases the need to pin versions and monitor upstream changes. Keep the integration adapter thin so replacing Sailor is feasible.
• Schema changes must be treated as API contract changes with review, tests, and staged rollout.

Support

• Support is community/GitHub-based under MIT, with no commercial SLA. The team must own operational support and incident response.
• Document a fallback path to hand-written GraphQL requests or an alternative client if the package becomes unavailable.
• Maintain internal runbooks for codegen failures, auth failures, and schema incompatibilities.

Scaling

• Client-side code generation has negligible runtime scaling impact; the remote GraphQL service remains the primary bottleneck.
• Large schemas may slow CI generation. Cache generated artifacts or generate only the operations needed for the build.
• For high-volume calls, use connection reuse, timeouts, retries with backoff, and circuit breakers in the adapter layer.

Failure modes

• Schema drift or breaking schema changes causing generated-type mismatches.
• Codegen failures blocking builds or producing incomplete classes.
• Auth token expiry, missing headers, or tenant-routing mistakes.
• Network timeouts, rate limits, HTTP 5xx responses, and GraphQL partial errors.
• Nullability mismatches between schema and runtime responses.
• Dependency conflicts with Laravel, Guzzle, or static-analysis tooling.
• Generated-code merge conflicts or accidental manual edits.

Ramp-up

• PHP developers familiar with Composer and Laravel service providers should ramp up quickly, but they need GraphQL schema literacy and discipline around generated code.
• Budget a short spike and a written integration guide covering generation, auth, error handling, and rollback.
• Treat Sailor as a tactical productivity tool rather than a strategic platform dependency until adoption, maintenance, and release cadence are validated.