Weave Code
Linearavel Laravel Package
glhd/linearavel
Linearavel is a Laravel client for Linear's GraphQL API. Query issues, projects, teams, and cycles from your app with an expressive interface, config-driven auth, and typed responses built on Laravel's HTTP client, so you can sync Linear data or build integrations without hand-writing GraphQL.
At a glance
Frequently asked questions about Linearavel
- How do I install Linearavel in a Laravel application?
- Install it as a standard Composer dependency with composer require glhd/linearavel. Authentication is config-driven, so place your Linear API key or OAuth token in your environment and reference it from the package configuration instead of hard-coding it. Then resolve the client through Laravel's container and start querying issues, projects, teams, or cycles.
- Which Laravel versions does Linearavel support?
- The 0.2.9 release notes do not state any framework-version coupling, and the package is described as a standard Composer dependency built on Laravel's HTTP client. Check the package's composer.json constraints or Packagist metadata for the exact Illuminate requirements before upgrading. Test the install against your application's Laravel version rather than assuming compatibility from the release notes alone.
- How does Linearavel authenticate with Linear?
- Linearavel uses config-driven authentication, so you supply a Linear API key or OAuth token through the package configuration. In production, source that value from your existing secrets management or environment variables rather than committing it to config files. Keeping credentials outside package-local config also makes it easier to rotate tokens without code changes.
- Do I still need to write GraphQL queries with Linearavel?
- Linearavel is a schema-derived client that gives you an expressive PHP interface and typed responses, so you do not hand-write GraphQL for the operations it covers. It is generated from a Linear schema snapshot, which means coverage follows that snapshot rather than being hand-curated. For uncommon fields or operations outside the generated surface, verify support before assuming the package exposes them.
- Should I use Linearavel's generated types directly in controllers and Eloquent models?
- No, treat Linearavel as an anti-corruption boundary rather than letting generated types leak into your domain code. Wrap it behind an application-owned LinearClient port with your own DTOs, then call that interface from controllers, jobs, and models. Because the generated code is disposable and version-coupled, the wrapper turns a future package bump into a one-file change instead of a codebase-wide refactor.
- What changed in Linearavel 0.2.9 and is it a breaking release?
- Release 0.2.9 is described as purely additive and non-breaking, adding three optional input fields and four new enum members. Optional fields such as inlineAnchorFrom and inlineAnchorTo on CommentCreateInput require no consumer changes, and existing mutation payloads remain valid. Enum widening is backward compatible at the wire level, though it can still affect exhaustive match statements in your own code.
- Can new Linear enum values break my application after a Linearavel update?
- Yes, if your code enumerates WorkflowTrigger or DocumentShareRole in a match expression or switch without a default arm. Linearavel 0.2.9 adds addedToMergeQueue and removedFromMergeQueue to WorkflowTrigger and comment and view to DocumentShareRole, which can trigger UnhandledMatchError or silent fallthrough. Add defensive default handling or an explicit unknown-value mapping, and grep for exhaustive matches after every package upgrade.
- How stable is Linearavel for production given its pre-1.0 version?
- At 0.2.x the package makes no stability guarantees beyond minor-version semantics, and each release is a full schema regeneration rather than a hand-written patch. That means you inherit Linear's schema evolution on the package author's cadence, not yours, and a future regeneration could rename or remove fields. Pin the version, review the actual diff instead of trusting terse changelog summaries, and contain the client behind your own interface.
- How do I test code that depends on Linearavel?
- Because Linearavel is built on Laravel's HTTP client, you can typically use Http::fake to stub the outbound GraphQL responses in feature tests. If you have wrapped the package behind a LinearClient port, bind a fake implementation in the container and test your application logic without touching generated types. Keep at least one integration-style test against a sandbox Linear workspace to catch schema and enum drift.
- What should I check before running Linearavel in production, and what are the alternatives?
- Confirm the package's HTTP layer matches your outbound-integration conventions, including retry and backoff behavior, timeout configuration, and how credentials flow through secrets management. Also verify who owns the schema snapshot date and whether it is current relative to Linear's live schema. If the pre-1.0 churn is unacceptable, alternatives are a hand-written GraphQL client over Laravel's HTTP client or an existing maintained Linear SDK wrapped in your own adapter.
Weaver
How can I help you explore Laravel packages today?