Setlistfm Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require nucleos/setlistfm
   

   Add the service provider to config/app.php under providers:

   Nucleos\Setlistfm\SetlistfmServiceProvider::class,
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Nucleos\Setlistfm\SetlistfmServiceProvider" --tag="config"
   

   Set your API key in .env:

   SETLISTFM_API_KEY=your_api_key_here
   

3. First Use Case: Fetching an Artist

   use Nucleos\Setlistfm\Setlistfm;
   
   $setlistfm = app(Setlistfm::class);
   $artist = $setlistfm->artist()->find('radiohead');
   dd($artist->name); // Output: Radiohead
   

Implementation Patterns

Common Workflows

1. Artist Data Retrieval

   // Get all albums by an artist
   $albums = $setlistfm->artist()->find('radiohead')->albums;
   
   // Get a specific album
   $album = $setlistfm->album()->find('radiohead', 'ok-computer');
   

2. Setlist Fetching

   // Get all setlists for an album
   $setlists = $setlistfm->album()->find('radiohead', 'ok-computer')->setlists;
   
   // Get a specific setlist by ID
   $setlist = $setlistfm->setlist()->find(123456);
   

3. Track Data

   // Get tracks from a setlist
   $tracks = $setlist->tracks;
   foreach ($tracks as $track) {
       echo $track->name . " (" . $track->duration . ")\n";
   }
   

4. Pagination

   // Paginate setlists (e.g., for large datasets)
   $setlists = $setlistfm->artist()->find('radiohead')->setlists()->paginate(10);
   

Integration Tips

• Caching Responses Cache API responses to reduce calls (e.g., using Laravel's cache):

  $artist = Cache::remember("setlistfm_artist_radiohead", now()->addHours(1), function() {
      return $setlistfm->artist()->find('radiohead');
  });
  

• Error Handling Wrap API calls in try-catch blocks:

  try {
      $artist = $setlistfm->artist()->find('nonexistent_artist');
  } catch (\Nucleos\Setlistfm\Exceptions\NotFoundException $e) {
      abort(404, 'Artist not found');
  }
  

• Rate Limiting Monitor API rate limits (Setlist.fm allows 100 requests/day for free tier). Log requests or use a queue system for batch operations.

• Symfony 8 Compatibility New in 3.6.0: The package now officially supports Symfony 8 components, which may be useful if your project integrates with Symfony tools or uses Symfony's HTTP client/Contracts. Ensure your Laravel version (8.0+) and dependencies are compatible, especially if leveraging Symfony's ecosystem.

Gotchas and Tips

Pitfalls

1. API Key Validation The package does not validate the API key on initialization. Always verify responses for 401 Unauthorized errors. Example:

   if ($artist->httpStatus === 401) {
       throw new \RuntimeException("Invalid API key");
   }
   

2. Case Sensitivity Artist/album names are case-sensitive in queries. Use lowercase for consistency:

   $artist = $setlistfm->artist()->find('Radiohead'); // May fail
   $artist = $setlistfm->artist()->find('radiohead'); // Works
   

3. Missing Data Some fields (e.g., venue, location) may be null if not provided by Setlist.fm. Handle gracefully:

   $venue = $setlist->venue ?? 'Unknown venue';
   

4. Symfony Dependency Conflicts New in 3.6.0: If your project uses Symfony components (e.g., HTTP client, contracts), ensure they are updated to v8.x to avoid compatibility issues. Run:

   composer require symfony/http-client symfony/contracts
   

Debugging

• Enable Debug Mode Set debug to true in config/setlistfm.php to log raw API responses:

  'debug' => env('SETLISTFM_DEBUG', false),
  

• HTTP Client Inspection Use Laravel's HTTP client middleware to inspect requests/responses:

  $setlistfm->getHttpClient()->tap(function ($client) {
      $client->withOptions(['debug' => true]);
  });
  

Extension Points

1. Custom Endpoints Use the underlying HTTP client to call undocumented endpoints:

   $response = $setlistfm->getHttpClient()->get('https://api.setlist.fm/rest/1.0/search/setlists', [
       'artistName' => 'radiohead',
       'apiKey' => config('setlistfm.api_key'),
   ]);
   

2. Model Binding Bind Setlist.fm models to Eloquent for seamless ORM integration:

   use Illuminate\Database\Eloquent\Model;
   
   class Setlist extends Model {
       public function getArtistAttribute() {
           return $this->artist ?? $this->setlist->artist;
       }
   }
   

3. Event Listeners Dispatch events for critical actions (e.g., after fetching a setlist):

   event(new \Nucleos\Setlistfm\Events\SetlistFetched($setlist));
   

4. Symfony Integration New in 3.6.0: Leverage Symfony 8 compatibility for advanced use cases, such as:

   • Integrating with Symfony's HTTP client for custom requests.
   • Using Symfony's event dispatcher if your application bridges Laravel and Symfony ecosystems. Example:

   use Symfony\Contracts\HttpClient\HttpClientInterface;
   
   $symfonyClient = app(HttpClientInterface::class);
   $response = $symfonyClient->request('GET', 'https://api.setlist.fm/...');