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

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!