Skip to main content

Configuration

Learn about configuration options and advanced settings for the PHP SDK.

Configuration Options​

TogglySettings​

The main configuration class TogglySettings supports the following options:

use Toggly\FeatureManagement\Config\TogglySettings;

$settings = new TogglySettings([
    'app_key' => 'your-app-key',                    // Required: Your Toggly App Key
    'environment' => 'Production',                  // Required: Environment name
    'base_url' => 'https://app.toggly.io/',         // Optional: leave blank for SDK default
    'use_signed_definitions' => false,              // Optional: Enable signature verification
    'allowed_key_ids' => ['key-id-1', 'key-id-2'],  // Optional: Whitelist of key IDs
    'refresh_interval' => 300,                      // Optional: Refresh interval in seconds
    'app_version' => '1.0.0',                       // Optional: Application version
    'instance_name' => 'server-1',                  // Optional: Instance identifier
    'undefined_enabled_on_development' => false,    // Optional: Enable undefined features in dev
    'enable_variants' => false,                     // Optional: evaluated-variants endpoint
]);

When base_url is omitted, core falls back to https://definitions.toggly.io/. The Laravel config default is https://app.toggly.io/.

Laravel Configuration​

Install toggly/laravel, then publish config/toggly.php:

return [
    'app_key' => env('TOGGLY_APP_KEY'),
    'environment' => env('TOGGLY_ENVIRONMENT', 'Production'),
    'base_url' => env('TOGGLY_BASE_URL', 'https://app.toggly.io/'),
    'use_signed_definitions' => env('TOGGLY_USE_SIGNED_DEFINITIONS', false),
    'enable_variants' => env('TOGGLY_ENABLE_VARIANTS', false),
    'allowed_key_ids' => env('TOGGLY_ALLOWED_KEY_IDS') ? explode(',', env('TOGGLY_ALLOWED_KEY_IDS')) : null,
    'snapshot_provider' => env('TOGGLY_SNAPSHOT_PROVIDER', 'cache'), // cache, database, file
    'cache' => [
        'store' => env('TOGGLY_CACHE_STORE'), // null = Laravel default store
        'prefix' => env('TOGGLY_CACHE_PREFIX', 'toggly'),
        'ttl' => env('TOGGLY_CACHE_TTL'), // null = cache until invalidated
    ],
    'refresh_interval' => env('TOGGLY_REFRESH_INTERVAL', 300),
    'app_version' => env('TOGGLY_APP_VERSION'),
    'instance_name' => env('TOGGLY_INSTANCE_NAME'),
    'undefined_enabled_on_development' => env('TOGGLY_UNDEFINED_ENABLED_ON_DEVELOPMENT', false),
];

WordPress Configuration​

Configure via Settings → Toggly in WordPress admin (stored in the toggly_settings option):

  • App Key — required
  • Environment — case sensitive (default Production)
  • Base URL — optional; leave blank for the SDK default
  • Use Signed Definitions — optional ECDSA verification

See WordPress Integration for install, shortcodes, template helpers, and WP-Cron.

Signed Definitions​

Enable ECDSA signature verification for secure feature definitions:

$settings = new TogglySettings([
    'app_key' => 'your-app-key',
    'environment' => 'Production',
    'use_signed_definitions' => true,
    'allowed_key_ids' => ['key-id-1'], // Optional: Whitelist specific key IDs
]);

When enabled, the SDK verifies that feature definitions are signed by Toggly using ECDSA ES256 signatures.

Snapshot Providers​

Configure snapshot providers for offline support and persistence:

Cache Provider​

use Toggly\FeatureManagement\Storage\SnapshotProviders\CacheSnapshotProvider;
use Toggly\FeatureManagement\Storage\SnapshotSettings;

$cache = /* PSR-16 cache implementation */;
$snapshotProvider = new CacheSnapshotProvider(
    $cache,
    new SnapshotSettings(['document_name' => 'toggly_features'])
);

Database Provider​

use Toggly\FeatureManagement\Storage\SnapshotProviders\DatabaseSnapshotProvider;
use Toggly\FeatureManagement\Storage\SnapshotSettings;

$pdo = new PDO('mysql:host=localhost;dbname=toggly', $user, $pass);
$snapshotProvider = new DatabaseSnapshotProvider(
    $pdo,
    new SnapshotSettings(['document_name' => 'toggly_features'])
);
// Tables are created in the constructor.

File Provider​

use Toggly\FeatureManagement\Storage\SnapshotProviders\FileSnapshotProvider;
use Toggly\FeatureManagement\Storage\SnapshotSettings;

$snapshotProvider = new FileSnapshotProvider(
    '/path/to/snapshots',
    new SnapshotSettings(['document_name' => 'toggly_features'])
);

Refresh Interval​

Configure how often features are refreshed:

$settings = new TogglySettings([
    'refresh_interval' => 300, // 5 minutes (default)
]);

The refresh interval determines how often the SDK polls the Toggly API for updated feature definitions.

Undefined Features in Development​

Enable undefined features to be treated as "always on" in development:

$settings = new TogglySettings([
    'undefined_enabled_on_development' => true,
]);
info

This only affects development environments. In production, undefined features will always return false.

App Version and Instance Name​

Track which version and instance of your application is using features:

$settings = new TogglySettings([
    'app_version' => '1.2.3',
    'instance_name' => 'web-server-1',
]);

This information is sent with usage statistics and metrics to help track feature usage across deployments.

Logging​

Configure logging for debugging and monitoring:

use Psr\Log\LoggerInterface;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$logger = new Logger('toggly');
$logger->pushHandler(new StreamHandler('toggly.log', Logger::WARNING));

// Pass to services
$featureProvider = new FeatureProvider(
    $settings,
    $httpClient,
    $stateService,
    null, // snapshot provider
    null, // websocket client
    $logger
);

HTTP Client Configuration​

Configure retry logic and timeouts:

use Toggly\FeatureManagement\Http\TogglyHttpClient;

$httpClient = new TogglyHttpClient(
    $psr18Client,
    $psr17Factory,
    $baseUrl,
    [
        'max_retries' => 3,
        'retry_delay' => 1000, // milliseconds
        'timeout' => 30, // seconds
    ]
);

WebSocket Configuration​

WebSocketClient uses a raw stream handshake (no ReactPHP requirement). It only runs in long-running processes (CLI, Octane, Swoole, etc.); PHP-FPM skips it.

use Toggly\FeatureManagement\Http\WebSocketClient;

$websocketClient = new WebSocketClient($logger);

$connected = $websocketClient->connect($wsUrl, function (string $payload): void {
    // Handle feature-update notification; refresh definitions as needed
});

// Prefer FeatureProvider live updates when enabled; otherwise poll on refresh_interval

Environment-Specific Configuration​

Use different configurations per environment:

$environment = getenv('APP_ENV') ?: 'production';

$settings = new TogglySettings([
    'app_key' => getenv('TOGGLY_APP_KEY'),
    'environment' => ucfirst($environment),
    'base_url' => $environment === 'local' 
        ? 'http://localhost:5000' 
        : 'https://definitions.toggly.io',
    'undefined_enabled_on_development' => $environment === 'local',
]);

Best Practices​

  1. Use Environment Variables: Never hardcode App Keys
  2. Enable Signed Definitions: Always enable in production
  3. Configure Snapshot Providers: For offline support
  4. Set Appropriate Refresh Intervals: Balance freshness with API calls
  5. Use Logging: Monitor for errors and warnings
  6. Version Tracking: Include app version for deployment tracking
  7. Environment-Specific: Use different configs per environment