PHPackages                             calliostro/php-discogs-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. calliostro/php-discogs-api

ActiveLibrary[HTTP & Networking](/categories/http)

calliostro/php-discogs-api
==========================

Lightweight Discogs API client for PHP 8.1+ with modern developer comfort — Clean parameter API and minimal dependencies

v4.0.0(5mo ago)85.1k↑118.8%2[1 PRs](https://github.com/calliostro/php-discogs-api/pulls)1MITPHPPHP ^8.1CI passing

Since Apr 12Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/calliostro/php-discogs-api)[ Packagist](https://packagist.org/packages/calliostro/php-discogs-api)[ RSS](/packages/calliostro-php-discogs-api/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)DependenciesVersions (27)Used By (1)

⚡ Discogs API Client for PHP 8.1+ – Lightweight with Maximum Developer Comfort
==============================================================================

[](#-discogs-api-client-for-php-81--lightweight-with-maximum-developer-comfort)

[![Package Version](https://camo.githubusercontent.com/7811e625e62da3ffbe44900cfb786805b19ab80da6350ce8de459140baf9cbe2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f63616c6c696f7374726f2f7068702d646973636f67732d6170692e737667)](https://packagist.org/packages/calliostro/php-discogs-api)[![Total Downloads](https://camo.githubusercontent.com/8139d41465497ffbea4412041d89777bad18c763a730ab57d58eab307038b580/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f63616c6c696f7374726f2f7068702d646973636f67732d6170692e737667)](https://packagist.org/packages/calliostro/php-discogs-api)[![License](https://camo.githubusercontent.com/f2dfeeea060f0c79952e0f887d1e8cb3014dea1a33c6bb5aeb19dd432d11c3d8/68747470733a2f2f706f7365722e707567782e6f72672f63616c6c696f7374726f2f7068702d646973636f67732d6170692f6c6963656e7365)](https://packagist.org/packages/calliostro/php-discogs-api)[![PHP Version](https://camo.githubusercontent.com/acffb6ae1962992d26e4466782832787e79504a6250f80d732c4283458b9f497/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e312d626c75652e737667)](https://php.net)[![Guzzle](https://camo.githubusercontent.com/6a93cb104bf92d53d8f69d987b59934c07ed2b2dba8d5f6801e340ea930f1774/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f67757a7a6c652d253545362e35253743253545372e302d6f72616e67652e737667)](https://docs.guzzlephp.org/)[![CI](https://github.com/calliostro/php-discogs-api/actions/workflows/ci.yml/badge.svg)](https://github.com/calliostro/php-discogs-api/actions/workflows/ci.yml)[![Code Coverage](https://camo.githubusercontent.com/edad474dd54d3cd340e7f41455c414163c647f182f46e68fd549949e43e84b47/68747470733a2f2f636f6465636f762e696f2f67682f63616c6c696f7374726f2f7068702d646973636f67732d6170692f67726170682f62616467652e7376673f746f6b656e3d30535634495845395631)](https://codecov.io/gh/calliostro/php-discogs-api)[![PHPStan Level](https://camo.githubusercontent.com/d117944b58da8146f96b4ef7403807610a20eeb3fbcaaaf95157bbcdad1686eb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c253230382d627269676874677265656e2e737667)](https://phpstan.org/)[![Code Style](https://camo.githubusercontent.com/5eddc7dd141d0fac72d1558d0950b5f45c014cbbc953b722a79cf21661f73ab6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f64652532307374796c652d50535231322d627269676874677265656e2e737667)](https://github.com/FriendsOfPHP/PHP-CS-Fixer)

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

📦 Installation
--------------

[](#-installation)

```
composer require calliostro/php-discogs-api
```

### Do You Need to Register?

[](#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](https://www.discogs.com/settings/developers) at Discogs to get credentials
- Needed for: search, collections, wantlists, marketplace features

### Symfony Integration

[](#symfony-integration)

**Symfony Users:** For easier integration, there's also a [Symfony Bundle](https://github.com/calliostro/discogs-bundle) available.

🚀 Quick Start
-------------

[](#-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
--------------

[](#-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
-----------------------------------------

[](#-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](https://www.discogs.com/developers/) for complete method reference*

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

📋 Requirements
--------------

[](#-requirements)

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

⚙️ Configuration
----------------

[](#️-configuration)

### 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
----------------

[](#-authentication)

Get credentials at [Discogs Developer Settings](https://www.discogs.com/settings/developers).

### Quick Reference

[](#quick-reference)

What you want to doMethodWhat you needGet artist/release info`create()`NothingSearch the database`createWithConsumerCredentials()`Register appAccess your collection`createWithPersonalAccessToken()`Personal tokenMulti-user app`createWithOAuth()`Full OAuth setup### Complete OAuth Flow Example

[](#complete-oauth-flow-example)

**Step 1: authorize.php** - Redirect user to Discogs

```