Repository files navigation

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

composer require calliostro/php-discogs-api

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 Users: For easier integration, there's also aSymfony Bundle available.

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

• 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

• 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 — seeDiscogs API Documentation for complete method reference

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

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

Simple (works out of the box):

useCalliostro\Discogs\DiscogsClientFactory;$discogs = DiscogsClientFactory::create();

Advanced (middleware, custom options, etc.):

useCalliostro\Discogs\DiscogsClientFactory;useGuzzleHttp\{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 usesDiscogsClient/4.0.0 +https://github.com/calliostro/php-discogs-api as User-Agent. You can override this by setting custom headers as shown above.

Get credentials atDiscogs Developer Settings.

Step 1: authorize.php - Redirect user to Discogs

<?php// authorize.phpuseCalliostro\Discogs\OAuthHelper;$consumerKey ='your-consumer-key';$consumerSecret ='your-consumer-secret';$callbackUrl ='https://yourapp.com/callback.php';$oauth =newOAuthHelper();$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.phprequire__DIR__ .'/vendor/autoload.php';useCalliostro\Discogs\{OAuthHelper,DiscogsClientFactory};$consumerKey ='your-consumer-key';$consumerSecret ='your-consumer-secret';$verifier =$_GET['oauth_verifier'];$oauth =newOAuthHelper();$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'];

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

MIT License – seeLICENSE file.

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

⭐Star this repo if you find it useful!