rikudou/unleash-sdk-bundle
Symfony bundle for integrating the Unleash PHP SDK into your application. Configure the Unleash client, register it as a service, and evaluate feature flags and strategies using Symfony configuration and dependency injection. Supports context-aware toggles and clean service wiring for gradual rollou...
Architecture fit. This is a Symfony bundle, not a Laravel package, and the distinction drives the entire assessment. It wraps the Unleash PHP client SDK and integrates it into Symfony's DI container, configuration tree, and event system. For a Laravel-first shop, the bundle is a reference implementation, not a drop-in dependency: the valuable asset is the underlying unleash/client-sdk-php engine plus the protocol semantics this bundle demonstrates (registration, /client/features polling, metrics flushing, backup-file fallback, context/strategy evaluation). Critically, "implementing the Unleash server protocol" refers to the client protocol — adopting this package still requires an Unleash server (self-hosted or Unleash Cloud) as a runtime dependency. That is a platform commitment, not a library install.
Integration feasibility. Straightforward for Symfony services; a deliberate build for Laravel. In Laravel you would bind the SDK client as a singleton in a service provider, map config/unleash.php to a Laravel config file, wire a PSR-6/PSR-16 cache adapter (Laravel's cache repository satisfies PSR-16) and a PSR-18 HTTP client (Laravel's HTTP client is not PSR-18 out of the box; Guzzle or Symfony HttpClient is). None of this is hard, but it is our code to own. Estimated effort: 2–4 days for a competent PHP engineer to reach parity with the bundle's behavior, plus tests. Note the project publishes very frequently (v0.12.182 → v0.12.285 in a short window), so pin to a specific tag rather than floating.
Technical risk. Primary risk is ecosystem thinness: 37 stars and zero dependents means no organic battle-testing and no community backstop. Mitigating factors: MIT license, first-party ownership by the Unleash org, and a small, well-understood surface. Secondary risks: bundle-level coupling to Symfony's DI/config conventions means fork maintenance grows if we adapt rather than reimplement; and flag-evaluation correctness is on the hot path for user-facing behavior, so caching and fallback semantics need explicit testing rather than inherited trust. The Symfony version-lag concern is materially reduced as of v0.12.285 — the maintainers added Symfony 8 support — signalling the package is tracking current framework releases rather than drifting. That does not validate the SDK's behaviour, only that the integration surface is maintained.
Key questions.
Stack fit. Poor-to-moderate as a direct dependency; good as a design donor. In a pure Laravel monolith, use unleash/client-sdk-php directly behind our own FeatureFlag contract interface, then implement a thin adapter. In a polyglot PHP estate with a Symfony service alongside Laravel (common after acquisitions or in a shared composer monorepo), the case for this bundle improves markedly: adopt it natively in Symfony, mirror the config shape in Laravel so the two services behave identically. Symfony 8 support in v0.12.285 removes a blocker for teams upgrading to the next Symfony LTS.
Migration path. Do not migrate off anything on day one. Sequence: (1) introduce the interface and a NullFlag/config-based implementation that reads from config/features.php or env vars — this is pure refactor, zero new infrastructure; (2) land the Unleash-backed implementation behind the same interface; (3) flip individual flags from static config to Unleash one at a time; (4) delete the static fallback once flags are proven. This keeps the blast radius per flag and lets us defer the platform decision.
Compatibility. Expect and verify: PHP 8.1+ (confirm the SDK's floor against our oldest running service), Symfony 6/7/8 if we use the bundle (Symfony 8 gated at v0.12.285), PSR-18 HTTP client, PSR-6 or PSR-16 cache, and PSR-3 logger. Laravel 10/11 ship PSR-16-compatible cache and PSR-3 logging, so the gaps are HTTP client binding and the config/DI translation. Pin versions explicitly — rapid patch releases (the ~100-patch jump to v0.12.285 is typical of this project) mean our lockfile is the real compatibility statement. Note the Symfony bundle's config keys differ from what we'd write idiomatically in Laravel; documenting the mapping prevents drift between services.
Sequencing. Weeks 1–2: platform decision and Unleash environment provisioning (dev/staging/prod, API tokens scoped per environment, never in VCS). Weeks 2–3: interface + static implementation, shipped and released as a no-op. Weeks 3–4: Unleash adapter, unit tests for strategy evaluation and fallback, integration test against a stubbed Unleash endpoint. Week 5: pilot on two or three low-risk flags (log verbosity, a non-critical UI variant). Weeks 6+: expand to release gating and kill switches, with a written flag-creation checklist before any engineering-wide rollout.
Maintenance. Vendor-owned but thinly staffed in practice. Two maintenance surfaces: the SDK dependency (upgrade on our normal cadence, watch for PHP/Symfony floor changes) and, if we adapt the bundle, our own adapter code (~200–400 lines plus tests). Budget a recurring half-day per quarter for dependency and Unleash-version compatibility review. The zero-dependents figure means we will not benefit from others discovering breakage first — our CI must be the canary. Offset by an active release stream: Symfony 8 support landed promptly, so framework-upgrade friction is lower than the raw star count suggests.
Support. Community-only: GitHub issues, no commercial SLA unless we purchase Unleash Enterprise (which shifts server support, not PHP SDK support). Escalation path for SDK bugs is "open an issue and vendor a patch." For a load-bearing kill-switch path, that is a real limitation; mitigate by keeping the fallback path dependency-free so a broken SDK can be reverted to static config within one deploy.
Scaling. Evaluation is in-process and cheap once flags are cached; the cost concentrates in polling. Poll interval × replica count determines Unleash server QPS — 15s across 50 replicas is ~3.3 req/s, tolerable, but autoscaling churn multiplies it. Use a shared cache (Redis) with the SDK's cache abstraction so replicas share one fetch rather than N, and enable the backup file so cold starts and restarts degrade to disk rather than blocking. Metrics flushing adds a second periodic call; sample or disable if not consuming the data. Unleash itself is stateless behind Postgres, so horizontal scaling is the vendor's problem, not ours.
Failure modes. (1) Unleash unreachable at boot — mitigated by cache + backup file; without them, startup latency or evaluation errors. (2) Stale cache serving a retired flag as on/off — needs a documented TTL and an emergency "all defaults" env override. (3) Token misconfiguration across environments causing dev flags in prod — enforce per-env tokens and a startup assertion. (4) Toggle debt: flags never removed, becoming undocumented config with a UI. This is the most likely real failure and it is organizational, not technical. (5) Partial rollout inconsistency during a canary — expected, but must be explained to QA. (6) SDK evaluation exception on an unusual context shape — wrap every evaluation in a try/catch returning the default. (7) Rapid patch cadence means a pinned version is essential; skipping the pin risks an untested minor bump landing via composer update.
Ramp-up. Engineering: low — a Laravel developer comfortable with service providers is productive in a day; the conceptual load is feature-flag discipline, not the API. Platform/SRE: moderate — someone must own Unleash deployment, upgrades, backups, and token rotation, or we buy Cloud and shrink this to configuration. Product/QA: highest relative cost — teams need a shared vocabulary for rollout percentages, targeting context, and cleanup ownership. Recommend a single "flag steward" role and a hard rule that every flag has an owner and an expiry date at creation time; without that, the tool's convenience outruns its governance within two quarters.
How can I help you explore Laravel packages today?