README

Connect your Laravel application with Linear

This package will allow you to connect your Laravel application with Linear via a Linear OAuth App.

Installation

You can install the package via composer:

composer require marshmallow/laravel-linear

After you've installed the package you can run the installation command. This command will publish the mandatory migrations and publish components and assets that are needed to show the beautiful Linear pages.

php artisan linear:install

Optionally, you can publish the config file with:

php artisan vendor:publish --tag="laravel-linear-config"

Create your Linear OAuth App

Go to settings in your Linear account. In the account menu, you will find the API button. Once you click on API you will be able to create an OAuth application. Click on Create New.

Fill in all the fields. The most important part is the Callback URLs. You need to add your callback URL like your-domain.test/linear/oauth2/callback. Add the callback url for all your domains. Local, Beta and Production so it will work on all your sites.

When you've created your app, you will get a Client id and a Client secret. Copy these, we need them later!

Configuration

The config file (config/linear.php) exposes the credentials for your Linear OAuth application. All values are read from your .env file:

Usage

Using this package is super easy. We just need to make two minor updates to your application.

Update your .env file

When you created your Linear OAuth Application you got a Client id and a Client secret. You need to add them to your .env file.

LINEAR_CLIENT_ID="____YOUR_CLIENT_ID____"
LINEAR_CLIENT_SECRET="____YOUR_CLIENT_SECRET____"

Update your Authenticatable model

First you need to be logged in to your application. This is so not everybody can change the connection to Linear.

On your Authenticatable model, usually the User model, you need to implement one new method to let the package know who can manage the Linear connection. Add the method below.

class User extends Authenticatable
{
    // ...
    public function allowedToManagerLinearConnection(): bool
    {
        return in_array($this->email, [
            'stef@marshmallow.dev',
        ]);
    }
}

Go to your-domain.test/linear/auth and follow the steps to connect your Laravel application to Linear. After you've done this you will be able to connect a company, team and project.

Submit your first issue

Build a LinearIssue message and send it to a notifiable via the NewLinearIssue notification:

use App\Models\User;
use LaravelLinear\Notifications\NewLinearIssue;
use LaravelLinear\Notifications\Messages\LinearIssue;

$issue = (new LinearIssue)
  ->title('Issue title')
  ->message('Issue message');

$user = User::first();
$user->notify(new NewLinearIssue($issue));

The LinearIssue message supports the following fluent methods:

(new LinearIssue)
  ->title('Issue title')        // required, the issue title
  ->message('Issue message')    // the issue description
  ->projectId('project-uuid')   // assign the issue to a Linear project
  ->label('Bug')                // attach a label to the issue
  ->submitter('Jane Doe')       // who submitted the issue (defaults to "Anonymous")
  ->attachment('/path/to/file') // add an attachment (call multiple times for more)
  ->issueModel($model);         // relate the issue to an Eloquent model

Using the notification channel

The NewLinearIssue notification routes through the package's LinearChannel and returns the LinearIssue message from its toLinear() method. Any notifiable that uses Laravel's Notifiable trait can send a Linear issue by calling $notifiable->notify(new NewLinearIssue($issue)) as shown above — no extra channel registration is required.

Change the settings

When you go to your-domain.test/linear/auth after you've connected to Linear you will be able to change the config.

Updating

When you install a new version of this package via Composer it might be helpful to run the update command so all the views and assets are up to date. This command will publish the latest assets for this package and publish new components if they are available.

php artisan linear:update

Linear

Here are some documentation pages from Linear that might be helpful.

https://developers.linear.app/docs/oauth/authentication https://developers.linear.app/docs/oauth/oauth-actor-authorization

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please report security vulnerabilities by email rather than via the public issue tracker.

Credits

• Stef van Esch
• Lars Kort
• All Contributors

License

The MIT License (MIT). Please see License File for more information.