Music Laravel Package

Getting Started

The v1.2.0 release confirms what this package is for: it is the Laravel-side controller for a local spotifyd speaker — the daemon that makes your app's host appear as a Spotify Connect target. It is not a Web API client. It shells out to / supervises a local process and then drives playback through Connect.

First steps:

1. composer require the package, then publish its config (php artisan vendor:publish --tag=...) and read the spotifyd block first — binary path, config path, device name, cache/credentials paths, and any supervisor/restart keys are the ones you will actually touch.
2. Confirm the host can run spotifyd at all before writing app code: binary present, --no-daemon vs daemon mode understood, credentials cached, and the device visible to a phone's Spotify Connect picker. Almost every "package bug" is a host problem.
3. First use case: a single artisan command or job that ensures the daemon is up and starts a playlist on the named device. Wire that behind a route or scheduled task and you have the skeleton of every later feature.

Because there is no prior assessment on record, treat this as the baseline. The one release note we have (v1.2.0) is a resilience fix, not an API change — nothing to migrate.

Implementation Patterns

Supervised local daemon, app-driven playback. The package's core competency is the local process lifecycle. Keep the daemon as a long-lived service (systemd unit, supervisor, or the package's own start/stop calls) and let your app issue intent ("play this", "resume") rather than owning the process. v1.2.0 is aimed squarely at this: on play/resume the package now restarts a dead local spotifyd even when Connect still advertises the speaker in its device list. That stale-listing condition is the classic failure mode for local Connect targets — the speaker looks alive because the account-level directory caches it, but nothing is listening on the host.

Wrap playback in a job, not a controller. Anything that touches process state or waits for device registration belongs in a queued job with retries and a timeout. Controllers should dispatch and return. play/resume now can trigger a restart internally, which adds seconds of latency you do not want in a request cycle.

Prefer "ensure up, then act" over "check, then act." Because v1.2.0 makes play/resume self-healing, the idiomatic pattern is a single idempotent call — play(track) — rather than your own isDeviceAlive() guard followed by a play. Your guard will read the Connect device list, which is exactly the list that lies. Duplicating the availability check in application code reintroduces the bug the release fixed.

Scheduled heartbeat. A everyFiveMinutes task calling a cheap resume/ensurePlaying on the local device is the standard integration for "always-on office/venue speaker" apps. With v1.2.0 this doubles as a watchdog: a dead daemon gets restarted by the heartbeat instead of sitting silently until someone notices.

Fakes and test doubles. For tests, bind a fake of whatever contract fronts the package (facade fake or container swap) so CI never spawns a real daemon. Assert on the intent — "resume was requested for device X" — not on process state. Keep one narrow integration test, tagged and excluded from default runs, that exercises a real binary on a machine that has one.

Events and logging are your observability seam. If the package fires lifecycle events (started, restarted, failed, playback changed), listen and forward to your log/alerting channel. The restart behaviour added in v1.2.0 is invisible unless you instrument it — you want to know how often the speaker is dying, not just that playback recovered.

Gotchas and Tips

• "Connect lists the speaker" is not a health check. This is the whole point of v1.2.0. A device can appear in GetDevices/the app picker while the local daemon is dead. Never build readiness logic on device enumeration alone; rely on the package's play/resume path or probe the host directly.
• The restart is implicit, so budget for the latency. A play that previously failed fast now blocks for the length of a daemon restart plus Connect re-registration. Set queue job timeouts generously (tens of seconds, not the default 60s if you also do playlist resolution) and set $tries/backoff so a genuinely dead speaker fails cleanly instead of hammering.
• Restart loops hide misconfiguration. If the daemon dies immediately on every start (bad credentials cache, wrong audio backend, missing device permissions), v1.2.0 will dutifully restart it on every play and you will see "playback works sometimes" instead of a hard error. Watch for repeated restarts in logs and treat high restart frequency as a config alarm, not normal.
• Process supervision vs. package restarts. Two supervisors fighting over one daemon is a bad time. Pick one: either systemd/supervisor owns the process and you disable the package's start/stop, or the package owns it and your system unit stays out of the way. Decide before you deploy.
• Config paths are per-user and per-host. spotifyd config, credential/cache directories, and the socket/port it binds resolve relative to the user running PHP-FPM or the queue worker — often not the user you tested with in a shell. Check whoami inside the job when the local daemon "works manually but not from the app."
• One daemon per device name. Running multiple instances with colliding device_name/port values produces flapping Connect entries and confusing restart behaviour. Namespace device names per environment (myapp-staging-speaker).
• Extension points to prefer: the playback/process contract (swap it for a fake or a remote-host implementation), the config file (binary path, restart policy, timeouts), and lifecycle events. Avoid subclassing internals; if you need custom restart policy, wrap the package rather than patching the daemon call.
• Debugging order when playback fails: 1) is the binary runnable as the web/queue user, 2) does a manual spotifyd --no-daemon start on that host, 3) do credentials still resolve, 4) is playback failing or is it the device registration that is failing. v1.2.0 only covers step 4's most common cause; if restarts are firing and playback still fails, you are at step 1 or 3.