Discogs Bundle Laravel Package

Getting Started

First Steps

1. Installation:

   composer require calliostro/discogs-bundle
   

   For Symfony projects, add the bundle to config/bundles.php:

   Calliostro\DiscogsBundle\DiscogsBundle::class => ['all' => true],
   

2. Zero-Configuration Mode: Use the DiscogsClient directly for public API access without configuration:

   use Calliostro\DiscogsBundle\Client\DiscogsClient;
   
   $client = new DiscogsClient();
   $releases = $client->listReleases(['page' => 1, 'per_page' => 20]);
   

3. Basic Usage: Leverage IDE autocomplete for method names (e.g., getArtist, searchDatabase). Example:

   $artist = $client->getArtist(['id' => 123456]);
   

Key Resources

• README for setup.
• UPGRADE.md for migration specifics.

Implementation Patterns

Workflows

1. Type-Safe API Calls: Use typed parameters with camelCase naming (e.g., listReleases(int $page, int $perPage)). The bundle validates inputs automatically.

2. Symfony Integration:

   • Dependency Injection: Inject DiscogsClientInterface into services:

     public function __construct(private DiscogsClientInterface $discogs) {}
     

   • Configuration: Use Symfony’s config/packages/discogs.yaml for settings like API keys and rate limits.

3. Authentication:

   • Personal Access Tokens (PAT):

     # config/packages/discogs.yaml
     discogs:
         auth:
             token: '%env(DISCOGS_PAT)%'
     

   • OAuth 1.0a: Built-in support without external libraries.

4. Rate Limiting: Integrate with Symfony’s RateLimiter component for granular control:

   discogs:
       rate_limiter:
           enabled: true
           limit: 30
           interval: '1 minute'
   

Common Use Cases

• Searching:

  $results = $client->searchDatabase('The Beatles', 'master');
  

• Bulk Operations: Use pagination parameters (e.g., listReleases(['page' => 1, 'per_page' => 50])).

Gotchas and Tips

Pitfalls

1. Breaking Changes:

   • Method Names: All 60 methods now use verb-first naming (e.g., getArtist instead of artistGet). Update all calls.
   • Parameters: Array parameters are replaced with typed, named arguments. Example:

     // Old (v3.x)
     $client->listReleases(['page' => 1]);
     
     // New (v4.0.0)
     $client->listReleases(page: 1);
     

2. Configuration:

   • The config/packages/discogs.yaml structure is simplified but may differ from v3.x. Review the UPGRADE.md for specifics.

3. Rate Limiting:

   • The legacy throttle system is removed. Ensure Symfony’s RateLimiter is configured if using custom limits.

Debugging

• IDE Support: Use PHPStan Level 8 for static analysis to catch type mismatches early.
• Logging: Enable Symfony’s monolog for API request/response logging:

  monolog:
      handlers:
          discogs:
              type: stream
              path: "%kernel.logs_dir%/%kernel.environment%.discogs.log"
              level: debug
  

Extension Points

1. Custom Clients: Extend DiscogsClient to add domain-specific methods:

   class CustomDiscogsClient extends DiscogsClient {
       public function getTopReleases(int $year): array {
           return $this->listReleases(['year' => $year, 'sort' => 'released', 'order' => 'desc']);
       }
   }
   

2. Event Listeners: Use Symfony’s event dispatcher to intercept API calls (e.g., for caching or analytics):

   $dispatcher->addListener(DiscogsEvents::REQUEST, function (DiscogsRequestEvent $event) {
       // Pre-process request
   });
   

3. Testing: Mock DiscogsClientInterface for unit tests:

   $mock = $this->createMock(DiscogsClientInterface::class);
   $mock->method('getArtist')->willReturn(['id' => 123456, 'name' => 'Test Artist']);