Snapshot Providers

Snapshot providers store feature flag definitions locally, enabling faster startup and continued operation during temporary API outages.

File Provider

Store snapshots as JSON files on disk. Core has no snapshot provider by default; explicitly select and inject one.

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

$snapshotSettings = new SnapshotSettings(['document_name' => 'toggly_features']);
$provider = new FileSnapshotProvider('/var/lib/toggly', $snapshotSettings);

Cache Provider

Store snapshots using PSR-16 SimpleCache.

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

$snapshotSettings = new SnapshotSettings(['document_name' => 'toggly_features']);
$provider = new CacheSnapshotProvider($cache, $snapshotSettings, 86400);

Database Provider (PDO)

This provider uses MySQL-compatible SQL, including LONGTEXT and ON UPDATE CURRENT_TIMESTAMP. A PDO connection alone does not make it portable to PostgreSQL or SQLite.

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

$pdo = new PDO('mysql:host=localhost;dbname=myapp', 'user', 'password');
$snapshotSettings = new SnapshotSettings(['document_name' => 'toggly_features']);

$provider = new DatabaseSnapshotProvider(
    $pdo,
    $snapshotSettings,
    'toggly_snapshots',     // Table name
    'toggly_jwk_snapshots'  // JWK table name
);

The provider creates the required tables automatically in the constructor.

MongoDB Provider

Store snapshots in MongoDB for high availability and scalability.

use Toggly\FeatureManagement\Storage\SnapshotProviders\MongoDBSnapshotProvider;
use MongoDB\Client;

$client = new Client('mongodb://localhost:27017');

$provider = new MongoDBSnapshotProvider(
    $client,
    'toggly',              // Database name
    'snapshots',           // Collection name
    'toggly_features',     // Definitions document ID
    'toggly_jwks'          // JWKs document ID
);

With Existing Collection

$client = new Client('mongodb://localhost:27017');
$collection = $client->selectDatabase('myapp')->selectCollection('feature_flags');

$provider = new MongoDBSnapshotProvider($collection);

info

The MongoDB provider requires the mongodb/mongodb package:

composer require mongodb/mongodb

Laravel Cache Provider

For Laravel applications, use the native Laravel cache integration.

use Toggly\Laravel\Storage\LaravelCacheSnapshotProvider;

$provider = new LaravelCacheSnapshotProvider(
    app('cache'),
    'redis',          // Cache store (null for default)
    'toggly',         // Key prefix
    3600              // TTL in seconds (null for forever)
);

Via Configuration

Configure in config/toggly.php:

return [
    // ...
    'snapshot_provider' => 'cache',
    'cache' => [
        'store' => 'redis',
        'prefix' => 'toggly',
        'ttl' => 3600,
    ],
];

Provider Comparison

Provider	Best For	Requires
File	Simple setups, single server	Filesystem access
Cache	PSR-16 compatible apps	PSR-16 cache implementation
Database	MySQL-compatible databases	PDO MySQL
MongoDB	NoSQL, high availability	mongodb/mongodb package
Laravel Cache	Laravel applications	Laravel framework

Clearing snapshots

All providers implement clear() to delete persisted feature and JWKS snapshots:

$provider->clear();
// Or via the feature provider:
$featureProvider->clearPersistedSnapshots();

Signed snapshots store exact signedDefsJson for cold-start verification. Configure $onError / on_error on settings for signature and fetch failures. See Server-side reliability.

Injection and ownership

Pass the selected snapshot provider as the fourth constructor argument, before startup loading occurs:

$featureProvider = new \Toggly\FeatureManagement\Core\FeatureProvider(
    $settings, $http, $state, $provider
);
$featureProvider->refreshFeatures();

Here $provider is the snapshot implementation from one of the examples above; $settings, $http and $state come from the core setup. Use a distinct directory, document name or cache prefix for each app/environment. Identity-specific variant providers also require separate snapshot namespaces. The host owns connection credentials, storage permissions and cleanup. Clearing persistence does not refresh the already loaded in-memory definitions; call refreshFeatures() to fetch current data.

Custom provider

Implement FeatureSnapshotProviderInterface, including feature and JWKS save/load methods plus clear(). Preserve the exact signedDefsJson bytes and metadata when storing a signed snapshot. Use the interface in your installed package for complete signatures and empty-snapshot return shapes.