Discogs Api Bundle Laravel Package

Getting Started

This package wraps the Discogs API for Laravel, giving you a configured HTTP client, container bindings, and a fluent surface for releases, collection items, and folders. Version 1.1.0 is a minor, additive release: collection items can now carry a Discogs folder id, so an item can be created directly into a named custom folder instead of landing in Uncategorized.

Minimal setup:

1. Install and publish config: composer require <vendor>/<package> then php artisan vendor:publish --tag=<package>-config. Check the published config for the exact environment key names — typically a personal access token plus a user agent string, which Discogs requires and will reject requests without.
2. Set credentials in .env (token and a something/1.0 +contact style user agent). Never rely on the package default user agent in production; Discogs rate-limits or blocks generic agents.
3. Confirm the binding resolves: app(\Discogs\Client::class) (or whatever the root client class is named in the service provider) — inspect the provider's register() to see whether it is a singleton or a fresh instance per resolution.

First use case worth wiring up: list the authenticated user's folders, match a folder by name, then add a release to it.

$folders = $client->user()->collection()->folders($username);

$folderId = collect($folders)->firstWhere('name', 'Wantlist Purchases')['id'];

$client->user()->collection()->addItem($username, [
    'release_id' => $releaseId,
    'folder_id'  => $folderId,   // new in 1.1.0
]);

Look first at how the package hydrates responses (array vs. DTO) before writing mapping code — that decision shapes everything downstream.

Implementation Patterns

Folder-aware ingestion. The main workflow this release unlocks is routing incoming records to the right folder at creation time rather than adding everything to Uncategorized and moving it afterwards. Discogs does support moving items between folders, but doing it in one call avoids a second request and the intermediate inconsistent state.

Folder id resolution as a value object. Folder ids are per-user, unstable integers. Resolve names to ids once (a cached config map or a small FolderResolver class) and inject that, rather than hardcoding folder_id => 3 in jobs. Cache the folder list for a few minutes; it changes rarely.

Queue the backfill. Any job that adds many collection items should be queued with a per-request delay. Discogs caps authenticated traffic at roughly 60 requests/minute; a tight loop of addItem calls will start returning 429s partway through.

class AddToCollection implements ShouldQueue
{
    public function handle(DiscogsClient $client, FolderResolver $folders): void
    {
        $client->user()->collection()->addItem(
            config('services.discogs.username'),
            ['release_id' => $this->releaseId, 'folder_id' => $folders->id('Purchases')],
        );
    }
}

Keep folder ids out of persistence. Store a folder key or name in your own database and translate at call time. Persisting raw Discogs folder ids means a user reorganising their collection silently corrupts your app's mapping.

Testing. Use Http::fake() with a captured response fixture for the add-item endpoint and assert the outgoing request body contains folder_id. The package's client almost certainly builds on Laravel's HTTP client, so Http::assertSent() works without extra tooling.

Integration tip. Treat collection-item creation as non-idempotent. If a queued job retries after a timeout, you can end up with the API having accepted the item even though your side saw an error. Write a small "already in collection" check, or accept duplicates and de-duplicate in a nightly reconcile.

Gotchas and Tips

• The parameter is optional and defaults to Uncategorized. Existing calls are unaffected, which is why this is 1.1.0 and not a major. But if you were relying on the old implicit behaviour and also passing an unrelated field named similarly, verify the payload shape in the changelog before upgrading.
• Folder ids must exist and belong to that user. Passing a folder id from a different account, or a stale id after the folder was deleted, yields an error from Discogs rather than a graceful fallback. Validate against a freshly fetched folder list when the id came from config.
• folder_id is a creation-time concern. It is not a general-purpose "move this item" switch. Moving an existing collection item between folders is a separate endpoint; check whether the package exposes it before building a UI around it.
• Ids, not names, all the way down. There is no server-side "add to folder named X". Any name-based ergonomics are yours to build.
• Rate limits are per-token, not per-process. Running several workers against the same token multiplies your request rate from Discogs' perspective. Budget them together.
• Debugging empty or wrong results. Dump the raw response before blaming hydration — Discogs frequently returns a 200 with a message-style body on partial failures, and a naive client will hand you an empty array.
• Extension points. If the package ships a configurable base URI or HTTP middleware hook, that is the clean place to add retry-with-backoff (retry(3, 2000)) and request logging, rather than wrapping every call site.
• Upgrade checklist for 1.1.0: run your test suite against a faked add-item response, confirm the payload shape still matches your fixtures, and add one integration test that exercises a real folder id end-to-end.