README

🚀 MINIMAL YET POWERFUL! Focused, lightweight Discogs API client — as compact as possible while maintaining modern PHP comfort and clean APIs.

📦 Installation

composer require calliostro/php-discogs-api

Do You Need to Register?

For basic database access (artists, releases, labels): No registration needed

Install and start using basic endpoints immediately

For search and user features: Registration required

Register your application at Discogs to get credentials
Needed for: search, collections, wantlists, marketplace features

Symfony Integration

Symfony Users: For easier integration, there's also a Symfony Bundle available.

🚀 Quick Start

Public data (no registration needed):

$discogs = DiscogsClientFactory::create();

$artist = $discogs->getArtist(5590213);     // Billie Eilish
$release = $discogs->getRelease(19929817);  // Olivia Rodrigo - Sour
$label = $discogs->getLabel(2311);          // Interscope Records

Search with consumer credentials:

$discogs = DiscogsClientFactory::createWithConsumerCredentials('key', 'secret');

// Positional parameters (traditional)
$results = $discogs->search('Billie Eilish', 'artist');
$releases = $discogs->listArtistReleases(4470662, 'year', 'desc', 50);

// Named parameters (PHP 8.0+, recommended for clarity)
$results = $discogs->search(query: 'Taylor Swift', type: 'release');
$releases = $discogs->listArtistReleases(
    artistId: 4470662,
    sort: 'year', 
    sortOrder: 'desc',
    perPage: 25
);

Your collections (personal token):

$discogs = DiscogsClientFactory::createWithPersonalAccessToken('token');

$collection = $discogs->listCollectionFolders('your-username');
$wantlist = $discogs->getUserWantlist('your-username');

// Add to the collection with named parameters
$discogs->addToCollection(
    username: 'your-username',
    folderId: 1,
    releaseId: 30359313
);

Multi-user apps (OAuth):

$discogs = DiscogsClientFactory::createWithOAuth('key', 'secret', 'oauth_token', 'oauth_secret');

$identity = $discogs->getIdentity();

✨ Key Features

Simple Setup – Works immediately with public data, easy authentication for advanced features
Complete API Coverage – All 60 Discogs API endpoints supported
Clean Parameter API – Natural method calls: getArtist(123) with named parameter support
Lightweight Focus – Minimal codebase with only essential dependencies
Modern PHP Comfort – Full IDE support, type safety, PHPStan Level 8 without bloat
Secure Authentication – Full OAuth and Personal Access Token support
Well Tested – 100% test coverage, PSR-12 compliant
Future-Ready – PHP 8.1–8.5 compatible (beta/dev testing)
Pure Guzzle – Modern HTTP client, no custom transport layers

🎵 All Discogs API Methods as Direct Calls

Database Methods – search(), getArtist(), listArtistReleases(), getRelease(), updateUserReleaseRating(), deleteUserReleaseRating(), getUserReleaseRating(), getCommunityReleaseRating(), getReleaseStats(), getMaster(), listMasterVersions(), getLabel(), listLabelReleases()
Marketplace Methods – getUserInventory(), getMarketplaceListing(), createMarketplaceListing(), updateMarketplaceListing(), deleteMarketplaceListing(), getMarketplaceFee(), getMarketplaceFeeByCurrency(), getMarketplacePriceSuggestions(), getMarketplaceStats(), getMarketplaceOrder(), getMarketplaceOrders(), updateMarketplaceOrder(), getMarketplaceOrderMessages(), addMarketplaceOrderMessage()
Inventory Export Methods – createInventoryExport(), listInventoryExports(), getInventoryExport(), downloadInventoryExport()
Inventory Upload Methods – addInventoryUpload(), changeInventoryUpload(), deleteInventoryUpload(), listInventoryUploads(), getInventoryUpload()
User Identity Methods – getIdentity(), getUser(), updateUser(), listUserSubmissions(), listUserContributions()
User Collection Methods – listCollectionFolders(), getCollectionFolder(), createCollectionFolder(), updateCollectionFolder(), deleteCollectionFolder(), listCollectionItems(), getCollectionItemsByRelease(), addToCollection(), updateCollectionItem(), removeFromCollection(), getCustomFields(), setCustomFields(), getCollectionValue()
User Wantlist Methods – getUserWantlist(), addToWantlist(), updateWantlistItem(), removeFromWantlist()
User Lists Methods – getUserLists(), getUserList()

All Discogs API endpoints are supported with clean documentation — see Discogs API Documentation for complete method reference

💡 Note: Some endpoints require special permissions (seller accounts, data ownership).

📋 Requirements

php ^8.1
guzzlehttp/guzzle ^6.5 || ^7.0

⚙️ Configuration

Configuration

Simple (works out of the box):

use Calliostro\Discogs\DiscogsClientFactory;

$discogs = DiscogsClientFactory::create();

Advanced (middleware, custom options, etc.):

use Calliostro\Discogs\DiscogsClientFactory;
use GuzzleHttp\{HandlerStack, Middleware};

$handler = HandlerStack::create();
$handler->push(Middleware::retry(
    fn ($retries, $request, $response) => $retries < 3 && $response?->getStatusCode() === 429,
    fn ($retries) => 1000 * 2 ** ($retries + 1) // Rate limit handling
));

$discogs = DiscogsClientFactory::create([
    'timeout' => 30,
    'handler' => $handler,
    'headers' => [
        'User-Agent' => 'MyApp/1.0 (+https://myapp.com)',
    ]
]);

💡 Note: By default, the client uses DiscogsClient/4.0.0 +https://github.com/calliostro/php-discogs-api as User-Agent. You can override this by setting custom headers as shown above.

🔐 Authentication

Get credentials at Discogs Developer Settings.

Quick Reference

What you want to do	Method	What you need
Get artist/release info	`create()`	Nothing
Search the database	`createWithConsumerCredentials()`	Register app
Access your collection	`createWithPersonalAccessToken()`	Personal token
Multi-user app	`createWithOAuth()`	Full OAuth setup

Complete OAuth Flow Example

Step 1: authorize.php - Redirect user to Discogs

<?php
// authorize.php

use Calliostro\Discogs\OAuthHelper;

$consumerKey = 'your-consumer-key';
$consumerSecret = 'your-consumer-secret';
$callbackUrl = 'https://yourapp.com/callback.php';

$oauth = new OAuthHelper();
$requestToken = $oauth->getRequestToken($consumerKey, $consumerSecret, $callbackUrl);

$_SESSION['oauth_token'] = $requestToken['oauth_token'];
$_SESSION['oauth_token_secret'] = $requestToken['oauth_token_secret'];

$authUrl = $oauth->getAuthorizationUrl($requestToken['oauth_token']);
header("Location: {$authUrl}");
exit;

Step 2: callback.php - Handle Discogs callback

<?php
// callback.php

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

use Calliostro\Discogs\{OAuthHelper, DiscogsClientFactory};

$consumerKey = 'your-consumer-key';
$consumerSecret = 'your-consumer-secret';
$verifier = $_GET['oauth_verifier'];

$oauth = new OAuthHelper();
$accessToken = $oauth->getAccessToken(
    $consumerKey,
    $consumerSecret,
    $_SESSION['oauth_token'],
    $_SESSION['oauth_token_secret'],
    $verifier
);

$oauthToken = $accessToken['oauth_token'];
$oauthSecret = $accessToken['oauth_token_secret'];

// Store tokens for future use
$_SESSION['oauth_token'] = $oauthToken;
$_SESSION['oauth_token_secret'] = $oauthSecret;

$discogs = DiscogsClientFactory::createWithOAuth($consumerKey, $consumerSecret, $oauthToken, $oauthSecret);
$identity = $discogs->getIdentity();
echo "Hello " . $identity['username'];

🤝 Contributing

Contributions are welcome! See DEVELOPMENT.md for detailed setup instructions, testing guide, and development workflow.

📄 License

MIT License – see LICENSE file.

🙏 Acknowledgments

Discogs for the excellent API
Guzzle for an HTTP client
Previous PHP Discogs implementations for inspiration

⭐ Star this repo if you find it useful!

calliostro / php-discogs-api

Maintainers

Details