Setlistfm Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require nucleos/setlistfm-bundle
   

2. Enable the Bundle in config/bundles.php:

   return [
       // ...
       Nucleos\SetlistFmBundle\NucleosSetlistFmBundle::class => ['all' => true],
   ];
   

3. Configure API Credentials in .env:

   SETLISTFM_API_KEY=your_api_key_here
   SETLISTFM_API_SECRET=your_api_secret_here
   

4. First Use Case: Fetch an artist’s setlists in a controller:

   use Nucleos\SetlistFmBundle\Service\SetlistFmService;
   
   class ArtistController extends AbstractController
   {
       public function showSetlists(SetlistFmService $setlistFmService, string $artistName)
       {
           $artist = $setlistFmService->getArtistByName($artistName);
           $setlists = $setlistFmService->getSetlistsByArtist($artist->getId());
   
           return $this->render('artist/setlists.html.twig', [
               'setlists' => $setlists,
           ]);
       }
   }
   

Implementation Patterns

Core Workflows

1. Artist Lookup & Setlists:

   // Fetch artist by name (with fallback to ID)
   $artist = $setlistFmService->getArtistByName('Radiohead');
   // OR
   $artist = $setlistFmService->getArtistById(12345);
   
   // Get setlists with optional filters
   $setlists = $setlistFmService->getSetlistsByArtist($artist->getId(), [
       'limit' => 10,
       'sort' => 'date',
   ]);
   

2. Event Details:

   $event = $setlistFmService->getEventById($eventId);
   $set = $setlistFmService->getSetById($setId);
   $tracks = $setlistFmService->getTracksBySet($setId);
   

3. Caching: Enable caching via config (config/packages/nucleos_setlistfm.yaml):

   nucleos_setlistfm:
       cache: true
       cache_lifetime: 3600  # 1 hour
   

Integration Tips

• Twig Integration: Extend Twig with custom filters for formatting dates/venues:

  {{ setlist.event.venue.name|setlistfm_venue_name }}
  

• Event Subscribers: Listen for setlistfm.api.response events to log API calls or transform responses:

  public static function getSubscribedEvents()
  {
      return [
          'setlistfm.api.response' => 'onApiResponse',
      ];
  }
  

• Dependency Injection: Prefer injecting SetlistFmService over creating clients directly for consistency.

Gotchas and Tips

Pitfalls

1. Rate Limiting:
   • Setlist.fm enforces 100 requests/hour for free accounts. Cache aggressively or implement exponential backoff:

     $setlistFmService->setRateLimitHandler(function () {
         throw new \RuntimeException('Rate limit exceeded. Retry later.');
     });
     

2. API Key Validation:
   • The bundle does not validate keys on install. Test with a dummy key early to catch misconfigurations:

     php bin/console debug:container nucleos_setlistfm.client
     

3. Pagination:
   • Use getSetlistsByArtist() with offset/limit for pagination. Avoid fetching all records at once:

     $setlists = $setlistFmService->getSetlistsByArtist($artistId, ['limit' => 50, 'offset' => 0]);
     

Debugging

• Enable API Logging:

  nucleos_setlistfm:
      debug: true
  

  Logs appear in var/log/dev.log (Symfony’s default).

• Common Errors:

  • InvalidArtistException: Verify artist names match Setlist.fm’s database (e.g., "The Beatles" vs. "Beatles").
  • AuthenticationException: Double-check .env credentials and API key permissions.

Extension Points

1. Custom Responses: Override the default SetlistFmResponse class to add fields or transform data:

   // src/Service/CustomSetlistFmResponse.php
   class CustomSetlistFmResponse extends SetlistFmResponse
   {
       public function getFormattedDate(): string
       {
           return $this->event->date->format('Y-m-d');
       }
   }
   

   Bind it in services.yaml:

   Nucleos\SetlistFmBundle\Service\SetlistFmService:
       arguments:
           $responseClass: App\Service\CustomSetlistFmResponse
   

2. API Client Extensions: Extend the underlying SetlistFm\Client for custom endpoints:

   use Nucleos\SetlistFmBundle\Client\SetlistFmClient;
   
   class CustomSetlistFmClient extends SetlistFmClient
   {
       public function getCustomEndpoint(string $endpoint, array $params = [])
       {
           return $this->request('GET', $endpoint, $params);
       }
   }
   

   Register it in services.yaml:

   Nucleos\SetlistFmBundle\Service\SetlistFmService:
       arguments:
           $client: '@custom_setlistfm.client'
   

3. Testing: Mock the service in PHPUnit:

   $mockService = $this->createMock(SetlistFmService::class);
   $mockService->method('getArtistByName')
       ->willReturn(new Artist(['id' => 123, 'name' => 'Test Artist']));