klytos-options-storage

name	klytos-options-storage
description	Guide for saving and retrieving plugin options and site configuration in Klytos CMS. Use when a plugin needs to store or read persistent settings, manage site configuration, retrieve options, save persistent key-value data, work with the Options API, Site Config, or Storage API, manage plugin settings, query options by domain, or clean up options during plugin uninstall.

Klytos Options & Storage

When to Use This Skill

Use this reference when your plugin needs to store and retrieve settings or configuration. Klytos provides three storage mechanisms:

1. Options API — Simple key-value pairs for plugin settings (most common)
2. Site Config — Global site configuration (name, language, social, SEO)
3. Storage API — Complex data collections (for advanced use cases)

---

1. Options API (Plugin Settings)

The primary way for plugins to store settings. Key-value pairs stored in the 'options' collection with built-in request-level caching.

Functions

klytos_get_option(string $key, mixed $default = null): mixed

Get an option. Returns $default if not found.

klytos_set_option(string $key, mixed $value): void

Create or update an option. Value must be JSON-serializable.

klytos_delete_option(string $key): bool

Delete an option. Returns true if it existed.

klytos_option_exists(string $key): bool

Check if an option exists.

Key Naming Convention

Format: plugin_id.setting_name

// Good — namespaced with plugin ID
klytos_set_option('my-gallery.columns', 3);
klytos_set_option('my-gallery.theme', 'dark');
klytos_set_option('seo-pro.sitemap_enabled', true);

// Bad — no namespace, risk of collision
klytos_set_option('columns', 3);
klytos_set_option('enabled', true);

Allowed characters: alphanumeric, dots, hyphens, underscores. Rejected: empty keys, keys starting with _ (reserved).

Examples

// Save settings
klytos_set_option('my-plugin.api_key', 'sk-xxxxx');
klytos_set_option('my-plugin.max_items', 50);
klytos_set_option('my-plugin.features', [
    'export' => true,
    'import' => false,
    'notifications' => true,
]);

// Read settings
$apiKey   = klytos_get_option('my-plugin.api_key', '');
$maxItems = klytos_get_option('my-plugin.max_items', 25);
$features = klytos_get_option('my-plugin.features', []);

// Check existence
if (klytos_option_exists('my-plugin.api_key')) {
    // API key is configured
}

// Delete
klytos_delete_option('my-plugin.deprecated_setting');

Bulk Operations (OptionsManager Methods)

$options = klytos_app()->getOptionsManager();

// Get ALL options for a plugin
$allSettings = $options->getForPlugin('my-plugin');
// ['my-plugin.api_key' => 'sk-xxx', 'my-plugin.max_items' => 50, ...]

// Delete ALL options for a plugin (use in uninstall.php)
$count = $options->deleteForPlugin('my-plugin');
// Returns number of options deleted

Text Domain Tracking

Every option is tagged with a text_domain field identifying its owner. This happens automatically when a plugin calls klytos_set_option() — the PluginLoader injects the active text domain.

// Automatic: text_domain is inferred from the active plugin context
klytos_set_option('my-gallery.columns', 3);
// Record: { key: "my-gallery.columns", value: 3, text_domain: "my-gallery", ... }

// Explicit: set with a specific text domain
klytos_set_option_for('_core', 'site.maintenance', false);

// Query by text domain
$allGalleryOptions = klytos_get_options_by_domain('my-gallery');

// Delete all options for a text domain
$deleted = klytos_delete_options_by_domain('old-plugin');

Text Domain Methods (OptionsManager)

$options = klytos_app()->getOptionsManager();

// Get/delete by text domain
$records = $options->getByTextDomain('my-plugin');
$count   = $options->deleteByTextDomain('my-plugin');
$count   = $options->countByTextDomain('my-plugin');

// List grouped by text domain
$grouped = $options->listGroupedByTextDomain();
// ['_core' => [...], 'my-plugin' => [...], '_unknown' => [...]]

// Classify by plugin status
$domains    = $app->getPluginLoader()->getTextDomainsByStatus();
$classified = $options->classifyOptions($domains['active'], $domains['inactive']);
// ['core' => [...], 'active' => [...], 'inactive' => [...], 'orphan' => [...], 'unknown' => [...]]

// Migrate legacy options without text_domain
$migrated = $options->migrateTextDomains();

Data Sensitivity Classification

Plugins can declare whether an option contains sensitive data. This tells Klytos whether to encrypt the option at rest based on the site's encryption level (basic, medium, professional).

klytos_register_option(string $key, bool|string $sensitive = false, array $meta = []): void

Sensitivity levels:

Value	Behavior	Use for
true	Always encrypted, regardless of site encryption level	API keys, tokens, passwords, secrets
'user_data'	Encrypted from medium level onwards	Emails, IPs, personal data (GDPR)
false	Only encrypted at professional level (default)	Colors, counts, toggles, non-sensitive config

Example:

// In your plugin's main file or install.php:

// API key — always encrypt, even on basic level
klytos_register_option('my-plugin.stripe_secret_key', true);
klytos_register_option('my-plugin.webhook_secret', true);

// User emails — encrypt from medium level (GDPR)
klytos_register_option('my-plugin.notification_email', 'user_data');
klytos_register_option('my-plugin.customer_data', 'user_data');

// Normal settings — no special encryption needed
klytos_register_option('my-plugin.theme_color', false);
klytos_register_option('my-plugin.items_per_page', false);

// false is the default, so you can omit it:
klytos_register_option('my-plugin.items_per_page');

Reading sensitivity:

$sensitivity = klytos_get_option_sensitivity('my-plugin.stripe_secret_key');
// Returns: true, 'user_data', false, or null (not registered)

Important: Registration must happen before the option is read/written. Register in your plugin's main file, not lazily. Options that are NOT registered default to false (only encrypted at professional level).

Hooks

Hook	Type	Arguments
option.before_set	action	string $key, mixed $value, mixed $oldValue
option.after_set	action	string $key, mixed $value, mixed $oldValue
option.before_delete	action	string $key
option.after_delete	action	string $key
option.get	filter	mixed $value, string $key
option.registered	action	string $key, bool|string $sensitive, array $meta

// Example: Log when options change
klytos_add_action('option.after_set', function (string $key, mixed $value): void {
    klytos_log('info', "Option updated: {$key}");
});

// Example: Transform option on retrieval
klytos_add_filter('option.get', function (mixed $value, string $key): mixed {
    if ($key === 'my-plugin.mode' && $value === null) {
        return 'default'; // Override null with default
    }
    return $value;
});

---

2. Site Configuration (Global Settings)

For global site-level settings. Do NOT use this for plugin settings — use the Options API instead.

Reading Config

klytos_config(string $key, mixed $default = null): mixed

Supports dot-notation for nested values:

$siteName = klytos_config('site_name');                      // 'My Site'
$language = klytos_config('default_language', 'en');          // 'es'
$twitter  = klytos_config('social.twitter');                  // '@handle'
$gaId     = klytos_config('analytics.google_analytics_id');   // 'G-XXXXXXX'
$ogImage  = klytos_config('seo.default_og_image');            // '/assets/images/og.jpg'

Writing Config

klytos_set_config(string $key, mixed $value): void

Note: Top-level keys only (no dot-notation for writing). Use sparingly.

Full Config Structure

[
    'site_name'        => 'My Klytos Site',
    'tagline'          => 'Built with AI',
    'default_language' => 'es',
    'description'      => 'Site description',
    'favicon_url'      => '/assets/images/favicon.ico',
    'logo_url'         => '/assets/images/logo.svg',
    'indexing_enabled' => true,
    'editor'           => 'gutenberg',
    'admin_theme'      => 'dark',        // 'light' or 'dark'

    'social' => [
        'twitter'   => '',
        'github'    => '',
        'linkedin'  => '',
        'instagram' => '',
        'youtube'   => '',
        'mastodon'  => '',
    ],

    'analytics' => [
        'google_analytics_id' => '',
        'custom_head_scripts' => '',
        'custom_body_scripts' => '',
    ],

    'seo' => [
        'default_og_image' => '',
        'robots_txt_extra' => '',
    ],

    'email' => [
        'transport'     => 'mail',       // 'mail' or 'smtp'
        'from_name'     => '',           // Falls back to site_name
        'from_email'    => '',           // Falls back to noreply@domain
        'reply_to'      => '',
        'smtp_host'     => '',
        'smtp_port'     => 587,
        'smtp_user'     => '',
        'smtp_pass'     => '',
        'smtp_security' => 'tls',        // 'tls', 'ssl', ''
    ],

    'languages'  => ['es', 'en'],
    'last_build' => '2026-03-31T10:00:00+02:00',
]

Via MCP

• klytos_get_site_config — Returns full config
• klytos_set_site_config — Partial update (only provided fields change)
• klytos_options_list_by_domain — List options for a text domain
• klytos_options_classify — Classify options by plugin status
• klytos_options_delete_domain — Delete all options for a text domain
• klytos_options_migrate — Migrate legacy options without text_domain

---

3. Storage API (Complex Data)

For complex plugin data that doesn't fit key-value. Uses the abstracted storage layer (FileStorage or DatabaseStorage).

$storage = klytos_storage();

// Write a data record
$storage->write('my-plugin-data', 'record-1', [
    'name'    => 'Campaign A',
    'status'  => 'active',
    'clicks'  => 1543,
    'created' => date('c'),
]);

// Read it back
$record = $storage->read('my-plugin-data', 'record-1');

// List all records (with optional filters)
$all = $storage->list('my-plugin-data', ['status' => 'active']);

// Count records
$count = $storage->count('my-plugin-data', ['status' => 'active']);

// Search
$results = $storage->search('my-plugin-data', 'Campaign', ['name']);

// Delete
$storage->delete('my-plugin-data', 'record-1');

// Check existence
$exists = $storage->exists('my-plugin-data', 'record-1');

// Transaction (atomic operations)
$storage->transaction(function ($storage) {
    $storage->write('my-data', 'a', ['count' => 1]);
    $storage->write('my-data', 'b', ['count' => 2]);
});

Collection Naming Convention

Use your plugin ID as the collection prefix:

• my-plugin-data — Main data
• my-plugin-cache — Cached data
• my-plugin-logs — Plugin-specific logs

---

When to Use Each System

Scenario	System	Sensitivity	Why
Plugin toggle (on/off)	Options API	false	Simple key-value
Plugin API key	Options API	true	Sensitive secret — always encrypt
Stripe webhook secret	Options API	true	Sensitive secret — always encrypt
Notification email	Options API	'user_data'	Personal data (GDPR)
List of 5 color presets	Options API	false	Small JSON array, non-sensitive
1000+ product records	Storage API	—	Complex, queryable data
Site name, language	Site Config	—	Global, not plugin-specific
Analytics settings	Site Config	—	Site-wide configuration
Cache of external API data	Storage API	—	Large, structured data
User preferences per user	Meta API	—	Per-entity metadata

Rule of Thumb

• Options API: Simple settings (strings, numbers, booleans, small arrays)
• Site Config: Global site settings (read mostly, write rarely)
• Storage API: Complex data with CRUD operations, lists, searches
• Meta API: Data attached to existing entities (pages, users)

---

Cleanup on Uninstall

When your plugin is uninstalled, clean up all stored data:

// plugins/my-plugin/uninstall.php
<?php
declare(strict_types=1);

$app = \Klytos\Core\App::getInstance();

// Delete all options
$app->getOptionsManager()->deleteForPlugin('my-plugin');

// Delete storage collections
$storage = $app->getStorage();
$records = $storage->list('my-plugin-data');
foreach ($records as $record) {
    $storage->delete('my-plugin-data', $record['id'] ?? $record['slug'] ?? '');
}

// Delete meta on all pages
// (Only if your plugin stored meta on pages)

---

Source Files

• Options manager: core/options-manager.php
• Site config: core/site-config.php
• Storage interface: core/storage-interface.php
• File storage: core/file-storage.php
• Database storage: core/database-storage.php
• Global option functions: core/helpers-global.php
• MCP option tools: core/mcp/tools/option-tools.php
• Admin panel: admin/system-options.php
• Admin API: admin/api/options-management.php