Unleash Sdk Bundle Laravel Package

Getting Started

Install via Composer and let Symfony Flex register the bundle (or add it manually to config/bundles.php):

composer require rikudou/unleash-sdk-bundle

As of v0.12.285 the bundle allows Symfony 8 alongside existing 6.4/7.x support, so a fresh Symfony 8 app can install it without a --with-all-dependencies fight or a version override. On older Symfony versions pin the bundle constraint explicitly.

Minimum viable configuration in config/packages/unleash.yaml:

unleash:
    url: '%env(UNLEASH_URL)%'
    api_token: '%env(UNLEASH_API_TOKEN)%'
    environment: '%env(UNLEASH_ENVIRONMENT)%'
    instance_id: '%env(UNLEASH_INSTANCE_ID)%'

Then set the matching UNLEASH_* entries in .env / your secrets store. The bundle wraps the Unleash\Client\Unleash class, so the first place to look is that class in unleash-client-php — the bundle's own source is thin and mostly covers DI, config tree definition, and optional integration points (Twig, context providers, profiler). Once installed, autowire Unleash\Client\Unleash into a controller or service and call:

public function checkout(Unleash $unleash): Response
{
    if ($unleash->isEnabled('new_checkout_flow')) {
        return $this->render('checkout/v2.html.twig');
    }
    return $this->render('checkout/legacy.html.twig');
}

That is the whole first-use case: one flag, one branch, zero ceremony. Everything else (context, variants, gradual rollout) is layered on top of that.

Implementation Patterns

Constructor injection, not container lookups. Autowire Unleash into the services that need it. Because the client is a fairly heavy object (it holds HTTP clients, cache pools, and feature snapshots), injecting it only where used keeps startup cheap and makes tests replaceable.

Build request-scoped context via a listener. Rather than threading user IDs through every isEnabled() call, register a kernel request listener (or the bundle's ContextProviderInterface if you're on the version that ships one) that constructs a Context from the authenticated user, session, and request IP. Store it in a request attribute or service, and have a thin FeatureFlags service that merges that context into every isEnabled() call. This is the single biggest ergonomic win — it turns flag checks into if ($this->flags->isEnabled('x')).

Wrap the SDK in a domain service. Create App\Feature\Flags with typed methods (canSeeNewDashboard(User $u): bool) instead of scattering string flag names. This gives you one place to change the flag name, one place to add caching/metrics, and one place to stub in tests. The bundle's DI aliasing lets you inject Unleash into that wrapper and nowhere else.

Use variants for multivariate flags. If you're doing A/B-style rollouts, $unleash->getVariant('flag_name', $context) returns a Variant with getName()/getPayload(), and isEnabled() returns true for variant-typed toggles. This is cleaner than a boolean plus a separate config lookup.

Twig extension for template-only flags. The bundle ships a Twig integration (or you can add one in ~20 lines). {% if unleash_is_enabled('new_banner') %} in templates avoids round-tripping through the controller for cosmetic toggles. Keep business-critical flags in the controller/service layer, not templates — template flags are hard to test.

Cache configuration matters more than you'd think. Under the hood the SDK stores the feature snapshot in a PSR-6 cache pool. Wire a cache.adapter.redis pool for the unleash.cache alias in production and cache.adapter.array in test. Without an explicit pool you'll be hammering the Unleash API every request on a cold container, which is painful in local dev and catastrophic in production.

Feature flags as deployment gates. A very common pattern with this bundle: gate new migrations/queues behind flags, deploy them dark, then flip per-environment. Because environment is a required config field, you get environment isolation "for free" by setting different env vars per deploy target.

Test with a fake, not the real client. The easiest testing pattern is to alias Unleash to your own FakeUnleash extending Unleash in config/services_test.yaml and control flag results in setUp(). Trying to hit a real Unleash instance in CI will make you hate the package quickly.

Gotchas and Tips

The SDK is "fail-open by default" — verify your defaults. When Unleash is unreachable, isEnabled() returns the $default you pass (default false unless configured otherwise). Decide deliberately per flag whether unreachable means on or off, because a network blip in production can silently disable a critical path.

The cache is the whole reliability story. If your cache pool is unavailable, the SDK falls back to its in-memory snapshot; if that's empty too, you get the default. Use a cache adapter with a TTL that matches the Unleash client refresh interval — otherwise you can serve stale flags for hours after flipping a toggle and think the bundle is broken.

environment is not optional and not derived. It must match what Unleash expects for that API token. If you copy .env between projects or forget to set it, flags will simply not appear (you'll get defaults, not an error), which is one of the most confusing failure modes.

The profiler collector (if present) is your debugging tool. When a flag returns the "wrong" value, check the Symfony profiler's Unleash panel to see the snapshot, the context that was sent, and whether the result came from cache, API, or in-memory fallback. This saves 90% of "why is this flag on/off" debug sessions.

Context is easy to forget. Users with isEnabled('x') but no Context get the anonymous/bucketing fallback — meaning a flag you toggled at 10% rollout will give them consistent-but-unrelated-to-their-user-ID behavior. If you care about sticky rollouts, always pass the same user identifier.

String flag names are a trap. The type system won't catch isEnabled('chckout_v2'). Centralize flag names as constants or a backed enum in your Flags service. This also gives you a single grep target when a flag is retired.

Pin a concrete version and read the changelog before composer update. The v0.12.182 → v0.12.285 gap is ~100 patch releases with only one PR called out in the notes, so the release page is not a reliable summary of everything that landed. The bundle historically lagged behind the PHP SDK's breaking changes, so pin rikudou/unleash-sdk-bundle to a known tag, verify the bundle's composer.json constraint against the unleash-client-php version you actually need, and check for Symfony 8 support when bumping the framework — v0.12.285 is the first release here explicitly allowing Symfony 8, so anything older will refuse to install on Symfony 8 regardless of what your other constraints say.

Extension points. The two useful ones: (1) PSR-6 cache pools under the bundle's configured alias, and (2) any ContextProvider / request-listener hook if the installed version offers one — register your own provider rather than editing vendor code when you need extra context fields. If neither is exposed, fall back to decorating the Unleash service with your own App\Feature\Flags wrapper, which is the clean extension seam regardless.

Local development. Point UNLEASH_URL at a mocked client (e.g. unleash-proxy in Docker) or override the Unleash service in services_dev.yaml with a alwaysEnabled() variant, otherwise your local dev is a coin toss on flags and every dev will have different behavior.