Skip to main content

Module Settings API

Modules can store their own configuration using the theme's settings infrastructure.

Storing Settings​

Each module uses a dedicated option group to avoid polluting the shared settings:

// Set a module setting
flavor_set_option('enabled', 'true', 'flavor_module_my_module');
flavor_set_option('color', '#ff0000', 'flavor_module_my_module');

// Get a module setting (with default fallback)
$enabled = flavor_get_option('enabled', 'false', 'flavor_module_my_module');
$color = flavor_get_option('color', '#000000', 'flavor_module_my_module');

Naming Convention​

Module setting groups follow this pattern:

flavor_module_{module_id}

Examples:

  • flavor_module_wishlist
  • flavor_module_sale_banner
  • flavor_module_my_custom_module

Default Values​

Always provide sensible defaults when reading settings:

// Good — default provided
$limit = (int) flavor_get_option('items_per_page', '12', 'flavor_module_my_module');

// Bad — no default, could return null
$limit = flavor_get_option('items_per_page', null, 'flavor_module_my_module');

Registering Settings UI​

If your module needs a settings panel in Flavor Options:

add_action('customize_register', function ($wp_customize) {
    // Add section
    $wp_customize->add_section('my_module_settings', [
        'title' => 'My Module Settings',
        'panel' => 'flavor_modules_panel',
    ]);

    // Add setting + control
    $wp_customize->add_setting('flavor_module_my_module[background_color]', [
        'default' => '#ffffff',
        'sanitize_callback' => 'sanitize_hex_color',
    ]);

    $wp_customize->add_control(new WP_Customize_Color_Control(
        $wp_customize,
        'my_module_bg_color',
        [
            'label' => 'Background Color',
            'section' => 'my_module_settings',
            'settings' => 'flavor_module_my_module[background_color]',
        ]
    ));
});

Caching Settings​

For expensive settings that are read frequently:

function my_module_get_config(): array
{
    $cached = flavor_cache_get('my_module_config');
    if ($cached !== null) {
        return $cached;
    }

    $config = [
        'enabled' => flavor_get_option('enabled', 'true', 'flavor_module_my_module'),
        'color' => flavor_get_option('color', '#000', 'flavor_module_my_module'),
        'limit' => (int) flavor_get_option('limit', '10', 'flavor_module_my_module'),
    ];

    flavor_cache_set('my_module_config', $config, 3600); // 1 hour TTL

    return $config;
}
caution

Remember: flavor_cache_get() returns null (not false) when the cache key doesn't exist. Use !== null for checks.