ricbra/php-discogs-api
A PHP client for the Discogs API that simplifies querying artists, releases, labels, marketplace listings, collections, and search results. Supports authentication and clean object-oriented access to Discogs data for building music catalog and collection tools.
The package is effectively frozen at a 2014 release and archived upstream. Treat it as a vendored legacy client you wrap, not a package you sprinkle through a Laravel app.
1. Install and verify compatibility first. The library targets PHP 5.4 and pulls a Guzzle 3.x-era dependency, which will collide with the Guzzle 7 that modern Laravel ships. On current Laravel this usually means you cannot composer require it cleanly. Options, in order of preference:
composer require ricbra/php-discogs-api
php artisan about # confirm the framework still boots after install
2. Get credentials from Discogs. Create an application in your Discogs developer settings. You get a consumer key and secret; for personal/scripted access you also generate a token and token secret. Discogs uses OAuth 1.0a, so all four values matter for authenticated calls.
3. Put credentials in config, never in code. Add to config/services.php:
'discogs' => [
'consumer_key' => env('DISCOGS_CONSUMER_KEY'),
'consumer_secret' => env('DISCOGS_CONSUMER_SECRET'),
'token' => env('DISCOGS_TOKEN'),
'secret' => env('DISCOGS_TOKEN_SECRET'),
'user_agent' => env('DISCOGS_USER_AGENT', 'MyApp/1.0 +https://example.com'),
],
4. Bind the client once. In a service provider:
$this->app->singleton(\Discogs\Client::class, function ($app) {
return \Discogs\Client::factory(config('services.discogs'));
});
5. First use case: resolve a release for a product page. Look up a barcode or catalogue number, then fetch the release:
$client = app(\Discogs\Client::class);
$results = $client->search(['q' => '5 099703 204322', 'type' => 'release']);
$id = $results['results'][0]['id'] ?? null;
$release = $id ? $client->getRelease(['id' => $id]) : null;
Where to look first: the package's Client factory signature for the exact parameter names it accepts, and the bundled service description (usually XML/JSON under src/) for the authoritative list of operations and argument shapes. Trust that file over any README example — the README predates several Discogs API changes.
Wrap the client in a repository/service. Keep raw Discogs\Client calls out of controllers and jobs. A DiscogsRepository with intent-named methods (findReleaseByBarcode, artistReleases) gives you a single seam to swap the client later and a natural place to normalise responses.
Normalise response shapes at the boundary. The client hands back decoded arrays with inconsistent keys: single-resource endpoints return the resource at the top level, list endpoints nest under releases, results, versions, images, plus a pagination block (page, pages, per_page, items). Convert to DTOs or Eloquent-shaped arrays immediately so the rest of the app isn't doing $data['results'][0]['basic_information'] archaeology.
Cache aggressively by ID. Discogs data is slow-changing and rate-limited. Cache::remember("discogs:release:{$id}", now()->addDay(), fn () => ...) cuts most traffic. Cache search queries with a shorter TTL. Releases are stable, but artist and master records absorb merges, so use a shorter TTL on those.
Queue anything bulk. Do not loop over 500 releases in a request. Dispatch jobs, and throttle the queue — a single worker with ->delay() or a rate-limited job middleware keeps you inside Discogs' request budget. A failed 429 in the middle of a sync is much worse than a slow sync.
Respect the rate limit deliberately. Discogs limits are strict (25 req/min unauthenticated, 60 req/min authenticated by default). Build the limiter in from day one rather than bolting it on after your first 429. Laravel's RateLimiter facade works well here.
Two-layer lookup pattern. Search first to get candidate IDs, then getRelease/getArtist/getMaster for the canonical record. Search results are summaries only — they lack tracklists, labels, formats, and marketplace data.
OAuth for user-scoped endpoints. Wantlist and collection operations require the user's own token, not your app token. The flow: request a token from the package, redirect the user to Discogs' authorise URL, handle the callback, then persist the access token and secret per user (encrypted cast on your model). The package exposes request/access token helpers, but the token-issuing leg is old enough that you may need to hand-roll the signature with Guzzle.
Compose with your domain models. A Release model with a nullable discogs_id, plus a sync job, is more maintainable than an app that calls Discogs on every page view. Treat Discogs as an import source and a reference, not a live dependency.
The User-Agent is mandatory. Discogs returns 403 without a descriptive User-Agent identifying your app and a contact URL or email. This trips up almost everyone first. Set it in the client config and make sure it survives into every retry.
Archived means no security or API-drift fixes. The package will not track Discogs API changes (fields added, endpoints revised, auth tightened). Pin the version, wrap it behind your own interface, and budget for replacement. This is the single biggest risk in adopting it.
Guzzle 3 is the real blocker. Composer conflicts with modern Laravel are likely. Check composer why-not guzzlehttp/guzzle before assuming the install was clean; sometimes it "installs" but a transitive dependency pins you to a Guzzle that Laravel's HTTP layer won't accept.
PHP 8 will surface fatal errors. Old array/string syntax, each(), dynamic properties, and deprecated type juggling all bite on PHP 8. If you must run it, run it on PHP 7.4 or patch the fork.
Responses are decoded arrays, not objects. No ->getRelease() accessor on results — index into arrays. Handle missing keys defensively; Discogs omits fields (e.g. tracklist, notes, images) rather than returning null.
429 and 5xx need backoff, not retries in a tight loop. Add a Guzzle retry subscriber or wrap calls in a retry() with exponential backoff. The package itself does no retry logic.
OAuth 1.0a signatures are order-sensitive. Query params, body params, and the authorization header must be constructed consistently. If you get a 401 on a request that looks identical to a working one, suspect parameter ordering or a stale timestamp.
Pagination is manual. There's no ->all(). Read pagination.pages and loop, respecting the rate limit between pages.
Cache invalidation for artist merges. Discogs merges artist profiles; an ID you cached last month may now redirect. Follow redirects and update your stored ID, or accept stale entries.
Extension points. The client is a Guzzle client, so custom event subscribers, retry middleware, and a custom User-Agent via default headers are the practical hooks. You can also override the base URL by constructing the client with an explicit base_url if you need to point at a mock server in tests.
Test with fixtures, not the live API. Record representative JSON responses (release, artist, search, collection) into tests/fixtures and bind a fake to the repository interface. Never hit Discogs in CI — the rate limit will bite you and flaky network tests will erode trust in the suite.
How can I help you explore Laravel packages today?