Skip to main content

Settings

Introduction​

Settings give a wp_options row a typed shape. You declare the fields once, then read and write them without repeating casts or get_option() calls. Added in wp-kit 2.4.0.

use YourPlugin\Deps\BitApps\WPKit\Settings\SettingField;
use YourPlugin\Deps\BitApps\WPKit\Settings\SettingsSchema;
use YourPlugin\Deps\BitApps\WPKit\Settings\SettingsRepository;

$schema = (new SettingsSchema())->add(
    SettingField::bool('enabled', false, 'general'),
    SettingField::int('max_retries', 3, 'general'),
    SettingField::enum('log_level', ['debug', 'info', 'error'], 'info', 'logging'),
    SettingField::string('api_key', '', 'api')
);

$settings = new SettingsRepository('yourplugin_settings', $schema);

Fields​

Each factory takes the key, a default, an optional group, and an optional sanitizer:

SettingField::bool('enabled', false, 'general');
SettingField::int('max_retries', 3, 'general');
SettingField::float('threshold', 0.5);
SettingField::string('api_key', '', 'api');
SettingField::arr('allowed_hosts', []);
SettingField::enum('log_level', ['debug', 'info', 'error'], 'info', 'logging');
SettingField::string('slug', '', null, fn ($value) => sanitize_title($value));

The group is a label for organising a settings screen — SettingsSchema::groups() returns the fields grouped by it.

Reading and writing​

$settings->get('enabled');       // bool, cast from whatever was stored
$settings->get('log_level');     // validated against the enum choices
$settings->all();
$settings->has('api_key');

$settings->set('enabled', '1')->set('max_retries', '5');   // cast on the way in
$settings->fill(['enabled' => true, 'api_key' => 'secret']);

$settings->save();      // one update_option() call
$settings->reload();    // discard unsaved changes, re-read from the database

set() and fill() only change the in-memory copy — nothing reaches the database until save().

The constructor takes an $autoload flag as its third argument, forwarded to update_option():

new SettingsRepository('yourplugin_settings', $schema, false);

Schema​

$schema->has('api_key');
$schema->field('api_key');   // the SettingField
$schema->fields();
$schema->defaults();
$schema->groups();           // fields keyed by group, for rendering a form
note

Values are cast on read and on write, so a checkbox posting "1" and a config posting true both land as a real boolean. An enum value outside its choices falls back to the field's default rather than being stored.