Symfony Client Bundle Laravel Package

Getting Started

This is the Symfony integration for Unleash, not a Laravel-native package. In a Laravel app you have two realistic entry points:

1. The plain PHP SDK (unleash/unleash-client) — the least friction for Laravel. Install it, bind Unleash\Client\Unleash as a singleton in a service provider, pull it via the container, and toggle on isEnabled('flag', $context).
2. This Symfony bundle — only worth it if you're running a Symfony app alongside Laravel, or you're deliberately mirroring a Symfony service stack. You'll register the bundle's services manually (it expects Symfony's DI, event dispatcher, and HTTP client contracts) or wire it through a small adapter service provider.

Minimum viable path with the PHP SDK:

composer require unleash/unleash-client

// AppServiceProvider::register()
$this->app->singleton(Unleash::class, fn () => new Unleash(
    new UnleaseBuilder()
        ->withUrl(config('services.unleash.url'))
        ->withInstanceId(config('services.unleash.instance_id'))
        ->withAppName(config('app.name'))
        ->withMetricsInterval(30000)
        ->build()
));

First use case: gate a single risky feature (new checkout, redesigned nav) behind $unleash->isEnabled('new-checkout', $context) and leave everything else untouched.

Look first at:

• The package README and UnleashBuilder / configuration reference for connection and metrics options.
• Unleash's strategy docs (gradual rollout, user IDs, custom constraints) — that's where the actual value lives.
• Your config/services.php and a dedicated config/unleash.php for env-driven setup.

Implementation Patterns

Context object per request. Unleash's killer feature is contextual evaluation. Build a UnleashContext from the authenticated user (or session/device ID for anonymous traffic) in a middleware, and inject it wherever flags are checked:

$context = (new UnLeashContext())
    ->setUserId((string) $request->user()?->id)
    ->setSessionId($request->session()->getId())
    ->setCurrentTime(Carbon::now());

Wrap flag checks in a small service. Don't scatter isEnabled() calls across controllers. Create App\Features\Flags with typed methods (isNewCheckoutEnabled(User $user)), so flags are testable, greppable, and easy to swap. Fake it in tests with an in-memory implementation — you do not want unit tests hitting the Unleash API.

Kill-switch pattern for migrations. Wrap risky deployments behind a flag: ship code dark, flip the flag in Unleash, monitor, then remove the branch. This is the single highest-value workflow for day-to-day use.

Blade + middleware integration. Resolve flags in middleware and share them via View::share('flags', $flags) or a @feature('new-checkout') Blade directive. Keep the evaluation server-side; never call Unleash from JS.

Gradual rollout. Use percentage strategies keyed on userId (or a stable session ID) so users get a consistent experience across requests. Don't key on request ID or timestamp — you'll get flicker.

Metrics and health. Configure the metrics interval and enable the SDK's built-in health check ($unleash->isEnabled('x') returning a default on failure). Register /health to report Unleash reachability if you gate critical paths on flags.

Symfony 8 note (v0.12.285). This release only broadens the Symfony constraint to ^8.0. For Laravel apps it's a forward-compatibility update: Laravel 11/12 ship Symfony 7.x components, so nothing changes functionally today. It matters if you're on Symphony 8 or plan to be — the bundle won't fight your dependency resolver. No config, API, or behavior changes.

Gotchas and Tips

• No Laravel auto-discovery for Symfony bundles. If you attempt to use this bundle in Laravel, you must register it manually and provide the Symfony service contracts it expects. In practice this is more work than using the PHP SDK directly. Prefer the SDK.
• Symfony 8 means PHP 8.4+. If you're on Laravel 12 with PHP 8.2/8.3, this release is a no-op for you — but it also means future bundle versions may require newer PHP. Pin your constraints and read the changelog before composer update.
• Flags fail open by default. If Unleash is unreachable and you haven't configured a fallback, isEnabled() returns the default you passed. Set explicit, safe defaults per flag — don't rely on the SDK guessing.
• Don't check flags in loops. Each isEnabled() can hit the local cache but context building is your cost. Build context once per request; batch-evaluate.
• Cache and metrics timing. The SDK caches the feature toggle payload (default ~30s) and posts metrics on an interval. In long-running workers (queues, Octane), this is fine — in short-lived requests, don't expect instant propagation after you toggle a flag.
• Testing. The SDK ships an in-memory/fake variant — use it in phpunit.xml to force the client off in CI so tests never touch the network. Explicit setEnabled(true/false) per test beats real API calls.
• Version churn. v0.12.x is pre-1.0; minor bumps can carry dependency-constraint changes like this one. Pin exactly (0.12.285) or use ~0.12 and review the changelog on each bump.
• Extension points. Custom strategies are supported via the client's strategy interface; use this for domain-specific rules (tenant tier, region) that aren't expressible in Unleash constraints — but prefer built-in constraint operators where they fit, since they're editable without a deploy.
• Where this package fits. If you find yourself fighting Symfony idioms in a Laravel codebase, stop and switch to unleash/unleash-client + a thin Laravel service provider. The Symfony bundle's value is Symfony-native wiring, which Laravel doesn't give you out of the box.