README

Laravel Discogs

A Laravel package for the Discogs API using the same action-first shape as laravel-spotify-api-wrapper.

Requires PHP 8.2+ and Laravel 12 or 13.

Install

composer require bjthecod3r/laravel-discogs
php artisan vendor:publish --tag=discogs-config

Configure

DISCOGS_CONSUMER_KEY=
DISCOGS_CONSUMER_SECRET=
DISCOGS_PERSONAL_ACCESS_TOKEN=
DISCOGS_USER_AGENT="YourApp/1.0 +https://yourapp.test"
DISCOGS_REDIRECT_URI="${APP_URL}/discogs/callback"
DISCOGS_CALLBACK_REDIRECT_URL="${APP_URL}/dashboard"
DISCOGS_ROUTES_ENABLED=false

Discogs requires a descriptive User-Agent on every request. Public database lookups can run without credentials, search and private surfaces should use app credentials, and account writes need a personal token or OAuth credentials.

Usage

use BjTheCod3r\Discogs\Facades\Discogs;

$artist = Discogs::artist(108713)->get();
$release = Discogs::release(249504)->currency('GBP')->get();

$results = Discogs::search('Daft Punk', 'release')
    ->field('year', '1997')
    ->perPage(10)
    ->get();

$artist->name;              // "Daft Punk"
$results->items[0]->title;  // typed SearchResult item

$wantlist = Discogs::wantlist('your-username')->page(1)->get();

Discogs::wantlist('your-username')
    ->release(249504)
    ->add(notes: 'Find a clean copy', rating: 5)
    ->get();

OAuth 1.0a is available for multi-user applications:

return Discogs::redirect($request);

$token = Discogs::handleCallback($request);

$identity = Discogs::withOAuth($token->token, $token->secret)
    ->identity()
    ->get();

The package ships GET /discogs/redirect and GET /discogs/callback, but they are opt-in. Set DISCOGS_ROUTES_ENABLED=true to register them. The redirect route starts an OAuth handshake against your Discogs application's rate limit, so publish the config and restrict discogs.oauth.routes_middleware (for example to ['web', 'auth']) if the flow should not be reachable by guests. Leave the routes disabled and call Discogs::redirect() / Discogs::handleCallback() from your own controller if you want full control.

The built-in callback route redirects to DISCOGS_CALLBACK_REDIRECT_URL, flashes discogs.connected, and dispatches BjTheCod3r\Discogs\Events\DiscogsConnected. Listen for that event to persist the OAuth token credentials in your application.

Action Surface

Database: search, artist, artistReleases, label, labelReleases, release, master, masterVersions, releaseRating, releaseStats
Users: identity, user, submissions, contributions, userLists, list, collectionFolders, collectionFolder, updateCollectionFolder, deleteCollectionFolder, collectionItems, collectionItemsByRelease, collectionInstance, moveCollectionInstance, removeCollectionInstance, collectionFields, setCollectionField, collectionValue, wantlist, inventory
Marketplace: listing, marketplaceFee, priceSuggestions, marketplaceStats, orders, order, orderMessages
Inventory jobs: inventoryExports, requestInventoryExport, inventoryExport, inventoryExportDownload, inventoryUploads, inventoryUpload, addInventoryUpload, changeInventoryUpload, deleteInventoryUpload
Escape hatch: get, post, put, delete for newly released or niche endpoints

Typed Responses

Known Discogs endpoints decode into response DTOs under BjTheCod3r\Discogs\Resources. Each DTO exposes common response fields as readonly properties and keeps the original payload available through toArray() / JSON serialization.

Typed resources include Artist, Label, Release, Master, UserProfile, Listing, Order, MarketplaceFee, ReleaseRating, SearchResult, ReleaseSummary, and MasterVersion. Paginated actions return Paginated with typed items where the item shape is known.

Nested response objects that matter are typed too, including Image, Entity, Format, Track, Identifier, Video, Price, UserSummary, and OrderItem.

Tests

composer test        # Pest
composer format      # Pint
composer analyse     # Larastan
composer test:ci     # all three, the same checks CI runs

Contributing

Commits follow Conventional Commits (feat:, fix:, docs:, ci:, …). Releases are cut automatically by release-please: merging to main opens or updates a release PR, and merging that PR tags the version, publishes the GitHub release, and updates CHANGELOG.md.

While the package is below 1.0.0, breaking changes bump the minor version.

Changelog

See CHANGELOG.md.

License

The MIT License (MIT). See LICENSE.

bjthecod3r / laravel-discogs

Maintainers

Package info

Statistics

Security