README

🚀 ONLY 2 CLASSES! The most lightweight Discogs API client for PHP. Zero bloat, maximum performance.

An ultra-minimalist Discogs API client that proves you don't need 20+ classes to build a great API client. Built with modern PHP 8.1+ features, service descriptions, and powered by Guzzle.

📦 Installation

composer require calliostro/php-discogs-api

Important: You need to register your application at Discogs to get your credentials. For read-only access to public data, no authentication is required.

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

🚀 Quick Start

Basic Usage

<?php

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

use Calliostro\Discogs\ClientFactory;

// Basic client for public data
$discogs = ClientFactory::create();

// Fetch artist information
$artist = $discogs->artistGet([
    'id' => '45031' // Pink Floyd
]);

$release = $discogs->releaseGet([
    'id' => '249504' // Nirvana - Nevermind
]);

echo "Artist: " . $artist['name'] . "\n";
echo "Release: " . $release['title'] . "\n";

Collection and Marketplace

<?php

// Authenticated client for protected operations
$discogs = ClientFactory::createWithToken('your-personal-access-token', 'MyApp/1.0');

// Collection management
$folders = $discogs->collectionFolders(['username' => 'your-username']);
$folder = $discogs->collectionFolderGet(['username' => 'your-username', 'folder_id' => '1']);
$items = $discogs->collectionItems(['username' => 'your-username', 'folder_id' => '0']);

// Add release to a collection
$addResult = $discogs->collectionAddRelease([
    'username' => 'your-username',
    'folder_id' => '1', 
    'release_id' => '249504'
]);

// Wantlist management
$wantlist = $discogs->wantlistGet(['username' => 'your-username']);
$addToWantlist = $discogs->wantlistAdd([
    'username' => 'your-username',
    'release_id' => '249504',
    'notes' => 'Looking for mint condition'
]);

// Marketplace operations
$inventory = $discogs->inventoryGet(['username' => 'your-username']);
$orders = $discogs->ordersGet(['status' => 'Shipped']);

// Create a marketplace listing
$listing = $discogs->listingCreate([
    'release_id' => '249504',
    'condition' => 'Near Mint (NM or M-)',
    'sleeve_condition' => 'Very Good Plus (VG+)',
    'price' => '25.00',
    'status' => 'For Sale'
]);

Database Search and Discovery

<?php

// Search the Discogs database
$results = $discogs->search(['q' => 'Pink Floyd', 'type' => 'artist']);
$releases = $discogs->artistReleases(['id' => '45031', 'sort' => 'year']);

// Master release versions
$master = $discogs->masterGet(['id' => '18512']);
$versions = $discogs->masterVersions(['id' => '18512']);

// Label information
$label = $discogs->labelGet(['id' => '1']); // Warp Records
$labelReleases = $discogs->labelReleases(['id' => '1']);

✨ Key Features

Ultra-Lightweight – Only 2 classes, ~234 lines of logic + service descriptions
Complete API Coverage – All 60+ Discogs API endpoints supported
Direct API Calls – $client->artistGet() maps to /artists/{id}, no abstractions
Type Safe + IDE Support – Full PHP 8.1+ types, PHPStan Level 8, method autocomplete
Future-Ready – PHP 8.5 compatible (beta/dev testing)
Pure Guzzle – Modern HTTP client, no custom transport layers
Well Tested – 100% test coverage, PSR-12 compliant
Secure Authentication – Full OAuth and Personal Access Token support

🎵 All Discogs API Methods as Direct Calls

Database Methods – search(), artistGet(), artistReleases(), releaseGet(), releaseRatingGet(), releaseRatingPut(), releaseRatingDelete(), releaseRatingCommunity(), releaseStats(), masterGet(), masterVersions(), labelGet(), labelReleases()
User Identity Methods – identityGet(), userGet(), userEdit(), userSubmissions(), userContributions(), userLists()
Collection Methods – collectionFolders(), collectionFolderGet(), collectionFolderCreate(), collectionFolderEdit(), collectionFolderDelete(), collectionItems(), collectionItemsByRelease(), collectionAddRelease(), collectionEditRelease(), collectionRemoveRelease(), collectionCustomFields(), collectionEditField(), collectionValue()
Wantlist Methods – wantlistGet(), wantlistAdd(), wantlistEdit(), wantlistRemove()
Marketplace Methods – inventoryGet(), listingGet(), listingCreate(), listingUpdate(), listingDelete(), marketplaceFee(), marketplaceFeeCurrency(), marketplacePriceSuggestions(), marketplaceStats()
Order Methods – orderGet(), ordersGet(), orderUpdate(), orderMessages(), orderMessageAdd()
Inventory Export Methods – inventoryExportCreate(), inventoryExportList(), inventoryExportGet(), inventoryExportDownload()
Inventory Upload Methods – inventoryUploadAdd(), inventoryUploadChange(), inventoryUploadDelete(), inventoryUploadList(), inventoryUploadGet()
List Methods – listGet()

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

📋 Requirements

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

🔧 Advanced Configuration

Option 1: Simple Configuration (Recommended)

For basic customizations like timeout or User-Agent, use the ClientFactory:

<?php

use Calliostro\Discogs\ClientFactory;

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

Option 2: Advanced Guzzle Configuration

For advanced HTTP client features (middleware, interceptors, etc.), create your own Guzzle client:

<?php

use GuzzleHttp\Client;
use Calliostro\Discogs\DiscogsApiClient;

$httpClient = new Client([
    'timeout' => 30,
    'connect_timeout' => 10,
    'headers' => [
        'User-Agent' => 'MyApp/1.0 (+https://myapp.com)',
    ]
]);

// Direct usage
$discogs = new DiscogsApiClient($httpClient);

// Or via ClientFactory
$discogs = ClientFactory::create('MyApp/1.0', $httpClient);

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

🔐 Authentication

Discogs supports different authentication flows:

Personal Access Token (Recommended)

For accessing your own account data, use a Personal Access Token from Discogs Developer Settings:

<?php

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

use Calliostro\Discogs\ClientFactory;

$discogs = ClientFactory::createWithToken('your-personal-access-token');

// Access protected endpoints
$identity = $discogs->identityGet();
$collection = $discogs->collectionFolders(['username' => 'your-username']);

OAuth 1.0a Authentication

For building applications that access user data on their behalf:

<?php

// You need to implement the OAuth flow to get these tokens
$discogs = ClientFactory::createWithOAuth('oauth-token', 'oauth-token-secret');

$identity = $discogs->identityGet();
$orders = $discogs->ordersGet();

💡 Note: Implementing the complete OAuth flow is complex and beyond the scope of this README. For detailed examples, see the Discogs OAuth Documentation.

🧪 Testing

Run the test suite:

composer test

Run static analysis:

composer analyse

Check code style:

composer cs

📚 API Documentation Reference

For complete API documentation including all available parameters, visit the Discogs API Documentation.

Popular Methods

Database Methods

search($params) – Search the Discogs database
artistGet($params) – Get artist information
artistReleases($params) – Get artist's releases
releaseGet($params) – Get release information
masterGet($params) – Get master release information
masterVersions($params) – Get master release versions

Collection Methods

collectionFolders($params) – Get user's collection folders
collectionItems($params) – Get collection items by folder
collectionFolderGet($params) – Get specific collection folder

User Methods

identityGet($params) – Get authenticated user's identity (auth required)
userGet($params) – Get user profile information
wantlistGet($params) – Get user's wantlist

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Please ensure your code follows PSR-12 standards and includes tests.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

🙏 Acknowledgments

Discogs for providing the excellent music database API
Guzzle for the robust HTTP client
ricbra/php-discogs-api and AnssiAhola/php-discogs-api for the original inspiration

⭐ Star this repo if you find it useful! It helps others discover this lightweight solution.

calliostro / php-discogs-api

Maintainers

Details