STR Content Management Settings API

STR Content Management Settings API

The Settings API allows for the global management of all of the plugins primary options, and gives tunnel down links to the settings page of all activated sub-modules. In addition, it lays down standards for over-riding the settings default and returns, and also gives function, file and variable naming conventions used.

Purpose

The STRCM Settings API provides a single, structured configuration array describing:

• Modules (top-level feature groups)
• Sub-modules (individual features/files inside a module)
• Runtime loading metadata (base dirs, load contexts, entry points)
• Debug control (per sub-module debug level 0–3)
• Lifecycle control (activate/deactivate/uninstall handlers)
• Cleanup policy (delete settings per sub-module, plus optional global cleanup)

This makes module rendering, loading, debugging, lifecycle actions, and cleanup data-driven and consistent.

Data Structures

Module setting structure

Returned by strcm_core_get_module_setting_structure():

Notes

• module_base_dir is used by the loader to assemble file paths without hardcoding.
• Module keys other than editable ones should be treated as code-owned defaults, not user input.

Sub-module setting structure

Returned by strcm_core_get_sub_module_setting_structure():

Notes

• sub_module_debug_mode controls which debug statements appear when calling strcm_debug_log(...) with the matching module/sub-module scope.

• sub_module_option_names enables standardized cleanup without hardcoding option names elsewhere.

• Lifecycle selectors allow gradual adoption: start with auto, later switch to file: when testing new lifecycle handlers.

Canonical Settings Option

Recommended canonical stored option (one source of truth):

• strcm_modules_settings (array)

This option should hold the merged result of defaults + user edits, with the default structures used as the canonical schema.

Editable vs code-owned keys

A safe rule:

Editable in UI (sanitizable from user input):

• module_status
• sub_module_status
• sub_module_debug_mode
• sub_module_delete_settings_on_deactivate

Everything else should be treated as code-owned defaults:

• names, links, banners/icons
• base dirs and load contexts
• lifecycle selectors/callables
• owned option lists
• user-level thresholds (unless you later build UI for them)

Filters

You want developers to be able to provide their own defaults and overrides without editing STRCM core. These are the recommended filters and how they are used.

1) Filter: module/sub-module defaults (most important)

Filter name: strcm_default_settings_array

When it runs: before merging saved values into defaults, and before rendering UI.

Purpose: allow third parties to:

• add modules/sub-modules
• change default enable state
• set default debug levels
• add settings links
• define lifecycle scripts/callables
• declare owned options for cleanup
• set module_base_dir / sub_module_load_context

Signature

apply_filters('strcm_default_settings_array', array $defaults): array

Example: add a new tools sub-module with lifecycle + cleanup

add_filter('strcm_default_settings_array', function(array $defaults): array {

	if (!isset($defaults['tools_manager'])) {
		return $defaults;
	}

	$sub = strcm_core_get_sub_module_setting_structure();
	$sub['sub_module_id']   = 'log_viewer';
	$sub['sub_module_name'] = 'Log Viewer';
	$sub['sub_module_status'] = 0;
	$sub['sub_module_debug_mode'] = 1;
	$sub['sub_module_link_name'] = 'strcm-log-viewer';

	$sub['sub_module_option_names'] = array('strcm_log_viewer_settings');
	$sub['sub_module_activation_script'] = 'auto';
	$sub['sub_module_deactivation_script'] = 'auto';
	$sub['sub_module_uninstall_script'] = 'auto';
	$sub['sub_module_load_context'] = 'admin';

	// You can also add entry metadata if you adopt it later (recommended).
	// $sub['sub_module_entry_file'] = 'str-log-viewer.php';

	$defaults['tools_manager']['sub_modules']['log_viewer'] = $sub;

	return $defaults;
});

2) Filter: targeted overrides

If you want a structured “override rules” layer, use:

Filter name: strcm_module_specific_default_overrides

Signature

apply_filters('strcm_module_specific_default_overrides', array $override_rules): array

Use case: quick “turn these on by default” patches without rewriting defaults.

Example:

add_filter('strcm_module_specific_default_overrides', function(array $ovr): array {
	$ovr['help_manager'] = array(
		'sub_modules' => array('admin_help_system', 'expert_mode'),
		'override_setting' => array('sub_module_status' => 1),
	);
	return $ovr;
});

If you keep both filters, apply overrides after strcm_default_settings_array and before merging saved values.

3) Filter: active debug level (runtime)

Filter name: strcm_active_debug_level

Signature

apply_filters('strcm_active_debug_level', int $level, string $module_id, string $sub_module_id): int

Purpose: allow environments to force debug levels (e.g. staging always L2).

Example:

add_filter('strcm_active_debug_level', function($level, $module, $sub){
	if (defined('WP_ENV') && WP_ENV === 'staging') {
		return max($level, 2);
	}
	return $level;
}, 10, 3);

Lifecycle Handlers

Lifecycle selection

For each sub-module, STRCM reads:

• sub_module_activation_script
• sub_module_deactivation_script
• sub_module_uninstall_script

Values:

• '' → no handler
• auto → include the sub-module’s entry file(s), then call the derived or explicit callable
• file:relative/path.php → include that file, then call callable

Callable naming convention (recommended)

If no explicit callable is provided, STRCM derives one.

Recommended convention (module + sub-module + action):

• strcm_{module_id}__{sub_module_id}__activate
• strcm_{module_id}__{sub_module_id}__deactivate
• strcm_{module_id}__{sub_module_id}__uninstall

Developers can override with:

• sub_module_activation_callable
• sub_module_deactivation_callable
• sub_module_uninstall_callable

Cleanup Behaviour

Per-sub-module cleanup

If a sub-module transitions from enabled → disabled and:

• sub_module_delete_settings_on_deactivate == 1

then STRCM should delete each option in:

• sub_module_option_names

Global cleanup on plugin deactivation

If STRCM offers a global setting such as:

• delete_all_on_plugin_deactivate

then on plugin deactivation STRCM should:

• iterate all modules/sub-modules
• run deactivation scripts where configured
• delete all owned sub-module options
• finally remove strcm_modules_settings and any STRCM global options

Debug Integration

Per-sub-module debug gate

When you call:

strcm_debug_log(STRCM_DEBUG_L2, 'message', $ctx, $module_id, $sub_id);

the message prints only if the active debug level for (module_id, sub_id) is >= 2.

Recommended logging pattern

• L1: function entry/exit + file load boundaries + lifecycle boundaries
• L2: helper outputs, merged settings summaries, resolved file lists
• L3: system call results when investigating (options, filesystem checks, WP API return values)