README

这个库是 PHP 5.4 对 Discogs API v2.0 的实现。[Discogs API](http://www.discogs.com/developers/index.html) 是一个基于 REST 的接口。通过使用这个库，你不需要担心与 API 进行通信：所有困难的工作都已经完成了。

此 API 是建立在巨人肩膀上的：[Guzzle 4.0](http://guzzle.readthedocs.org/en/latest/)。这是一个绝对出色的库。

已弃用

此仓库已过时，不再维护。请参阅 [https://github.com/calliostro/php-discogs-api](https://github.com/calliostro/php-discogs-api) 以获取更新的版本。

许可证

此库以 MIT 许可证发布。有关完整许可证，请参阅 LICENSE 文件。

安装

首先 安装 composer。接下来做

$ composer require ricbra/php-discogs-api

要求

PHP >=5.4.0

用法

创建一个新的实例非常简单

<?php
$client = Discogs\ClientFactory::factory([]);

用户代理

Discogs 需要您提供一个用户代理。您可以轻松地这样做

<?php
$client = Discogs\ClientFactory::factory([
    'defaults' => [
        'headers' => ['User-Agent' => 'your-app-name/0.1 +https://www.awesomesite.com'],
    ]
]);

节流

Discogs 不喜欢您以过高的连接速率调用其 API。使用 ThrottleSubscriber 以防止出现错误或被禁止

<?php

$client = Discogs\ClientFactory::factory();
$client->getHttpClient()->getEmitter()->attach(new Discogs\Subscriber\ThrottleSubscriber());

认证

Discogs API 允许使用简单的 Discogs Auth 流 或更高级的（更复杂的）OAuth 流 访问受保护的端点

Discogs 认证

如 Discogs 认证文档所述

为了访问受保护的端点，您需要根据您的具体情况注册消费者密钥和密钥或用户令牌

• 要轻松访问您自己的用户账户信息，请使用 用户令牌。
• 要获取访问需要认证的端点的权限以及构建第三方应用程序，请使用 消费者密钥和密钥。

使用 Discogs Php API，您可以通过向您的默认值添加一个 query 键将您的凭据添加到每个请求中，如下所示

$client = ClientFactory::factory([
    'defaults' => [
        'query' => [
            'key' => 'my-key',
            'secret' => 'my-secret',
        ],
    ]
]);

OAuth

有很多端点需要OAuth认证。幸运的是，使用Guzzle这简直是小菜一碟。如果你在获取token和token_secret时遇到麻烦，请查看我的示例实现。

<?php

$client = Discogs\ClientFactory::factory([]);
$oauth = new GuzzleHttp\Subscriber\Oauth\Oauth1([
    'consumer_key'    => $consumerKey, // from Discogs developer page
    'consumer_secret' => $consumerSecret, // from Discogs developer page
    'token'           => $token['oauth_token'], // get this using a OAuth library
    'token_secret'    => $token['oauth_token_secret'] // get this using a OAuth library
]);
$client->getHttpClient()->getEmitter()->attach($oauth);

$response = $client->search([
    'q' => 'searchstring'
]);

历史

另一个酷炫的插件是历史插件

<?php

$client = Discogs\ClientFactory::factory([]);
$history = new GuzzleHttp\Subscriber\History();
$client->getHttpClient()->getEmitter()->attach($history);

$response = $client->search([
    'q' => 'searchstring'
]);

foreach ($history as $row) {
    print (string) $row['request'];
    print (string) $row['response'];
}

更多信息及插件

有关Guzzle及其插件的信息，请查阅文档。

执行搜索

截至2014年8月，此端点需要签名的OAuth请求。

<?php

$response = $client->search([
    'q' => 'Meagashira'
]);
// Loop through results
foreach ($response['results'] as $result) {
    var_dump($result['title']);
}
// Pagination data
var_dump($response['pagination']);

// Dump all data
var_dump($response->toArray());

获取标签信息

<?php

$label = $service->getLabel([
    'id' => 1
]);

获取艺术家信息

<?php

$artist = $service->getArtist([
    'id' => 1
]);

获取发行信息

<?php

$release = $service->getRelease([
    'id' => 1
]);

echo $release['title']."\n";

获取主发行信息

<?php

$master  = $service->getMaster([
    'id' => 1
]);

echo $master['title']."\n";

获取图像

Discogs返回图像的完整URL，所以只需使用内部客户端即可获取这些图像

php

$release = $client->getRelease([
    'id' => 1
]);
foreach ($release['images'] as $image) {
    $response = $client->getHttpClient()->get($image['uri']);
    // response code
    echo $response->getStatusCode();
    // image blob itself
    echo $client->getHttpClient()->get($image['uri'])->getBody()->getContents();
}

用户收藏夹

当folder_id不为0时需要授权。

获取收藏夹目录

<?php

$folders = $service->getCollectionFolders([
    'username' => 'example'
]);

获取收藏夹目录

<?php

$folder = $service->getCollectionFolder([
    'username' => 'example',
    'folder_id' => 1
]);

通过目录获取收藏夹项目

<?php

$items = $service->getCollectionItemsByFolder([
    'username' => 'example',
    'folder_id' => 3
]);

文档

更详细的文档可以在Discogs API v2.0 文档中找到。

贡献

实现了缺失的调用？欢迎PR！