README

PHP 包，用于与 ClickUp 接口。我们强烈建议您查阅 ClickUp 的 API 文档，了解本包的功能，因为我们只是封装了他们的 API。

我们仅使用 Laravel 来构建我们的应用程序，因此本包是用 Laravel 编写的。我们已尽力使其在 Laravel 之外也能使用。如果社区有将此包拆分为两部分的要求，我们将考虑完成这项工作。

构建状态

安装

通过 Composer 安装 ClickUp PHP 包

$ composer require spinen/laravel-clickup

本包使用 Laravel 的自动注册功能。

Laravel 设置

配置

您需要让您的 User 对象实现 Spinen\ClickUp\Concerns\HasClickUp 特性，这将允许它像这样访问客户端：$user->clickup

<?php

namespace App;

use Illuminate\Contracts\Auth\MustVerifyEmail;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Spinen\ClickUp\Concerns\HasClickUp;

class User extends Authenticatable
{
    use HasClickUp, Notifiable;

    // ...
}

将适当的值添加到您的 .env 文件中

可选密钥

CLICKUP_CLIENT_ID=<Application ID, if using OAuth to generate user tokens>
CLICKUP_CLIENT_SECRET=<Application Secret, if using OAuth to generate user tokens>
CLICKUP_OAUTH_URL=<url to clickup OAuth flow, default is v2>
CLICKUP_URL=<url to clickup API, default is v2>

[可选] 发布配置和迁移

配置

可以运行以下命令将名为 clickup.php 的配置文件发布到 config/ 目录...
```
php artisan vendor:publish --tag=clickup-config
```
迁移

可以运行以下命令将迁移文件发布...
```
php artisan vendor:publish --tag=clickup-migrations
```
您需要迁移来在您的 User 模型上设置 ClickUp API 令牌。

通用的 PHP 设置

示例

要获取 Spinen\ClickUp\Api\Client 实例...

$ psysh
Psy Shell v0.9.9 (PHP 7.3.11 — cli) by Justin Hileman
>>> $configs = [
     "oauth" => [
       "id" => "<client_id>", // if using OAuth
       "secret" => "<client_secret>", // If using OAuth
       "url" => "https://app.clickup.com/api",
     ],
     "route" => [
       "enabled" => true,
       "middleware" => [
         "web",
       ],
       "sso" => "clickup/sso",
     ],
     "url" => "https://api.clickup.com/api/v2",
   ];
>>> $guzzle = new GuzzleHttp\Client();
=> GuzzleHttp\Client {#2379}
>>> $clickup = new Spinen\ClickUp\Api\Client($configs, $guzzle) // Optionally, pass the token as 3rd parameter
=> Spinen\ClickUp\Api\Client {#2363}
>>> $clickup->setToken('<a token>') // Skip if passed in via constructor
=> Spinen\ClickUp\Api\Client {#2363}

$clickup 实例将像以下所有示例那样工作，因此如果您不使用 Laravel，则可以在启动客户端后使用该包。

身份验证

ClickUp 在进行 API 调用时有两种身份验证方式... 1) OAuth 令牌或 2) 个人令牌。两种方法都使用一个保存在 User 模型上的 clickup_token 属性的令牌。

OAuth

有一个名为 clickup 的中间件，可以应用于任何路由，以验证用户是否有 clickup_token，如果没有，则将用户重定向到 ClickUp 的 OAuth 页面，其中用户可以选择与您的应用程序链接的团队。选择团队后，用户将被重定向到 /clickup/sso/<user_id>?code=<OAuth Code>，系统将把 code 转换为令牌并将其保存到用户。保存 clickup_token 后，用户将被重定向到中间件保护的初始页面。

注意：您需要在路由上具有 auth 中间件，因为需要 User 来查看是否有 clickup_token。

如果您不想使用 clickup 中间件来启动 OAuth 流程，则可以使用 Client 上的 oauthUri 生成用户的链接...

$ php artisan tinker
Psy Shell v0.9.9 (PHP 7.3.11 — cli) by Justin Hileman
>>> $clickup = app(Spinen\ClickUp\Api\Client::class)
=> Spinen\ClickUp\Api\Client {#3035}
>>> $clickup->oauthUri(route('clickup.sso.redirect_url', <user_id>))
=> "https://app.clickup.com/api?client_id=<client_id>&redirect_uri=https%3A%2F%2F<your.host>2Fclickup%2Fsso%2F<user_id>"
>>>

注意：目前没有一种方法可以删除已失效的令牌，因此您需要删除用户的clickup_token以重新启动流程。

个人令牌

如果您不想使用OAuth流程，则可以允许用户向您提供一个个人令牌，您可以在User上保存它。

$ php artisan tinker
Psy Shell v0.9.9 (PHP 7.3.11 — cli) by Justin Hileman
>>> $user = App\User::find(1)
=> App\User {#3040
     id: 1,
     first_name: "Bob",
     last_name: "Tester",
     email: "bob.tester@example.com",
     email_verified_at: null,
     created_at: "2019-11-15 19:49:01",
     updated_at: "2019-11-15 19:49:01",
     logged_in_at: "2019-11-15 19:49:01",
     deleted_at: null,
   }
>>> $user->clickup_token = '<personal token>';
=> "<personal token>"
>>> $user->save()
=> true

使用方法

支持的操作

主要类是Spinen\ClickUp\Client。它使用3个参数进行构造...

array $configs - 配置属性。请参阅./config目录中的clickup.php文件以获取选项的文档列表。
Guzzle $guzzle - GuzzleHttp\Client的实例
Token $token - [可选] 用户令牌的字符串

一旦创建了一个Client实例，您就有以下方法...

delete($path) - 以'DELETE'作为最后一个参数的request()方法的快捷方式
get($path) - 以'GET'作为最后一个参数的request()方法的快捷方式
oauthRequestTokenUsingCode($code) - 使用OAuth代码请求令牌
oauthUri($url) - 使用$url作为重定向URL构建OAuth页面的URI
post($path, array $data) - 以'POST'作为最后一个参数的request()方法的快捷方式
put($path, array $data) - 以'PUT'作为最后一个参数的request()方法的快捷方式
request($path, $data = [], $method = 'GET') - 使用登录用户的JWT对$path进行API调用，并使用$data
setConfigs(array $configs) - 允许在Client实例上覆盖$configs
setToken($token) - 设置ClickUp API的令牌
uri($path = null, $url = null) - 为ClickUp API的路径生成完整的URI。

使用客户端

Client旨在模拟Laravel的Eloquent模型。当与ClickUp资源一起工作时，您可以像在Laravel中一样访问属性和关系。

获取客户端对象

通过运行此包中包含的迁移，您的User类将有一个clickup_token列。当您设置用户的令牌时，它将使用Laravel的加密方法在您的数据库中进行加密。设置ClickUp API令牌后，您可以通过$user->clickup访问Client对象。

$ php artisan tinker
Psy Shell v0.9.9 (PHP 7.2.19 — cli) by Justin Hileman
>>> $user = User::find(1);
=> App\User {#3631
     id: 1,
     first_name: "Bob",
     last_name: "Tester",
     email: "bob.tester@example.com",
     email_verified_at: null,
     created_at: "2019-11-15 19:49:01",
     updated_at: "2019-11-15 19:49:01",
     logged_in_at: "2019-11-15 19:49:01",
     deleted_at: null,
   }
>>> // NOTE: Must have a clickup_token via one of the 2 ways in the Authentication section
>>> $user->clickup;
=> Spinen\ClickUp\Api\Client {#3635}

模型

API响应被转换为模型，属性被转换为在ClickUp API文档中定义的类型。您可以在src/文件夹中查看模型。每个模型都有一个名为casts的属性，指示Client如何将API响应中的属性转换为类型。如果casts属性为空，则属性未在API文档中定义，因此返回一个数组。

>>> $team = $user->clickUp()->teams->first();
=> Spinen\ClickUp\Team {#3646
     +exists: true,
     +incrementing: false,
     +parentModel: null,
     +timestamps: false,
   }
>>> $team->toArray(); // Calling toArray() is allowed just like in Laravel
=> [
     "id" => <7 digit ClickUp ID>,
     "name" => "SPINEN",
     "color" => "#2980B9",
     "avatar" => <URL to avatar>,
     "members" => [
       [
    // Keeps going

关系

一些响应有相关资源的链接。如果属性有关系，您可以将其作为方法调用，并且会自动进行额外的调用并返回。值存储在原始数据的位置，因此一旦加载就会缓存。

$folder = $team->spaces->first()->folders->first();
=> Spinen\ClickUp\Folder {#3632
     +exists: true,
     +incrementing: false,
     +parentModel: Spinen\ClickUp\Space {#3658
       +exists: true,
       +incrementing: false,
       +parentModel: Spinen\ClickUp\Team {#3645
         +exists: true,
         +incrementing: false,
         +parentModel: null,
         +timestamps: false,
       },
       +timestamps: false,
     },
     +timestamps: false,
   }
>>> $folder->lists->count();
=> 5
>>> $folder->lists->first()->name;
=> "Test Folder"

您也可以将这些关系作为属性调用，Client将为您返回一个Collection（就像Eloquent一样）。

>>> $folder->lists;
=> Spinen\ClickUp\Support\Collection {#3650
     all: [
       Spinen\ClickUp\TaskList {#3636
         +exists: true,
         +incrementing: false,
         +parentModel: Spinen\ClickUp\Space {#3658
           +exists: true,
           +incrementing: false,
           +parentModel: Spinen\ClickUp\Team {#3645
             +exists: true,
             +incrementing: false,
             +parentModel: null,
             +timestamps: false,
           },
           +timestamps: false,
         },
         +timestamps: false,
       },
       // Keeps going

使用 "where" 进行高级筛选

您可以使用模型上的where进行高级筛选

>>> $team->tasks()->where('space_ids', ['space_id_1', 'space_id_2'])->where('assignees', ['assignee1', 'assignee2'])->get()->count();
=> 100
// If there are more than 100 results, they will be paginated. Pass in another parameter to get another page:
>>> $team->tasks()->where....->where('page', 2)->get();

注意：API的页面大小为100条记录，因此要获取下一页，您使用where方法... ->where('page', 3)

已知问题

// TODO：找到已知问题后记录

spinen / laravel-clickup

维护者

详细信息