Weave Code
Client Laravel Package
unleash/client
PHP client for Unleash, the open-source feature flag service. Evaluate toggles and activation strategies in PHP applications to support gradual rollouts, A/B tests, and kill switches, with framework-friendly integration for Laravel projects.
Unleash Client is a PHP SDK for integrating Unleash, the open-source feature toggle service, into PHP applications. It fetches toggle configurations from an Unleash server and evaluates feature flags locally, enabling gradual rollouts, A/B testing, and kill switches without redeploying.
- Lightweight, framework-agnostic PHP client
- Local feature flag evaluation with configurable refresh and caching
- Supports activation strategies, variants, and user/context targeting
- Easy integration with Laravel, Symfony, and other PHP frameworks
- Robust error handling and fallback behavior
Frequently asked questions about Client
- How do I install the Unleash PHP SDK (unleash/client) in a Laravel app?
- Install it with composer require unleash/client, then bind the Unleash client as a singleton in a service provider, supplying a PSR-18 HTTP client such as Guzzle, a PSR-16 cache, and a PSR-3 logger. There is no publishable config file, so the API URL, token, and environment go into config/services.php or a dedicated config file you write yourself. The whole integration is roughly 40 lines of glue.
- Is there an official Laravel package, service provider, or facade for Unleash?
- No. unleash/client is a framework-agnostic PHP SDK and ships no service provider, facade, Blade directive, or testing fake. You write that glue yourself, which effectively makes it a small internal package with its own tests that you must maintain across SDK upgrades.
- Does unleash/client work with Laravel's cache repository?
- Not directly, because the SDK expects a PSR-16 SimpleCache implementation and Laravel's cache repository does not implement Psr\SimpleCache\CacheInterface. You either add a thin adapter or point the SDK at a dedicated cache store. Choose deliberately, since the cache is the only thing preventing every PHP-FPM worker from polling Unleash independently.
- How often does the Unleash PHP SDK poll, and does it add latency to each request?
- The SDK polls the /client/features endpoint on a roughly 30-second interval and keeps a feature-toggle snapshot, evaluating strategies locally against a context object. There is no per-request network hop in the hot path, so evaluation is cheap and deterministic once the snapshot is cached. Usage metrics are reported back on a separate cadence.
- How do I target specific users and read variants with unleash/client?
- Pass a context object containing userId, sessionId, IP, environment, and any custom properties into the enablement check, and the strategies are evaluated locally against it. Variants resolve from the same context, so gradual rollouts and weighted experiments work without extra infrastructure. Custom properties are handy for things like plan tier or tenant ID.
- How do I test code that depends on Unleash feature flags in Laravel?
- The SDK does not ship a testing fake, so the usual approach is to define a small interface, bind it in the container, and swap in a fake during tests. Alternatively you can bind a preconfigured Unleash instance backed by a stubbed cache. Keeping flag checks behind a thin wrapper instead of scattering the SDK across the codebase makes both testing and later replacement much easier.
- What happens when Unleash is unreachable and the cache is cold?
- Evaluation falls back silently to each flag's default value. If that default is false on an authorization-relevant flag you have an outage, and if it is true you may have a security hole. Decide fail-open versus fail-closed per flag and encode that decision explicitly rather than inheriting it from a default argument.
- Does unleash/client work with Laravel Octane, Swoole, or long-running queue workers?
- It works, but the behaviour needs a deliberate design. Under Octane or a long-running worker, a singleton SDK instance holds its snapshot in memory for the life of the process, so toggle changes are not instantly visible and memory is not reclaimed. That is acceptable for polling-based propagation, but it should be a documented decision rather than an accident.
- Which PHP versions does unleash/client support, and what dependencies does it pull in?
- The SDK is PSR-compliant and targets modern PHP, so check the composer.json in the Unleash/unleash-php-sdk repository for the exact version constraint before committing. It requires the PSR-17 and PSR-18 interfaces plus a concrete HTTP implementation. Guzzle is the path of least resistance since it is already transitively present in most Laravel applications, but verify version pinning against laravel/framework's HTTP client in a scratch branch.
- Is unleash/client mature enough for production, and what are the alternatives?
- It is the official server-side PHP SDK, so correctness risk is lower than its small community footprint suggests: roughly 65 GitHub stars and very few tracked dependents, which mainly raises the cost of troubleshooting, finding answers, and hiring people who have hit your exact bug. Support routes to GitHub issues plus whatever commercial tier you hold, and feature parity with the Node, Go, and Java SDKs often lags, so newer capabilities may not be available in PHP yet. Alternatives include LaunchDarkly, Flagsmith, or ConfigCat SDKs, or a homegrown database-backed toggle table.
Weaver
How can I help you explore Laravel packages today?