README

Time Doctor 的 PHP API 客户端

了解有关 Time Doctor API 的更多信息，请访问 timedoctor.com

use SudiptoChoudhury\TimeDoctor\Api;

$td = new Api([
    'access_token' => '<<access_token>>'
]);


$result = $td->getCompanies(); 

$result = $td->getWorklogs([
    'company_id' => '2348758',
    "start_date" => '2020-08-16',
    'end_date' => '2020-08-31'
]);
 

安装

要求

• 任何 PHP 7.1+ 版本都适用

使用 Composer 安装

您可以通过向您的 composer.json 文件的 require 块中添加以下行来安装库（将 dev-master 替换为最新稳定版本）

"sudiptochoudhury/php-time-doctor": "dev-master"

或者运行以下命令

composer require sudiptochoudhury/php-time-doctor

设置

验证

在实现此功能时，您可以选择以下两种 OAuth2.0 策略之一。

在此之前，您需要按照此处所述注册您的 Time Doctor 应用程序，设置 redirect_url 并从应用程序中获取 client_id、client_secret。

对于基于 Web 服务器的/桌面应用程序/原生应用程序

授权代码授予流：如果您有自己的服务器用于应用程序（对于传统 Web 应用程序以及原生桌面和移动应用程序来说最常见），则此流程非常有用。

第一步 - 获取代码

use SudiptoChoudhury\TimeDoctor\OAuth;

$tdOAuth = new OAuth();
$tdOAuth->getAuthCode([
    'client_id' => '', // pass your client_id here 
    'redirect_uri' => '' // set your redirect_url here
]);

这将打开您的 Time Doctor 应用程序的认证门户，并在认证成功后重定向到指定的 redirect_url（您的应用程序的主应用程序的 URL）（前提是此 URL 已在您的 Time Doctor 应用程序中注册），并在其查询字符串中包含一个 code。

您的站点代码应收集并存储此代码以供下一步使用。

第二步 - 生成 access_token

use SudiptoChoudhury\TimeDoctor\OAuth;

$tdOAuth = new OAuth();
$tdOAuth->getToken([
    'client_id' => '',  // pass your client_id here 
    'client_secret' => '',  // pass your client_secret here 
    'redirect_uri' => '', // pass your redirect_url here 
    'code' => '' // set here the code you received in Step 1 stated above
]);

您将收到一组类似于以下给出的值

{
    "access_token": "342019_MGQ1MjNiNDEzNzJmMGEzNDgyYWY3M2QA2YTZimjY3ZTFFYzBhNTAxMjEyMjM0MmMwMTFiOWJjOZzZ2NiZDMzMQ",
    "expires_in": 432000,
    "token_type": "bearer",
    "scope": null,
    "refresh_token": "342019_MjQyN2U4ZQAxMzA4ZjRlQTExNGMzQDMzZmQlZjM0QTQwMQU1OTdQNjI0OQNlZDlmNmJiOXZkNWRjOTc3N2YjNg"
}

存储 access_token 和 refresh_token 以供将来使用。

access_token 将在所有 Time Doctor API 调用中需要，而 refresh_token 将在访问令牌过期时需要重新生成访问令牌。 access_token 的有效期为有限时间，如接收数据的 expires_in（以秒为单位）属性所示。上面示例数据中的 expires_in 计算为 5 天。

下面的步骤显示了如何在过期后重新生成 access_token。

使用刷新令牌检索访问令牌过期

use SudiptoChoudhury\TimeDoctor\OAuth;

$tdOAuth = new OAuth();
$tdOAuth->refreshToken([
    'client_id' => '',  // pass your client_id here 
    'client_secret' => '', // set your client_secret here
    'refresh_token' => '' // set your refresh_token here
]);

对于无服务器 Web 应用程序

显式授权流：如果您没有自己的服务器用于应用程序，则非常有用（适用于浏览器中的 Web 应用程序，例如无法对我们公开 API 进行任意 GET 请求的单站点应用程序）。

use SudiptoChoudhury\TimeDoctor\OAuth;

$tdOAuth = new OAuth();
$tdOAuth->getAuthToken([
    'client_id' => '', // pass your client_id here      
    'redirect_uri' => '' // pass your redirect_url here 
]);

使用

您需要做的所有事情就是将 TimeDoctor access_token 传递给构造函数。

use SudiptoChoudhury\TimeDoctor\Api;

new Api([
    'access_token' => '<<access_token>>',
]);

此外，您可以通过 log 属性设置记录器。

• 您可以将记录设置为 false 以禁用记录。
• 您还可以传递一个包含 file 和 path 属性的数组。

use SudiptoChoudhury\TimeDoctor\Api;

new Api([
    'access_token' => '<<access_token>>',
    'log' => ['file' => 'TimeDoctor.log', 'path' => '/your/log/path']
]);

• 您还可以传递一个 Monolog\Logger 实例。

use SudiptoChoudhury\TimeDoctor\Api;

new Api([
    'access_token' => '<<access_token>>',
    'log' => ['logger' => $monologInstance]
]);

您可以使用 client 属性将其传递给 GuzzleHttp\Client 构造函数。

use SudiptoChoudhury\TimeDoctor\Api;

new Api([
    'access_token' => '<<access_token>>',
    'client' => ['timeout' => 5]
]);

如果您想访问请求和响应处理程序堆栈，请使用 settings 而不是使用 client 的 handlers 属性。

'settings' => [
    'responseHandler' => function (ResponseInterface $response) {
        // do something
        return $response;
    },
    'requestHandler' => function (RequestInterface $request) {
        // some action
        return $request;
    },
],

如何使用

接下来，调用下表中给出的所需方法。在大多数方法中，您可能需要传递参数。参数应以关联数组的形式传递。

示例

use SudiptoChoudhury\TimeDoctor\Api;

$td = new Api([
    'access_token' => '<<access_token>>'
]);


$result = $td->getCompanies(); 

$result = $td->getWorklogs([
    'company_id' => '2348758',
    "start_date" => '2020-08-16',
    'end_date' => '2020-08-31'
]);

 

可用 API 方法

可用 OAuth API 方法