Setlistfm Bundle Laravel Package

Technical Evaluation

NucleosSetlistFmBundle is a Symfony bundle wrapping the setlist.fm API — it is not a Laravel-native package. It ships a DI extension, service definitions, and typically relies on Symfony's HTTP client, serializer, and cache contracts. In a Laravel application it can only be consumed as a library (or via a third-party bridge); the bundle's service wiring will not auto-register the way laravel/framework package discovery expects. Architecture fit is therefore conditional: strong for Symfony applications, weak-to-moderate for Laravel unless the team is prepared to manually bind the underlying setlist.fm client and its dependencies.

The 1.4.0 release is primarily tooling churn (PHPUnit 12, PHPStan 2, removal of Psalm and Infection, CI cleanup) with one material change: PHP 8.2 support was dropped. Labeled a minor feature release, but dropping a runtime version is a breaking change for any consumer still on PHP 8.2. That is the single line item that matters to a production team. The PHPStan v2, PHPUnit v12, and removed-statics/infection changes are internal to the maintainers' pipeline and should not affect consumers at runtime, though they do signal a shrinking quality gate (no mutation testing, no Psalm static analysis in CI).

Technical risks:

• SemVer deviation: PHP 8.2 removal in a 1.4.0 bump means composer update on a 1.x lockfile can silently break a PHP 8.2 environment. Composer will block installation via platform requirements, which is the saving grace, but dependency resolution errors are still a support burden.
• Reduced QA surface: removing Infection (mutation) and Psalm leaves PHPStan as the sole static gate. Acceptable for a thin API wrapper, but worth noting if the team's compliance bar expects mutation coverage.
• Symfony coupling: even as a non-bundle library, transitive Symfony contracts (HttpClient, Serializer, Cache) can conflict with a Laravel app's own dependency versions.
• API surface: setlist.fm's API is rate-limited and returns artist/setlist fixtures; the bundle's value is mostly serialization and endpoint encapsulation, both of which are easy to reimplement.

Key questions to answer before adoption: What PHP version is the target fleet on (8.3/8.4 required now)? Are we Symfony or Laravel? If Laravel — is there an existing wrapper we can maintain instead of the bundle? Do we need setlist.fm at all, or is a ~200-line HTTP client wrapping the two or three endpoints we care about the cheaper path (avoiding the Symfony dependency tree entirely)?

Integration Approach

Stack fit: Direct fit in a Symfony 6.4/7.x application using PHP 8.3+. In Laravel, treat this strictly as a library — pull the underlying client class, instantiate it via a Laravel service provider binding, and skip the bundle's Extension/Configuration entirely. Do not attempt to register it as a Symfony bundle inside Laravel; the container bridge (nucleos/setlist-fm-bundle services) expects Symfony's DI compiler passes.

Migration path for existing 1.3.x consumers:

1. Confirm PHP runtime on all deployment targets. If any environment is on 8.2, pin nucleos/setlist-fm-bundle:1.3.* until the platform upgrade lands, or bump PHP first.
2. Run composer why-not nucleos/setlist-fm-bundle 1.4.0 in each consuming repo to surface platform blockers up front.
3. Upgrade in a branch, run the app's test suite, then merge. No code-level migration is expected — no public API changes are documented in 1.4.0.
4. Expect a Composer dependency-graph bump (PHPStan 2, PHPUnit 12) if those tools are dev dependencies of the consuming project and share the lockfile.

Compatibility: Laravel teams should validate that any pinned Symfony packages (HttpClient, Serializer) satisfy the bundle's composer.json constraints alongside Laravel's own. In practice, Laravel 10/11 pull Symfony components of compatible majors, but the intersection is worth a composer update --dry-run audit.

Sequencing:

• Phase 1 (1 sprint): Runtime audit — confirm PHP 8.3+ across environments; if not, freeze at 1.3.x and schedule the PHP upgrade.
• Phase 2: Spike a 1-day evaluation — implement the two or three setlist.fm calls we actually need using the package in a sandbox, compare to the raw API. This determines whether the bundle earns its dependency footprint.
• Phase 3: If adopted, wrap in a Laravel service provider (or Symfony bundle config) behind a thin internal interface so the dependency is swappable.
• Phase 4: Roll out with integration tests against the setlist.fm sandbox or fixtures; add a circuit breaker for the external API.

Operational Impact

Maintenance: Low-frequency, low-complexity package (a thin API wrapper), maintained by a single primary contributor (@core23) with Renovate bot assistance. Bus-factor risk is real: a solo-maintainer package with irregular releases is fine for a non-critical integration but should not be on a critical path without a fork-and-patch contingency. 1.4.0 signals healthy hygiene (PHPStan v2, PHPUnit 12, CI cleanup) but also consolidation toward a single static tool and reduction of the QA suite (no Infection, no Psalm) — acceptable for wrapper code, but the team should not assume as strong a quality gate as before.

Support: GitHub issues and PRs only; no vendor SLA. For Laravel users, upstream support will assume a Symfony context, so framing questions carefully ("how do I bind X in a non-Symfony container") is a self-service exercise. Budget for owning the Laravel wiring yourself.

Scaling: The bundle itself is stateless — scaling is a function of setlist.fm's API rate limits and HTTP client concurrency. Ensure connection pooling/reuse and per-instance client reuse; do not instantiate per request in a hot path. In a queue-worker context (the natural place for these outbound calls), throughput is bound by setlist.fm, not the package, so scaling concerns belong to the calling layer, not this dependency.

Failure modes:

• Platform mismatch: Composer resolves and fails at install time on PHP 8.2 — visible, loud, and easy to roll back. Low blast radius if caught in CI.
• Transitive Symfony conflict: more insidious — a composer update for another package could shift Symfony versions and break the bundle's service wiring at runtime, not install time. Mitigate with a lockfile policy and a smoke test in staging.
• Upstream API change: setlist.fm's API is versioned but has historically evolved; an unmapped field or endpoint deprecation would surface as a deserialization failure. Wrap calls behind an internal interface so a swap to a hand-rolled client is a one-file change.
• Rate-limit saturation: in bulk backfills, expect 429s. The package does not inherently implement backoff — verify and add retry/backoff in the calling code.

Ramp-up: Trivial for a Symfony engineer (half a day to wire, configure, and test against fixtures). Moderate for a Laravel engineer (one to two days, mostly spent mapping the container wiring and validating the Symfony transitive dependencies). The 1.4.0 release itself adds no new API surface to learn; the ramp-up cost is unchanged from 1.3.x, subject to the PHP 8.3+ prerequisite. Documentation is standard Symfony bundle docs — expect to lean on the underlying client class source rather than prose for the Laravel path.