Configuration

Create TogglySettings before creating the provider. The same settings and HTTP client should be used by the provider, usage statistics and metrics services. Start with the complete core setup.

Settings

use Toggly\FeatureManagement\Config\TogglySettings;

$settings = new TogglySettings([
    'app_key' => getenv('TOGGLY_APP_KEY') ?: '',
    'environment' => 'Production',
    'base_url' => getenv('TOGGLY_BASE_URL') ?: 'https://definitions.toggly.io/',
    'use_signed_definitions' => true,
    'enable_variants' => false,
    'refresh_interval' => 300,
    'enable_live_updates' => false,
    'undefined_enabled_on_development' => false,
    'on_error' => static function (string $message, ?Throwable $error): void {
        error_log('Toggly: ' . $message);
    },
]);

Key	Default	Purpose
app_key	empty	Selects your Toggly application; supply it through host configuration
environment	Production	Case-sensitive environment name
base_url	https://definitions.toggly.io/	Definitions endpoint
use_signed_definitions	false	Enable signature verification for signed definitions
allowed_key_ids	null	Optional allowed signing-key IDs (array or comma-separated string)
enable_variants	false	Fetch server-evaluated variants for the initial identity
identity	null	Identity used when fetching evaluated variants
refresh_interval	300	Interval in seconds for your host's refresh schedule
enable_live_updates	true	Enable provider-managed WebSocket updates in supported long-running hosts
undefined_enabled_on_development	false	Treat undefined flags as enabled when explicitly selected
app_version / instance_name	null	Deployment and instance metadata
on_error	null	Callback accepting message and nullable exception

Keep undefined_enabled_on_development disabled in production. Match signed mode to your app's definitions configuration and observe on_error; do not switch to unsigned mode as an automatic error fallback.

HTTP client and logger

Configure timeouts on the PSR client, not on TogglyHttpClient:

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use Psr\Log\NullLogger;
use Toggly\FeatureManagement\Http\TogglyHttpClient;
use Toggly\FeatureManagement\Core\{FeatureProvider, FeatureStateService};

$logger = new NullLogger();
$http = new TogglyHttpClient(
    new Client(['timeout' => 10, 'connect_timeout' => 5]),
    new HttpFactory(),
    $settings->getBaseUrl(),
    null,
    $logger
);
$state = new FeatureStateService();
$provider = new FeatureProvider($settings, $http, $state, null, $logger);
$provider->refreshFeatures();

The HTTP client's fourth argument is an optional user-agent string; its fifth is the logger. The provider's fourth argument is an optional snapshot provider; its fifth is the logger. To enable persistence, inject a snapshot provider instead of the fourth null.

Host scheduling

Construction loads an injected snapshot but does not initiate an HTTP fetch. Call refreshFeatures() before first evaluation when there is no usable snapshot. Changing refresh_interval does not create a timer.

For PHP-FPM, use a scheduled CLI task to refresh shared snapshots and let web requests load them. Define the acceptable snapshot age and cold-start policy in your application. Without snapshots, each new request needs its own refresh. For a persistent worker, schedule refreshes and flush telemetry inside that worker; see the worker loop.

WebSockets are disabled in traditional PHP-FPM. Supported long-running hosts must drive the provider's tick() and call shutdown() on termination. Keep a host refresh schedule for polling even when live updates are enabled.

Variants and identity lifetime

FeatureManager::isEnabled($key, $context) evaluates ordinary flags with a per-call array. FeatureProvider::getVariant($key) has no context argument: it reads a variant fetched for the provider's initial identity. Enable variants and supply that identity before construction and refresh. Use a separate provider and snapshot namespace for each identity scope. Never change identity on a shared provider while serving different users. See the variant example.

Framework configuration

Laravel reads config/toggly.php; publish it with php artisan vendor:publish --tag=toggly-config. Register the host HTTP bindings and initial refresh described in Laravel integration. WordPress reads its toggly_settings option from Settings → Toggly; follow WordPress host setup for autoload, cron and snapshot selection before activation.