README

这个库是 Discogs API v2.0 的 PHP 7.3 / PHP 8.x 实现。Discogs API 是一个基于 REST 的接口。使用这个库，您无需担心与 API 的通信：所有困难的工作已经完成。

许可证

这个库是在 MIT 许可证下发布的。请参阅 LICENSE 文件中的完整许可证。

Symfony Bundle

有关将 Discogs 集成到 Symfony 5 或 Symfony 6 的信息，请参阅 calliostro/discogs-bundle。

安装

首先 安装 composer。然后

$ composer require prhl2375/php-discogs-api

需求

PHP 7.3 或 PHP 8.x

使用

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

<?php

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

User-Agent

Discogs 要求您提供 User-Agent。您可以通过以下方式轻松实现

<?php

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

节流

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

<?php

$handler = \GuzzleHttp\HandlerStack::create();
$throttle = new Discogs\Subscriber\ThrottleSubscriber();
$handler->push(\GuzzleHttp\Middleware::retry($throttle->decider(), $throttle->delay()));

$client = Discogs\ClientFactory::factory(['handler'=>$handler]);

身份验证

Discogs API 允许您使用简单的 Discogs Auth Flow 或更复杂（更复杂）的 Oauth Flow 访问受保护的端点

Discogs 身份验证

如 Discogs 身份验证文档所述

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

• 要轻松访问您自己的用户账户信息，请使用 用户令牌。
• 要访问需要身份验证的端点并构建第三方应用程序，请使用 消费者密钥和密钥。

使用 Authorization 标头

$client = ClientFactory::factory([
    'headers' => [
        'Authorization' => "Discogs key=key_here, secret=secret_here",
    ],
]);

使用个人访问令牌进行身份验证（您可以从 https://www.discogs.com/settings/developers 获取）

$client = ClientFactory::factory([
    'headers' => [
        'User-Agent' => $user_agent,
        'Authorization' => "Discogs token={$access_token}",
    ]
]);

OAuth

有很多端点需要 OAuth。幸运的是，使用 Guzzle 这很容易。如果您在获取令牌和令牌密钥方面遇到困难，请查看 ricbra/php-discogs-api-example。

<?php

$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
]);
$handler = GuzzleHttp\HandlerStack::create();
$handler->push($oauth);
$client = Discogs\ClientFactory::factory([
    'handler' => $handler,
    'auth' => 'oauth'
]);

历史

另一个很酷的插件是 History 插件

<?php

$container = [];
$history = GuzzleHttp\Middleware::History($container);
$handler = GuzzleHttp\HandlerStack::create();
$handler->push($history);
$client = Discogs\ClientFactory::factory([ 
    'handler' => $handler
]);

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

foreach ($container as $row) {
    print $row['request'] -> getMethod(); // GET
    print $row['request'] -> getRequestTarget(); // /database/search?q=searchstring
    print strval($row['request'] -> getUri()); // https://api.discogs.com/database/search?q=searchstring
    print $row['response'] -> getStatusCode(); // 200
    print $row['response'] -> getReasonPhrase(); // OK
}

更多信息及插件

有关 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 = $client->getLabel([
    'id' => 1
]);

获取艺术家信息

<?php

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

获取发行信息

<?php

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

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

获取主发行信息

<?php

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

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

获取图像

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

$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();
}

用户列表

获取用户列表

<?php

$userLists = $client->getUserLists([
    'username' => 'example',
    'page' => 1, #default
    'per_page' => 500 #min 1, max 500, default 50
]);

获取用户列表项

<?php

$listItems = $client->getLists([
    'list_id' => 1
]);

获取用户愿望清单

<?php

$wantlist = $client->getWantlist([
    'username' => 'example',
    'page' => 1, #default
    'per_page' => 500 #min 1, max 500, default 50
]);

用户收藏

当 folder_id 不为 0 时，需要授权。

获取收藏夹

<?php

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

获取收藏夹

<?php

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

通过文件夹获取收藏夹项

<?php

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

列表

创建和操作列表需要您作为卖家进行身份验证

创建列表

<?php

$response = $client->createListing([
    'release_id' => '1',
    'condition' => 'Good (G)',
    'price' => 3.49,
    'status' => 'For Sale'
]);

修改列表

<?php

$response = $client->changeListing([
    'listing_id' => '123',
    'condition' => 'Good (G)',
    'price' => 3.49,
]);

删除列表

<?php

$response = $client->deleteListing(['listing_id' => '123']);

批量创建列表（通过CSV）

<?php
$response = $client->addInventory(['upload' => fopen('path/to/file.csv', 'r')]);

// CSV format (example): 
// release_id,condition,price
// 1,Mint (M),19.99
// 2,Near Mint (NM or M-),14.99

批量删除列表（通过CSV）

<?php
$response = $client->deleteInventory(['upload' => fopen('path/to/file.csv', 'r')]);

// CSV format (example): 
// listing_id
// 123
// 213
// 321

文档

更多文档可在Discogs API v2.0 文档中找到。

贡献

实现了缺失的功能？您可以提出请求。创建拉取请求（Pull Request）是完成工作的更好方式。

感谢

由ricbra/php-discogs-api进行初始开发。

移植到PHP 7并添加更多Discogs API方法由AnssiAhola/php-discogs-api完成。

此API建立在Guzzle 7的基础上。