Configuration

After publishing the config file, you can customize the package behavior in config/featureflags.php.

Full Configuration

return [
    // Your environment's API key
    'api_key' => env('FEATURE_FLAGS_API_KEY'),

    // Base URL for the FeatureFlags API
    'base_url' => env('FEATURE_FLAGS_URL', 'https://api.featureflags.dev/v1'),

    // Cache settings
    'cache' => [
        'enabled' => true,
        'ttl' => 300, // seconds (5 minutes)
        'store' => null, // null = default cache store
    ],

    // What to do when the API is unreachable
    'fallback' => [
        'behavior' => 'cache', // cache, default, exception
        'default_value' => false,
    ],

    // User context auto-resolution
    'context' => [
        'auto_resolve' => true,
        'user_traits' => [
            'id' => 'id',
            'email' => 'email',
            'created_at' => 'created_at',
        ],
    ],

    // Webhook configuration for instant updates
    'webhook' => [
        'enabled' => false,
        'path' => '/webhooks/feature-flags',
        'secret' => env('FEATURE_FLAGS_WEBHOOK_SECRET'),
    ],

    // Telemetry for analytics (requires Starter plan or above)
    'telemetry' => [
        'enabled' => true,
        'batch_size' => 100,
        'flush_interval' => 60, // seconds
    ],
];

Cache Settings

Flags are cached locally to ensure zero-latency evaluation. Configure the cache behavior:

'cache' => [
    // Enable/disable caching entirely
    'enabled' => true,

    // How long to cache flag configs (in seconds)
    // Lower = fresher data, Higher = less API calls
    'ttl' => 300,

    // Which cache store to use (null = default)
    // Useful if you want flags in Redis while other cache is file-based
    'store' => 'redis',
],

Fallback Behavior

Control what happens when the API is unreachable:

'fallback' => [
    // Options: 'cache', 'default', 'exception'
    'behavior' => 'cache',

    // Only used when behavior is 'default'
    'default_value' => false,
],
Behavior Description
cache Use the last known cached values indefinitely. Safest option for production.
default Return the configured default value for all flags.
exception Throw an exception so your app can handle it explicitly.

Context Auto-Resolution

The package can automatically build user context from the authenticated user:

'context' => [
    // Automatically use Auth::user() when checking flags
    'auto_resolve' => true,

    // Map user model attributes to context traits
    'user_traits' => [
        'id' => 'id',           // $user->id
        'email' => 'email',     // $user->email
        'plan' => 'plan_name',  // $user->plan_name
        'created_at' => 'created_at',
    ],
],

With auto-resolution enabled, you can simply call:

// Automatically uses the logged-in user's attributes for targeting
Feature::enabled('premium-feature');

Telemetry

Enable telemetry to track flag evaluations for analytics (requires Starter plan or above):

'telemetry' => [
    'enabled' => true,

    // Batch evaluations before sending (reduces API calls)
    'batch_size' => 100,

    // Maximum time before flushing the batch
    'flush_interval' => 60,
],

Environment Variables

Common environment variables:

# Required
FEATURE_FLAGS_API_KEY=ff_live_xxxxx

# Optional - override API URL (useful for self-hosted)
FEATURE_FLAGS_URL=https://api.featureflags.dev/v1

# Optional - webhook secret for instant updates
FEATURE_FLAGS_WEBHOOK_SECRET=your-webhook-secret

Next Steps