Download the PHP package spinen/laravel-clickup without Composer

SPINEN's Laravel ClickUp

PHP package to interface with ClickUp. We strongly encourage you to review ClickUp's API docs to get a feel for what this package can do, as we are just wrapping their API.

We solely use Laravel for our applications, so this package is written with Laravel in mind. We have tried to make it work outside of Laravel. If there is a request from the community to split this package into 2 parts, then we will consider doing that work.

Build Status

Branch	Status	Coverage	Code Quality
Develop
Master

Table of Contents

• Installation
• Laravel Setup
  • Configuration
    • Optional Keys
• Generic PHP Setup
  • Examples
• Authentication
  • OAuth
  • Personal Token
• Usage
  • Supported Actions
  • Using the Client
    • Getting the Client object
    • Models
    • Relationships
    • Advanced filtering using "where"
  • More Examples
• Known Issues

Installation

Install ClickUp PHP Package via Composer:

The package uses the auto registration feature of Laravel.

Laravel Setup

Configuration

1. You will need to make your User object implement includes the Spinen\ClickUp\Concerns\HasClickUp trait which will allow it to access the Client as an attribute like this: $user->clickup

2. Add the appropriate values to your file

   Optional Keys

3. [Optional] Publish config & migration

   Config

   A configuration file named can be published to by running...

   Migration

   Migrations files can be published by running...

   You'll need the migration to set the ClickUp API token on your User model.

Generic PHP Setup

Examples

To get a Spinen\ClickUp\Api\Client instance...

The $clickup instance will work exactly like all of the examples below, so if you are not using Laravel, then you can use the package once you bootstrap the client.

Authentication

ClickUp has 2 ways to authenticate when making API calls... 1) OAuth token or 2) Personal Token. Either method uses a token that is saved to the clickup_token property on the User model.

OAuth

There is a middleware named clickup that you can apply to any route that verifies that the user has a clickup_token, and if the user does not, then it redirects the user to ClickUp's OAuth page with the client_id where the user selects the team(s) to link with your application. Upon selecting the team(s), the user is redirected to /clickup/sso/<user_id>?code=<OAuth Code> where the system converts the code to a token & saves it to the user. Upon saving the clickup_token, the user is redirected to the initial page that was protected by the middleware.

NOTE: You will need to have the auth middleware on the routes as the User is needed to see if there is a clickup_token.

If you do not want to use the clickup middleware to start the OAuth flow, then you can use the oauthUri on the Client to generate the link for the user...

NOTE: At this time, there is not a way to remove a token that has been invalidated, so you will need to delete the clickup_token on the user to restart the flow.

Personal Token

If you do not want to use the OAuth flow, then you can allow the user to provide you a personal token that you can save on the User.

Usage

Supported Actions

The primary class is Spinen\ClickUp\Client. It gets constructed with 3 parameters...

• array $configs - Configuration properties. See the clickup.php file in the ./config directory for a documented list of options.

• Guzzle $guzzle - Instance of GuzzleHttp\Client

• Token $token - [Optional] String of the user's token

Once you new up a Client instance, you have the following methods...

• delete($path) - Shortcut to the request() method with 'DELETE' as the last parameter

• get($path) - Shortcut to the request() method with 'GET' as the last parameter

• oauthRequestTokenUsingCode($code) - Request a token from the OAuth code

• oauthUri($url) - Build the URI to the OAuth page with the redirect_url set to $url

• post($path, array $data) - Shortcut to the request() method with 'POST' as the last parameter

• put($path, array $data) - Shortcut to the request() method with 'PUT' as the last parameter

• request($path, $data = [], $method = 'GET') - Make an API call to ClickUp to $path with the $data using the JWT for the logged in user.

• setConfigs(array $configs) - Allow overriding the $configs on the Client instance.

• setToken($token) - Set the token for the ClickUp API

• uri($path = null, $url = null) - Generate a full uri for the path to the ClickUp API.

Using the Client

The Client is meant to emulate Laravel's models with Eloquent. When working with ClickUp resources, you can access properties and relationships just like you would in Laravel.

Getting the Client object

By running the migration included in this package, your User class will have a clickup_token column on it. When you set the user's token, it is encrypted in your database with Laravel's encryption methods. After setting the ClickUp API token, you can access the Client object through $user->clickup.

Models

The API responses are cast into models with the properties cast into the types as defined in the ClickUp API documentation. You can review the models in the src/ folder. There is a property named casts on each model that instructs the Client on how to cast the properties from the API response. If the casts property is empty, then the properties are not defined in the API docs, so an array is returned.

Relationships

Some of the responses have links to the related resources. If a property has a relationship, you can call it as a method and the additional calls are automatically made & returned. The value is stored in place of the original data, so once it is loaded it is cached.

You may also call these relationships as attributes, and the Client will return a Collection for you (just like Eloquent).

Advanced filtering using "where"

You can do advanced filters by using where on the models

NOTE: The API has a page size of 100 records, so to get to the next page you use the where method...

More Examples

Known Issues

// TODO: Document known issues as we find them