README

PHP 客户端库，用于访问 Springshare LibCal API。

入门指南

您可能希望首先查看来自 Springshare 帮助中心的 LibCal API 概述。此客户端使用 API v1.1 端点。

此软件包是为 PHP 7.4 及以上版本开发的。您应该使用 Composer 安装此软件包及其依赖项。例如

php composer.phar require bgsu-lits/libcal guzzlehttp/guzzle guzzlehttp/psr7 desarrolla2/cache

所需依赖项

PSR-18 HTTP 客户端

客户端需要一个 psr/http-client 的实现。此文档将使用 guzzlephp/guzzle 作为示例，但可以使用任何实现。

PSR-17 HTTP 工厂

客户端需要一个 psr/http-factory 的实现。此文档将使用 guzzlephp/psr7 作为示例，但可以使用任何实现。

PSR-7 HTTP 消息接口

客户端需要一个 psr/http-message 的实现。此文档将使用 guzzlephp/psr7 作为示例，但可以使用任何实现。

可选依赖项

PSR-16 Simple Cache

客户端可以使用一个 psr/simple-cache 的实现。此文档将使用 desarrolla2/cache 作为示例，但可以使用任何实现。

确定客户端凭据

主机

客户端的主机将是您的 LibCal 实例的主机名，例如 <institution>.libcal.com。例如，我们将使用 BGSU 的主机 bgsu.libcal.com。

客户端 ID 和密钥

访问您的 LibCal 实例的控制台，然后转到管理员 > API。选择 API 身份验证选项卡，并在应用程序部分下使用创建新应用程序按钮。您可以选择任何应用程序名称和描述，并勾选任何您希望客户端访问的权限范围。

创建应用程序后，您需要复制应用程序表中的客户端 ID 和客户端密钥列的值。例如，我们将使用客户端 ID 100 和客户端密钥 61483dcf150d97c921abbe1f8024eb2e。

实例化 API 客户端

现在您已经收集了依赖项和凭据，您可以实例化 API 客户端。以下是一个示例 PHP 文件，它将包含 Composer 的自动加载器并使用凭据和依赖项创建 API 客户端。此示例使用我们上面指定的示例，其中注释显示依赖项必须实现的接口。

<?php
require __DIR__ . '/vendor/autoload.php';

$client = new \Lits\LibCal\Client(
    'bgsu.libcal.com',
    '100',
    '61483dcf150d97c921abbe1f8024eb2e',
    new GuzzleHttp\Client(),           // Psr\Http\Client\ClientInterface
    new GuzzleHttp\Psr7\HttpFactory(), // Psr\Http\Message\RequestFactoryInterface
    new GuzzleHttp\Psr7\HttpFactory(), // Psr\Http\Message\StreamFactoryInterface
    new Desarrolla2\Cache\Memory()     // Psr\SimpleCache\CacheInterface
);

使用 API 客户端

有了实例化的 API 客户端，您可以通过流畅的方式访问 API 端点。例如，要访问 /space/locations 端点，您可以执行以下操作

$locations = $client->space()->locations()->send();

参数也可以添加，通常通过以 set 开头的方法。例如，/space/locations 端点同时具有 details 和 admin_only 参数。

$locations = $client->space()->locations()
    ->setDetails()
    ->setAdminOnly()
    ->send();

一些端点需要指定参数，通常是 ID。例如，使用 ID 为 100 访问 /space/item/:id。

$item = $client->space()->item(100)->send();

API 调用的结果将被映射到 Lits\LibCal\Data 类的 PHP 对象或对象数组。相应地，属性应可以从这些对象中以正确的格式访问。

如果端点需要通过 POST 传输数据，这些数据将指定在特定的有效负载对象中。这些对象可以由用户提交的 POST 数据创建。例如，使用 /space/reserve 端点来预定空间。

$_POST = [
    'start' => '2021-12-31T10:00:00-0400',
    'fname' => 'Freddie',
    'lname' => 'Falcon',
    'email' => 'ffalcon@bgsu.edu',
    'bookings' => [
        [
            'id' => 100,
            'to' => '2021-12-31T11:00:00-0400',
        ],
    ],
];

$data = new \Lits\LibCal\Data\Space\Reserve\PayloadReserveSpaceData
    ::fromArray($_POST);

$response = $client->space()->reserve($data)->send();

缓存结果

向 API 客户端提供 Simple Cache 客户端是可选的。如果提供，它将始终用于缓存经过身份验证的会话。然后它还可以用于缓存大多数 GET 端点的结果。这可以通过在这些端点在 send() 之前调用 cache() 方法来实现。

$locations = $client->space()->locations()->cache()->send();

建议查阅您 Simple Cache 客户端的文档，了解如何最好地设置缓存以在进程之间保留条目。

限制

此客户端当前仅实现了位于 /space 下的 Spaces/Seats 端点。

开发

此客户端由 Bowling Green State University 图书馆信息技术服务部门开发。代码遵循 MIT 许可。问题可以通过 GitHub 项目报告。

也欢迎贡献，最好是通过 pull request。在提交更改之前，请通过 Composer 运行 test 命令（php composer.phar test）以检查代码是否符合项目标准。

bgsu-lits / libcal

维护者

详细信息