README

这是一个用 Crossref REST API 编写的 PHP 库。

简介

这 **不是** 一个官方库！本库的目的是提供一种简单的方式，以便向 CrossRef 的 REST API 发送请求。您 **应该** 与官方文档结合阅读。

突出功能

您无需担心发送 HTTP 请求；
如果发生 HTTP 错误，则会抛出适当的异常；
您将直接收到响应，而无需额外的封装；
如果需要，过滤和分面参数会被编码；
您可以轻松缓存响应；
如果您标识自己，则可以享受更好的服务；
您可以将您的应用程序绑定到 API 的特定大版本；
您的应用程序符合速率限制（如果配置了缓存，则效果更佳）。

库摘要

class RenanBr\CrossRefClient
{
    // Returns JSON decoded as array
    public function request($path, array $parameters = []);

    // Returns boolean
    public function exists($path);

    public function setUserAgent($userAgent);
    public function setCache(Psr\SimpleCache\CacheInterface $cache);
    public function setVersion($version);
}

安装

composer require renanbr/crossref-client ^1

用法

单例

单例是单个结果。检索特定标识符（例如 DOI、ISSN、funder_identifier）的元数据通常返回单例结果。

见：https://github.com/CrossRef/rest-api-doc#singletons

require __DIR__ . '/vendor/autoload.php';
$client = new RenanBr\CrossRefClient();
$work = $client->request('works/10.1037/0003-066X.59.1.29');
print_r($work);

上述示例将输出

Array
(
    [status] => ok
    [message-type] => work
    [message-version] => 1.0.0
    [message] => Array
        (
            ...

            [DOI] => 10.1037/0003-066x.59.1.29
            [type] => journal-article

            ...

            [title] => Array
                (
                    [0] => How the Mind Hurts and Heals the Body.
                )

            ...
        )
)

确定单例的存在性

(...) [您] 可以确定单例的 "存在性"。这种技术的优点是它非常快，因为它不会返回任何元数据 (...)

见：https://github.com/CrossRef/rest-api-doc#headers-only

require __DIR__ . '/vendor/autoload.php';
$client = new RenanBr\CrossRefClient();
$exists = $client->exists('members/98');
var_dump($exists);

上述示例将输出

bool(true)

列表

列表结果可以包含多个条目。搜索或过滤通常返回列表结果。

列表有两部分：摘要和条目。通常，API 列表结果会返回这两者。

见：https://github.com/CrossRef/rest-api-doc#lists

require __DIR__ . '/vendor/autoload.php';
$client = new RenanBr\CrossRefClient();

$parameters = [
    'query' => 'global state',
    'filter' => [
        'has-orcid' => true,
    ],
];
$result = $client->request('works', $parameters);

foreach ($result['message']['items'] as $work) {
    // ...
}

配置

缓存结果

缓存数据，这样您就不必反复请求相同的数据。

见：https://github.com/CrossRef/rest-api-doc#etiquette

require __DIR__ . '/vendor/autoload.php';
$client = new RenanBr\CrossRefClient();
$client->setCache(new voku\cache\CachePsr16());

// ...

上述示例使用 voku/simple-cache 作为缓存实现，但您可以使用任何 PSR-16 实现，因为 setCache() 接受 Psr\SimpleCache\CacheInterface 作为参数。

识别您的脚本

截至2017年9月18日，所有使用HTTPS且包含适当联系信息的API查询将被定向到专门用于礼貌用户的API机器池。

参阅： https://github.com/CrossRef/rest-api-doc#good-manners--more-reliable-service

require __DIR__ . '/vendor/autoload.php';
$client = new RenanBr\CrossRefClient();
$client->setUserAgent('GroovyBib/1.1 (https://example.org/GroovyBib/; mailto:GroovyBib@example.org)');

// ...

上述示例使所有后续请求都附加了提供的联系信息。

绑定到特定的大版本

如果您需要将您的实现与API的特定主要版本绑定，可以通过使用特定版本的路径来实现。默认路径将重定向到API的最新版本。

参阅： https://github.com/CrossRef/rest-api-doc#how-to-manage-api-versions

require __DIR__ . '/vendor/autoload.php';
$client = new RenanBr\CrossRefClient();
$client->setVersion('v55');

// ...

上述示例将所有后续请求绑定到API版本 v55。

速率限制

默认情况下，此库符合API对当前执行的速率限制。

如果您想在多个执行中保持此行为，您必须配置缓存，如上所述。

处理错误

由于此库内部使用guzzlehttp/guzzle。请参阅Guzzle异常文档了解如何正确处理异常。

renanbr / crossref-client

维护者

详细信息