This library is a PHP 7.3 implementation of the Discogs API v2.0. The Discogs API is a REST-based interface. By using this library you don't have to worry about communicating with the API: all the hard work has already be done.
This API is build upon the shoulders of a giant: Guzzle 7.0. This is an absolutely awesome library.
This library is released under the MIT license. See the complete license in the LICENSE file.
Start by installing composer. Next do:
$ composer require ricbra/php-discogs-api
PHP >=7.3.0
Creating a new instance is as simple as:
<?php
$client = Discogs\ClientFactory::factory([]);Discogs requires that you supply a User-Agent. You can do this easily:
<?php
$client = Discogs\ClientFactory::factory([
'headers' => ['User-Agent' => 'your-app-name/0.1 +https://www.awesomesite.com'],
]);Discogs doesn't like it when you hit their API at a too high connection rate. Use the ThrottleSubscriber to
prevent getting errors or banned:
<?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 allow to access protected endpoints with either a simple Discogs Auth Flow or a more advanced (and more complex) Oauth Flow
As stated in the Discogs Authentication documentation:
In order to access protected endpoints, you’ll need to register for either a consumer key and secret or user token, depending on your situation:
- To easily access your own user account information, use a User token.
- To get access to an endpoint that requires authentication and build 3rd party apps, use a Consumer Key and Secret.
With the Discogs Php API you can add your credentials to each request by adding a query key to your own defaults like this:
Instead of query use Authorization header
$client = ClientFactory::factory([
'headers' => [
'Authorization' => "Discogs key=key_here, secret=secret_here",
],
]);Authenticate with Personal access token, you can get it from https://www.discogs.com/settings/developers
$client = ClientFactory::factory([
'headers' => [
'User-Agent' => $user_agent,
'Authorization' => "Discogs token={$access_token}",
]
]);There are a lot of endpoints which require OAuth. Lucky for you using Guzzle this is peanuts. If you're having trouble obtaining the token and token_secret, please check out my example implementation.
<?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'
]);Another cool plugin is the History plugin:
<?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
}For more information about Guzzle and its plugins checkout the docs.
Per august 2014 a signed OAuth request is required for this endpoint.
<?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 returns the full url to images so just use the internal client to get those:
$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();
}Authorization is required when folder_id is not 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
]);Creating and manipulating listings requires you to be authenticated as the seller
<?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']);<?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<?php
$response = $client->deleteInventory(['upload' => fopen('path/to/file.csv', 'r')]);
// CSV format (example):
// listing_id
// 123
// 213
// 321Further documentation can be found at the Discogs API v2.0 Documentation.
Implemented a missing call? PR's are welcome!
