PHPackages                             ampache/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. [API Development](/categories/api)
4. /
5. ampache/php-discogs-api

ActiveLibrary[API Development](/categories/api)

ampache/php-discogs-api
=======================

A PHP library for accessing the Discogs API

0.2.0(1y ago)112.0k↓39.2%MITPHPPHP >=8.2CI passing

Since Mar 30Pushed 2w ago3 watchersCompare

[ Source](https://github.com/ampache/php-discogs-api)[ Packagist](https://packagist.org/packages/ampache/php-discogs-api)[ Docs](https://github.com/ampache/php-discogs-api)[ RSS](/packages/ampache-php-discogs-api/feed)WikiDiscussions master Synced 2w ago

READMEChangelog (3)Dependencies (5)Versions (4)Used By (0)

php-discogs-api (AmpacheDiscogs)
================================

[](#php-discogs-api-ampachediscogs)

This library is a simple Discogs query library exported from the [Ampache Discogs plugin](https://github.com/ampache/ampache/blob/develop/src/Plugin/AmpacheDiscogs.php).

The focus here is on keeping it small and simple.

All data is JSON decoded with objects converted into associative arrays.

License
-------

[](#license)

AGPL-3.0-or-later. See [LICENSE.md](LICENSE.md).

This library is an export of the Ampache Discogs plugin and carries Ampache's license. Releases before 0.3.0 declared `MIT` in `composer.json`; that was a mistake in the metadata, not a different license — the AGPL text and the source headers were there from the initial commit.

Requirements
------------

[](#requirements)

- PHP8.2+
- rmccue/requests

Paging
------

[](#paging)

Discogs paginates the list endpoints. Every method that hits one takes a trailing `int $page = 1`, and the `pagination` block in the response says how many pages there are:

```
$page  = $discogs->get_label_releases(1);
$total = $page['pagination']['pages'];

for ($number = 1; $number get_label_releases(1, $number)['releases'];
    // ...
}
```

Paged: `get_artist_releases`, `get_label_releases`, `get_master_versions`, `get_collection_items_by_folder`, `get_user_lists`, `get_wantlist`, `search_album`, `search_artist`, `search_master`, `search_release`. Pass a page to `search()` in its parameter array. Anything returning a single record takes no page.

Each request is paced to about a second, so walking a long list is not instant.

**`get_artist_releases()` repeats a few records across page boundaries** and returns 49 rows for a `per_page` of 50. That is Discogs, not this library: it happens on the raw endpoint under every `sort` option. Key on `id` when collecting pages from it:

```
$byId = [];
for ($number = 1; $number get_artist_releases($artistId, $number)['releases'] as $release) {
        $byId[$release['id']] = $release;
    }
}
```

The other paged endpoints — label releases, master versions, wantlists and search — return non-overlapping pages.

Rate limiting and errors
------------------------

[](#rate-limiting-and-errors)

Discogs allows 60 authenticated requests a minute. The client paces itself to that, widens the gap as `X-Discogs-Ratelimit-Remaining` runs down, and retries a `429` or a `5xx` up to three times, honouring `Retry-After`. Nothing is required of the caller for that to happen.

Anything that still fails throws `AmpacheDiscogs\DiscogsException`, which extends `Exception` and carries the HTTP status so the cases can be told apart:

```
use AmpacheDiscogs\DiscogsException;

try {
    $album = $discogs->get_master(1234);
} catch (DiscogsException $error) {
    if ($error->getStatusCode() === 404) {
        // no such record, nothing to retry
    } elseif ($error->isRateLimited()) {
        // still limited after three attempts, come back later
    }

    print_r($error->getMessage());
}
```

Usage Example
-------------

[](#usage-example)

```