README

从您的PHP应用程序中与Personio交互。

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

要求

• Client ID和Client Secret（您可以在https://xxx.personio.de/configuration/api/credentials生成它们）

安装

为了使用此库，您需要一个PSR-18 HTTP客户端和一个PSR-17 HTTP消息工厂。

使用 kriswallsmith/buzz 和 nyholm/psr7 的示例

composer require kriswallsmith/buzz nyholm/psr7 gamez/personio

$requestFactory = new \Nyholm\Psr7\Factory\Psr17Factory();
$httpClient = new \Buzz\Client\FileGetContents($requestFactory);

使用 guzzlehttp/guzzle 和 laminas/laminas-diactoros 的示例

composer require guzzlehttp/guzzle laminas/laminas-diactoros gamez/personio

$requestFactory = new \Laminas\Diactoros\RequestFactory();
$httpClient = new \GuzzleHttp\Client();

使用

基本API客户端

根据安装部分所述创建HTTP客户端和请求工厂后，您可以使用它们创建API客户端

use Gamez\Personio\Api\HttpApiClient;

$clientId = 'xxx';
$clientSecret = 'xxx';

/**
 * @var \Psr\Http\Message\RequestFactoryInterface $requestFactory
 * @var \Psr\Http\Client\ClientInterface $httpClient
 */
$apiClient = HttpApiClient::with($clientId, $clientSecret, $httpClient, $requestFactory);

此API客户端允许您向Personio账户的API发出经过身份验证的HTTP请求 - 请参阅Personio的REST API文档以了解您可以使用哪些端点。

简单API

Gamez\Personio\SimpleApi 是访问Personio账户中数据的简单快捷方式。其方法命名与可用的REST API端点相对应，并返回数据数组。您可以通过查看Gamez\Personio\SimpleApi类的源代码或使用IDE的自动完成功能来检查可用的方法。

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

有关允许的查询参数和字段值的详细信息，请参阅Personio开发者中心。

捕获错误

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

<?php 

use Gamez\Personio\Exception\ApiClientError;
use Gamez\Personio\Exception\PersonioException;

try {
    /** @var \Gamez\Personio\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 (PersonioException $e) {
    exit('Something not API related went really wrong: '.$e->getMessage());
}

缓存HTTP请求

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

• Guzzle: kevinrob/guzzle-cache-middleware
• HTTPlug: Cache Plugin

创建自己的API客户端

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

许可证

gamez/personio使用MIT许可证。

您对Personio的使用受Personio服务条款的约束。