Download the PHP package dniccum/linear-sdk without Composer

Linear SDK for Laravel

[!NOTE] This is an unofficial, community-built package. It is not affiliated with, endorsed by, or sponsored by Linear. "Linear" and the Linear logo are trademarks of Linear. This package simply talks to Linear's public API.

Create Linear issues from your Eloquent models, the way Laravel Spark handles billing: add a trait to a model, let your users connect their Linear workspace on a ready-made configuration page, and issues are created for you from the model's lifecycle events.

• Model traits that add Linear attributes (linear_issue_url, linear_issue_identifier, linear_sync_status) and tie issue creation to created, updated and deleted.
• Optional configuration page with your own branding: connect (OAuth 2.0 with PKCE, or a personal API key), pick the team, project, status, labels, priority and assignee, and choose automatic or manual sending. Don't want it? Turn it off and build your own UI on the headless Actions.
• Safe by design: issues and comments are created from queued jobs with retries, are idempotent (a retry never creates a duplicate), and a failure never breaks the save of your own model.
• Fully typed (PHPStan level 9, strict TypeScript) and tested to 100% coverage.

Requirements

• PHP 8.3 or 8.4
• Laravel 12 or 13
• A Linear workspace, plus either a Linear OAuth application or personal API keys

Installation

Publish and run the migrations, then (optionally) the config file and the page's compiled assets:

Keep the front-end assets up to date

The configuration page's JavaScript and CSS are published into your public directory, so a copy from an older release stays there until you publish again. The page reads its asset manifest from the installed package but serves the files from public/vendor/linear, so after an upgrade with stale published files the page would link to bundles that no longer exist and fail to load. Re-publish them every time Composer updates the package by adding the command to the post-update-cmd scripts in your application's composer.json:

(laravel-assets is already there in a default Laravel application; add the linear-assets line beneath it.) The --force flag overwrites the previously published files, and the compiled files use hashed names, so browsers pick up the new version straight away. If you deploy with composer install, run the same command as a deploy step, or add it to post-install-cmd too.

If you do not use the built-in page (the ui route group is off, or you build your own UI), you can skip this.

Make sure a queue worker is running; issues and comments are sent from queued jobs.

Configuration

For OAuth, create an application at Linear → Settings → API → OAuth applications and register https://your-app.test/linear/callback as its callback URL. The requested scopes are read, issues:create and comments:create; the grant is refused if Linear returns fewer.

In api_key mode each owner pastes a personal API key (Linear → Settings → API). It is validated against Linear when saved, stored encrypted, and never expires.

Every option is documented in config/linear.php.

Quick start

1. Mark the owner

The owner is whoever connects a Linear workspace: usually a User or a Team.

2. Mark the models that become issues

That's it. When a SupportRequest is created and its owner has an active connection with a destination in automatic mode, an issue is filed in Linear. The model gains:

3. Send manually, retry, comment

4. Open the page

Visit /linear while signed in. Done.

Tying issues to model lifecycle events

Override linearEvents() to choose which events act on Linear (default: ['created']):

Set on_update / on_delete in config/linear.php.

Customising the issue

Override any hook on your model (or implement Dniccum\Linear\Contracts\ComposesLinearIssue to take full control):

Events

Listen for what happened:

The configuration page

GET /linear renders a standalone, branded page: connection card, destination form (team, project, status, labels, priority, assignee, automatic / manual), and a list of recent failures with a retry button.

Branding

Run php artisan vendor:publish --tag=linear-views to change the markup.

Authorization and the owner

By default the signed-in user ($request->user()) is the owner and the routes use the web and auth middleware. Customise from a service provider:

Change the URL or middleware with path and middleware in the config.

Back link

A "Back" link at the top of the page lets users leave the configuration interface. The text and the destination are both configurable, and the destination defaults to /dashboard:

When the destination depends on who is looking (a team, a tenant), choose it at runtime from a service provider's boot() method. The callback receives the owner and returns a route name, a path or a URL, or null to hide the link; it takes precedence over back.url:

The link is part of the settings payload (back) and of Linear::settingsFor($owner)->back, so custom UIs can render it too. If you embed <x-linear::settings /> inside your own layout, set back.enabled to false.

Signed-out users

If a user's session expires while they are using the page (or they open it signed out), they are sent to your login page instead of seeing a raw error. The page's requests that come back 401 or 419 redirect the browser, and package routes reached without a signed-in user redirect there too. The destination defaults to your login route and is configurable:

Embedding or disabling it

Embed the page inside your own layout, with the route group turned off:

The three route groups (ui, oauth, api) are independent. To register no routes at all, call Linear::ignoreRoutes() from a service provider's register() method.

Building your own UI

Everything the page does is available as headless, typed Actions, and as a documented HTTP contract (docs/custom-ui.md.

Disable the package routes (routes.* => false or Linear::ignoreRoutes()) and wire the Actions into your own controllers, Inertia pages or Livewire components.

Team, project, status and member visuals

The data the Actions return (and $owner->linearClient() / Linear::client($owner)) carries what Linear itself shows next to each choice, so a custom UI can look like Linear. All of it is optional (null when Linear sends nothing):

Priorities have no API data, so Dniccum\Linear\Enums\LinearPriority lists them (NoPriority=0, Urgent=1, High=2, Medium=3, Low=4) with label() and options(). toArray() on each DTO matches the HTTP contract exactly.

docs/custom-ui.md documents every field (type, nullability, meaning), how icons, colours and avatars should be rendered, what each status type means, and includes a complete custom controller and Blade view that works without the bundled UI.

[!IMPORTANT] Avatars are loaded by the browser directly from the avatarUrl Linear returns (the package never proxies them). If your app sends a strict Content-Security-Policy, its img-src directive must allow the image hosts of your members' avatars, in the bundled page as well as in your own UI. When an image is blocked or fails to load, the bundled page falls back to the member's initials on their avatar colour, so nothing breaks; it simply looks plainer.

Testing your application

Linear::fake() swaps Linear for an in-memory double, so no HTTP request is made:

Available helpers: withTeams(), withTeamOptions(), withViewer(), withTokens(), failWith(), assertIssueCreated(), assertIssueCreatedCount(), assertNoIssueCreated(), assertCommentPosted(), assertNoCommentPosted(), assertNothingSent().

How it behaves

• Idempotent. Each issue and comment gets a client-generated UUID. If a request times out after Linear created the issue, the retry finds and adopts it instead of creating a duplicate.
• Resilient. Jobs retry 5 times with backoff (30s, 2m, 10m, 30m). Rate limits and outages retry; permanent rejections fail fast and show up on the configuration page with a retry button.
• Safe. Lifecycle hooks swallow and report() their errors, so Linear can never lose or break a save of your own model.
• Self-healing auth. OAuth tokens refresh under a cache lock; connections whose authorization is revoked are marked needs reconnect and shown that way in the UI.

Frontend development

The page is TypeScript + Alpine compiled with Vite. The compiled assets are committed, so using the package never requires Node. To work on the page itself, see docs/frontend.md:

Testing the package

CI runs the PHP suite on PHP 8.3/8.4 × Laravel 12/13 × lowest/stable on Linux and Windows, plus PHPStan, Pint and the frontend checks.

Changelog

See CHANGELOG.

Contributing

See CONTRIBUTING.

Credits

• Doug Niccum
• Inspired by the billing experience of Laravel Spark.

License

The MIT License (MIT). See LICENSE.