Setlistfm Bundle Laravel Package

Getting Started

• This is a Symfony bundle for the setlist.fm API, not a Laravel-native package. In Laravel, expect to register/bind the underlying client or service manually rather than relying on Symfony bundle auto-configuration.
• 1.4.0 requires PHP 8.3+ because PHP 8.2 support was dropped. Confirm your app/runtime before upgrading.
• Look first at the bundle’s DI extension/config tree for the API key option and exposed client/service. Then check the underlying setlist.fm client class/interface you will inject in Laravel.
• Minimal Laravel setup:
  1. Require nucleos/setlist-fm-bundle:^1.4.
  2. Add SETLISTFM_API_KEY to .env and expose it via config/services.php.
  3. Bind the client/service as a singleton or scoped instance in AppServiceProvider.
  4. Inject it into a controller, job, or app service.
• First use case: fetch an artist’s recent setlists and render them in a controller. Keep the API call behind an app-level service so you can cache, retry, and test it.

Implementation Patterns

• Wrap the package client in an application service such as SetlistFmService or ArtistSetlistRepository. Controllers and Livewire/Inertia endpoints should depend on your service, not the bundle/client directly.
• Register the client in the container with config-driven API credentials. Use a singleton for normal request usage, but be careful with long-running workers if the client holds mutable state.
• For sync/import workflows, dispatch queued jobs. Cache artist lookups and setlist responses; setlist.fm data changes slowly enough that short TTL caching is usually safe.
• Apply Laravel’s RateLimiter or a queue throttle around outbound calls. Handle 429 responses with backoff and avoid retrying non-idempotent operations blindly.
• Normalize external responses into your own DTOs/arrays before passing them to views. This isolates your app from API shape changes and missing fields.
• Paginate explicitly. Search and setlist endpoints are likely paginated; expose page/per-page parameters in your app service and cache per page.
• In tests, bind a fake implementation of your wrapper or use Laravel’s HTTP fake if the client uses Guzzle/HTTP under the hood. Do not hit the real API in the test suite.
• Upgrade workflow for 1.4.0: bump the dependency, run composer why-not php 8.3/platform checks, run the test suite, and smoke-test one real API call in staging.

Gotchas and Tips

• PHP 8.2 is no longer supported in 1.4.0. Despite being a minor release, this is a practical compatibility break. If your Laravel app is still on PHP 8.2, stay on ^1.3 or upgrade PHP first.
• Symfony bundle vs. Laravel: bundle service definitions, autowiring, and config loading will not work the same way in Laravel. Plan for explicit container bindings or use the standalone client package if one is available.
• API key handling: keep the setlist.fm key out of source control and config caches. Confirm the exact header/config key expected by the underlying client, and fail fast at boot or first use if it is missing.
• External API reliability: setlist.fm can return empty setlists, partial artist data, and rate-limit responses. Treat “no setlists found” as a normal empty state, not an exception.
• Pagination and caching: cache by artist + page + parameters. A naive cache key can mix search results or stale pages.
• Long-running workers: if you use Octane or queue workers, verify whether the client is safe to reuse. If not, bind it as a scoped/transient service or refresh credentials per job.
• Release scope: 1.4.0 contains dependency/tooling updates and CI cleanup only. There are no new runtime features to adopt. PHPUnit 12, PHPStan 2, and removal of Psalm/Infection affect contributors/CI, not normal Laravel runtime usage.
• Extension points: use the package’s client interface or HTTP client abstraction, if exposed, to inject custom Guzzle middleware for logging, retries, and correlation IDs. Otherwise wrap the package in your own adapter and keep all customization there.