README

从您的PHP应用程序中与mite进行交互。

• 要求
• 安装
• 用法
  • 基本API客户端
  • 简单API
  • 简单跟踪器
  • 捕获错误
  • 缓存HTTP请求
  • 创建自己的API客户端
• 许可证

要求

• 一个账户名（您mite账户域名的第一部分，例如在https://xxx.mite.de中）
• 一个API密钥（您可以在https://xxx.mite.de/myself上找到您的API密钥）

请注意，库的功能受使用的凭证权限的限制。例如，具有“时间跟踪器”角色的用户只能访问向他们提供的数据，并且不允许创建新客户。

具有admin角色的用户可以查看和做（几乎所有）任何事情。

安装

为了使用此库，您需要一个PSR-18 HTTP客户端和一个PSR-17 HTTP消息工厂。如果它们尚未在您的项目中可用，它们将被添加到您的项目依赖项中

composer require gamez/mite

用法

基本API客户端

一旦您已根据安装部分创建了一个HTTP客户端和请求工厂，您可以使用它们创建一个API客户端

<?php

use Gamez\Mite\Api\HttpApiClientFactory;

$apiClientFactory = new HttpApiClientFactory();

$apiClient = $apiClientFactory('my_account', 'api_key');

此API客户端允许您向mite账户的API发出经过身份验证的HTTP请求 - 有关您可以使用哪些端点的信息，请参阅mite的REST API文档

简单API

Gamez\Mite\SimpleApi是访问您mite账户中数据的最快、最简单的方式。其方法名称与可用的REST API端点相匹配，并且始终返回数据数组。您可以通过查看Gamez\Mite\SimpleApi类的源代码或使用您的IDE的自动完成功能来检查可用的方法。

简单API在访问mite API时不会妨碍您，但它也不提供额外的功能。例如，它不会告诉您是否使用了错误的查询参数或无效的字段值，因此您必须依赖返回的API响应。

有关允许哪些查询参数和字段值的更多信息，请参阅官方mite API文档

示例

use Gamez\Mite\SimpleApi;

/** 
 * @var \Gamez\Mite\Api\ApiClient $apiClient 
 */
$api = SimpleApi::withApiClient($apiClient);

$customer = $api->createCustomer([
    'name' => 'My new customer',
    'note' => 'He pays better than the old one',
]);

echo 'Customer: '.print_r($customer, true);

$project = $api->createProject([
    'name' => 'My new customer project',
    'customer_id' => $customer['id'],
    'budget_type' => 'minutes_per_month',
    'budget' => 6000,
    'hourly_rate' => 10000,
    'active_hourly_rate' => 'hourly_rate',
]);

echo 'Project: '.print_r($project, true);

$service = $api->createService([
    'name' => 'Customer Support',
]);

echo 'Service: '.print_r($service, true);

$user = current($api->getActiveUsers()); // For the sake of this example, we use the first available user

echo 'User: '.print_r($user, true);

$timeEntry = $api->createTimeEntry([
    'date_at' => 'today',
    'minutes' => 60,
    'user_id' => $user['id'], // Would we omit this, the authenticated user would be used
    'project_id' => $project['id'],
    'service_id' => $service['id'],
    'note' => 'We had some work to do, and we did some work.'
]);

echo 'Time Entry: '.print_r($timeEntry, true);

// $api->delete($newTimeEntry['id'];

$workdaysPerMonthAndUser = $api->getGroupedTimeEntries($groupBy = ['user'], ['at' => 'this_month']);

echo 'Workdays per month and user: '.print_r($workdaysPerMonthAndUser, true);

简单跟踪器

Gamez\Mite\SimpleTracker允许您使用mite的时间跟踪器。

注意：您只能访问当前已认证用户（通过使用的API密钥识别）的跟踪器。无法修改其他用户的跟踪器。

在追踪器上的每个操作都会返回一个包含追踪时间条目信息的数组，但你不必检查结果就知道操作是否成功——如果一个操作没有抛出错误，那么它就是成功的。

use Gamez\Mite\SimpleApi;
use Gamez\Mite\SimpleTracker;

/** @var \Gamez\Mite\Api\ApiClient $apiClient */
$api = SimpleApi::withApiClient($apiClient);
$tracker = SimpleTracker::withApiClient($apiClient);

$sleeping = $api->createTimeEntry(['note' => 'I am sleeping']);
$working = $api->createTimeEntry(['note' => 'I switch to this now and then']);

$tracker->start($sleeping['id']);
sleep(1); // You don't need this sleep, but the example makes more sense this way
$tracker->start($working['id']); // This will automatically stop the "sleeping" tracker
// No sleep this time, we'll just work for zero seconds 
$tracker->stop($working['id']); // We stopped working!

print_r($tracker->status()); // Sad

捕获错误

此库抛出的所有异常都实现了\Gamez\Mite\Exception\MiteException接口。在使用API客户端时抛出的异常将抛出\Gamez\Mite\Exception\ApiClientError。

use Gamez\Mite\Exception\ApiClientError;
use Gamez\Mite\Exception\MiteException;

try {
    /** @var \Gamez\Mite\Api\ApiClient $apiClient */
    $result = $apiClient->get('nice-try');
} catch (ApiClientError $e) {
    $message = "Something went wrong while accessing {$e->getRequest()->getUri()}";

    if ($response = $e->getResponse()) {
        $message .= " ({$response->getStatusCode()})";
    }

    $message .= ' : '.$e->getMessage();

    exit($message);
} catch (MiteException $e) {
    exit('Something not API related went really wrong: '.$e->getMessage());
}

// Something went wrong while accessing https://xxx.mite.de/nice-try (404) :
// The URI /nice-try could not be found.

缓存HTTP请求

要缓存API的HTTP请求，你可以在将其注入到API客户端实例之前，向HTTP客户端添加缓存中间件/插件。有关如何操作的说明，请参阅相应组件的文档。

• Guzzle: kevinrob/guzzle-cache-middleware
• HTTPlug: 缓存插件

创建自己的API客户端

如果你想创建自己的API客户端，请实现\Gamez\Mite\Api\ApiClient接口，并使用你的实现。

许可证

gamez/mite遵循MIT许可证。

你对mite的使用受mite服务条款的约束。