Configs

Siren’s configuration system stores key-value settings using a compound key of type, subtype, and key. This three-level hierarchy lets different parts of the system namespace their settings without collision. A program’s incentive settings, a distributor’s schedule parameters, and a global feature flag can all coexist in the same table with different type and subtype values.

The config system is designed for settings that need to persist across requests and survive plugin updates. Unlike WordPress options or transients, config values are scoped to Siren’s own table and travel with the Siren data layer regardless of platform.

Siren is built on an event-driven architecture. Most configuration is written through Siren’s admin UI, which fires the appropriate events. Direct config writes are appropriate for programmatic setup (recipes, migrations, custom initialization code) and for reading config values in your own event handlers.

Accessing config data

The config datastore is available through dependency injection or the static facade.

use Siren\Configs\Core\Datastores\Config\Interfaces\ConfigDatastore;

class FeatureChecker
{
    protected ConfigDatastore $configs;

    public function __construct(ConfigDatastore $configs)
    {
        $this->configs = $configs;
    }

    public function isFeatureEnabled(string $feature): bool
    {
        return (bool) $this->configs->getConfigValue('features', 'global', $feature, false);
    }
}

use Siren\Configs\Core\Facades\Configs;

$isEnabled = (bool) Configs::getConfigValue('features', 'global', 'advancedReporting', false);

The config model

Each config record is represented by a Config model instance.

Getter methods: getType(), getSubtype(), getKey(), getValue().

The identity of a config record is the compound key of type, subtype, and key together. There is no single auto-incrementing primary key. The getIdentity() method returns an array with type, subtype, and configKey.

Available methods

The config datastore provides the standard CRUD methods documented in the introduction. It adds these domain-specific methods.

Getting a config object

getConfig retrieves a full Config model for a specific type/subtype/key combination. If the config doesn’t exist, it returns a Config instance initialized with the provided default value rather than throwing an exception. This makes it safe to call without wrapping in a try/catch.

use Siren\Configs\Core\Facades\Configs;

// Returns a Config model -- never throws for missing configs
$config = Configs::getConfig('distribution', 'schedule', 'frequency', 'monthly');

echo $config->getValue(); // 'monthly' if not set, or the stored value

Getting a config value directly

getConfigValue is a convenience method that returns just the value rather than the full model. This is the most common accessor when you only need the setting value.

use Siren\Configs\Core\Facades\Configs;

$frequency = Configs::getConfigValue('distribution', 'schedule', 'frequency', 'monthly');
$threshold = Configs::getConfigValue('fulfillment', 'rules', 'minimumPayout', 0);

Setting a config value

setConfig creates or updates a configuration value. If a record with the given type/subtype/key already exists, it is updated in place. Otherwise, a new record is created. This method is available on the datastore interface through dependency injection.

use Siren\Configs\Core\Datastores\Config\Interfaces\ConfigDatastore;

// Inside a service class with ConfigDatastore injected
$this->configs->setConfig('distribution', 'schedule', 'frequency', 'weekly');
$this->configs->setConfig('fulfillment', 'rules', 'minimumPayout', 5000);

Getting all configs in a group

getConfigGroup retrieves all config records that share a type and subtype. This is useful for loading an entire settings panel at once.

use Siren\Configs\Core\Facades\Configs;

$scheduleSettings = Configs::getConfigGroup('distribution', 'schedule');

foreach ($scheduleSettings as $config) {
    echo $config->getKey() . ': ' . $config->getValue();
}

Deleting a config

deleteConfig removes a specific configuration entry by its compound key. This method is available on the datastore interface through dependency injection.

use Siren\Configs\Core\Datastores\Config\Interfaces\ConfigDatastore;

// Inside a service class with ConfigDatastore injected
$this->configs->deleteConfig('distribution', 'schedule', 'frequency');

Incentive configs

Siren provides a specialized interface for managing program-specific incentive configuration through the Incentives facade. Under the hood, incentive configs use the same config table with the type set to incentive and the subtype set to the program ID. The Incentives facade wraps this pattern so you don’t need to manually construct the type/subtype values.

Accessing incentive configs

use Siren\Incentives\Core\Interfaces\IncentiveConfigDatastore;

class IncentiveSettings
{
    protected IncentiveConfigDatastore $incentiveConfigs;

    public function __construct(IncentiveConfigDatastore $incentiveConfigs)
    {
        $this->incentiveConfigs = $incentiveConfigs;
    }

    public function getCommissionRate(int $programId): float
    {
        return (float) $this->incentiveConfigs->getConfig($programId, 'commissionRate', 0.10);
    }

    public function setCommissionRate(int $programId, float $rate): void
    {
        $this->incentiveConfigs->setConfig($programId, 'commissionRate', $rate);
    }
}

use Siren\Incentives\Core\Facades\Incentives;

$rate = Incentives::getConfig($programId, 'commissionRate', 0.10);

Incentives::setConfig($programId, 'commissionRate', 0.15);

Getting an incentive config value

getConfig on the Incentives facade retrieves a configuration value for a specific program and key. The program ID replaces the type/subtype pair from the general config system. You only need the program ID and key.

use Siren\Incentives\Core\Facades\Incentives;

$cookieLifetime = Incentives::getConfig($programId, 'cookieLifetime', 30);
$autoApprove = Incentives::getConfig($programId, 'autoApprove', false);

Setting an incentive config value

setConfig creates or updates an incentive configuration for a program. The method returns the datastore instance for fluent chaining.

use Siren\Incentives\Core\Facades\Incentives;

Incentives::setConfig($programId, 'commissionRate', 0.20);

// Fluent chaining through the datastore
Incentives::setConfig($programId, 'cookieLifetime', 60)
    ->setConfig($programId, 'autoApprove', true);

Getting all configs for a program

getConfigs returns all incentive configuration records for a program as an array of Config models.

use Siren\Incentives\Core\Facades\Incentives;

$allSettings = Incentives::getConfigs($programId);

foreach ($allSettings as $config) {
    echo $config->getKey() . ': ' . $config->getValue();
}

Deleting an incentive config

deleteConfig removes a specific incentive configuration for a program.

use Siren\Incentives\Core\Facades\Incentives;

Incentives::deleteConfig($programId, 'cookieLifetime');