Php Discogs Api Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require calliostro/php-discogs-api
   

   Requires PHP 8.1+ (Guzzle 7+ and package dependencies).

2. Basic Setup Create a client instance using your Discogs OAuth 1.0a credentials (obtain from Discogs Developer Settings):

   use Calliostro\Discogs\DiscogsClient;
   
   $client = new DiscogsClient(
       key: env('DISCOGS_KEY'),
       secret: env('DISCOGS_SECRET'),
       token: env('DISCOGS_TOKEN'),
       tokenSecret: env('DISCOGS_TOKEN_SECRET')
   );
   

3. First Use Case: Fetch an Artist

   $artist = $client->getArtist(12345); // Replace with an actual artist ID
   dd($artist->name, $artist->realname);
   

4. Explore the API Check the Discogs API Documentation and the package’s README for available endpoints (e.g., listArtistReleases(), searchReleases()).

Implementation Patterns

Common Workflows

1. Searching for Releases

   $results = $client->searchReleases(
       query: 'Pink Floyd',
       type: 'master',
       perPage: 25
   );
   foreach ($results as $release) {
       echo $release->title . ' (' . $release->year . ')' . PHP_EOL;
   }
   

2. Batching Requests Use Laravel’s HttpClient or Guzzle’s Promise for parallel requests:

   $artistIds = [123, 456, 789];
   $artists = collect($artistIds)->map(fn($id) => $client->getArtist($id));
   

3. Laravel Integration Bind the client to the container in config/services.php:

   'discogs' => [
       'key' => env('DISCOGS_KEY'),
       'secret' => env('DISCOGS_SECRET'),
       'token' => env('DISCOGS_TOKEN'),
       'token_secret' => env('DISCOGS_TOKEN_SECRET'),
   ],
   

   Register in a service provider:

   $this->app->singleton(DiscogsClient::class, fn() => new DiscogsClient(
       config('services.discogs.key'),
       config('services.discogs.secret'),
       config('services.discogs.token'),
       config('services.discogs.token_secret')
   ));
   

   Inject via constructor:

   public function __construct(private DiscogsClient $discogs) {}
   

4. Handling Pagination Use paginate() or loop with offset/limit parameters:

   $releases = $client->searchReleases(
       query: 'Radiohead',
       perPage: 50
   );
   while ($releases->hasMore()) {
       $releases = $client->searchReleases(
           query: 'Radiohead',
           perPage: 50,
           offset: $releases->offset + 50
       );
   }
   

5. Caching Responses Cache frequent queries using Laravel’s cache:

   $release = Cache::remember("discogs_release_{$releaseId}", now()->addHours(1), fn() =>
       $client->getRelease($releaseId)
   );
   

Gotchas and Tips

Pitfalls

1. OAuth 1.0a Requirements

   • New: The package now enforces OAuth 1.0a (RFC 5849) for authentication.
   • Tip: Ensure you have all four credentials (key, secret, token, token_secret) from Discogs Developer Settings.
   • Error: Missing credentials will throw Calliostro\Discogs\Exceptions\AuthenticationException.

2. Method Naming Changes

   • Breaking: All 60+ methods now use verb-first naming (e.g., getArtist() instead of artist()).
   • Tip: Use IDE autocomplete or check the UPGRADE.md guide for the full list.

3. Parameter Validation

   • New: All parameters are strictly typed and validated.
   • Tip: IDEs will now show autocomplete and parameter hints (e.g., searchReleases(query: string, type: string|null)).

4. Rate Limiting

   • Discogs enforces rate limits (e.g., 1000+ requests/minute for authenticated OAuth).
   • Tip: Implement exponential backoff or use Laravel’s throttle middleware.

5. Missing Endpoints

   • The package covers core endpoints but not all Discogs APIs (e.g., marketplace advanced features).
   • Tip: Use the underlying Guzzle client for unsupported endpoints:

     $response = $client->getGuzzleClient()->get('https://api.discogs.com/marketplace/...');
     

Debugging Tips

1. Enable Guzzle Debugging Pass a HandlerStack with debug middleware:

   use GuzzleHttp\HandlerStack;
   use GuzzleHttp\Middleware;
   
   $stack = HandlerStack::create();
   $stack->push(Middleware::tap(function ($request) {
       \Log::debug('Discogs Request:', ['url' => (string) $request->getUri()]);
   }));
   
   $client = new DiscogsClient(
       key: env('DISCOGS_KEY'),
       secret: env('DISCOGS_SECRET'),
       token: env('DISCOGS_TOKEN'),
       tokenSecret: env('DISCOGS_TOKEN_SECRET'),
       guzzleClient: new Client(['handler' => $stack])
   );
   

2. Inspect Raw Responses Access the underlying Guzzle response:

   try {
       $release = $client->getRelease(123);
   } catch (\Exception $e) {
       $rawResponse = $client->getGuzzleClient()->get('...')->getBody();
       \Log::error($rawResponse);
   }
   

Extension Points

1. Custom Resources Extend the base Resource class to add methods:

   class CustomRelease extends \Calliostro\Discogs\Resources\Release {
       public function isVinyl(): bool {
           return str_contains($this->format, 'Vinyl');
       }
   }
   

   Override the client’s hydration logic if needed.

2. Add New Endpoints Extend the DiscogsClient class:

   public function getUserCollection(string $username): array {
       $response = $this->getGuzzleClient()->get("/users/{$username}/collection");
       return $this->hydrateCollection($response->getBody());
   }
   

3. Mocking for Tests Use Laravel’s HttpClient mocking or replace the client:

   $mock = Mockery::mock(DiscogsClient::class);
   $mock->shouldReceive('getRelease')->andReturn(new Release(['title' => 'Mock Release']));
   

4. Webhook Integration For real-time updates, use Discogs’ webhook system and handle payloads via Laravel’s Broadcast or Queue systems.

5. Type-Safe Parameters Leverage PHP 8.1+ named arguments and type hints:

   $client->searchReleases(
       query: 'Artist Name',
       type: 'master', // string|null
       perPage: 25,    // int
       year: 2023      // int|null
   );