README

A lightweight WordPress library for working with options and settings. Provides clean APIs for option operations, bulk management, pattern-based operations, and backup/restore functionality with advanced analysis tools.

Features

🎯 Clean API: WordPress-style snake_case methods with consistent interfaces
🚀 Advanced Operations: Array manipulation, type casting, nested access with dot notation
📊 Bulk Management: Process multiple options efficiently with change detection
🔍 Pattern Operations: Find, delete, or backup by prefix, suffix, or substring
📈 Analysis Tools: Size calculation, type validation, comparison, and orphan detection
💾 Backup & Restore: Safe option backup and restoration capabilities
🔢 Numeric Operations: Increment/decrement values with atomic updates
🔎 Type Safety: Built-in type checking and validation methods

Requirements

PHP 7.4 or later
WordPress 5.0 or later

Installation

composer require arraypress/wp-option-utils

Basic Usage

Single Option Operations

use ArrayPress\OptionUtils\Option;

// Basic operations
$exists = Option::exists( 'my_option' );
$value  = Option::get( 'my_option' );
$value  = Option::get_with_default( 'my_option', 'default' );

// Type casting
$int_value    = Option::get_cast( 'my_option', 'int', 0 );
$bool_value   = Option::get_cast( 'my_option', 'bool', false );
$array_value  = Option::get_cast( 'my_option', 'array', [] );
$float_value  = Option::get_cast( 'my_option', 'float', 0.0 );
$string_value = Option::get_cast( 'my_option', 'string', '' );

// Update/delete operations
Option::update( 'my_option', 'value' );
Option::update_if_changed( 'my_option', 'new_value' );
Option::delete( 'my_option' );

// Numeric operations
$new_value = Option::increment_value( 'counter', 1 );
$new_value = Option::decrement_value( 'counter', 1 );

// Array operations
Option::array_append( 'my_list', 'new_item' );
$contains = Option::array_contains( 'my_list', 'item' );
Option::array_remove_all( 'my_list', 'item' );
Option::array_remove_first( 'my_list', 'item' );
$count = Option::get_array_count( 'my_list' );

// Nested operations (dot notation)
$value = Option::get_nested( 'settings', 'theme.colors.primary', '#000' );
Option::set_nested( 'settings', 'theme.colors.primary', '#ff0000' );
Option::remove_nested( 'settings', 'theme.colors.primary' );

// Utility methods
$type    = Option::get_type( 'my_option' );
$size    = Option::get_size( 'my_option' );
$toggled = Option::toggle( 'boolean_option' );

// Type and size validation
if ( Option::is_type( 'my_option', 'array' ) ) {
	// Option is an array
}

if ( Option::is_large( 'my_option', 1024 ) ) {
	// Option exceeds 1KB
}

Multiple Option Operations

use ArrayPress\OptionUtils\Options;

// Bulk operations
$existing             = Options::exists( [ 'opt1', 'opt2', 'opt3' ] );
$values               = Options::get( [ 'opt1', 'opt2' ] );
$values_with_defaults = Options::get( [ 'opt1', 'opt2' ], true, 'default' );
$updated              = Options::update( [ 'key1' => 'value1', 'key2' => 'value2' ] );
$deleted_count        = Options::delete( [ 'opt1', 'opt2' ] );

// Backup and restore
$backup   = Options::backup( [ 'important_setting', 'api_key' ] );
$restored = Options::restore( $backup );

// Pattern-based operations
$pattern_options   = Options::get_by_pattern( 'my_plugin_', 'prefix' );
$prefix_options    = Options::get_by_prefix( 'my_plugin_' );
$suffix_options    = Options::get_by_suffix( '_cache' );
$substring_options = Options::get_by_substring( 'temp' );

// Pattern-based deletion
$deleted = Options::delete_by_prefix( 'my_plugin_' );
$deleted = Options::delete_by_suffix( '_cache' );
$deleted = Options::delete_by_substring( 'temp' );

// Analysis and comparison
$mismatches    = Options::compare_values( [ 'opt1' => 'expected' ] );
$filtered      = Options::filter_by_value( [ 'opt1', 'opt2' ], fn( $v ) => is_string( $v ) );
$total_size    = Options::get_size( [ 'opt1', 'opt2' ] );
$large_options = Options::find_large( [ 'opt1', 'opt2' ], 1024 );
$orphaned      = Options::find_orphaned( [ 'old_option1', 'old_option2' ] );

Advanced Examples

Complex Settings Management

// Initialize complex nested settings
$theme_config = [
	'colors'     => [
		'primary'   => '#007cba',
		'secondary' => '#50575e'
	],
	'typography' => [
		'font_size'   => 16,
		'line_height' => 1.5
	],
	'features'   => [
		'dark_mode'  => false,
		'animations' => true
	]
];

Option::update( 'theme_settings', $theme_config );

// Access and modify nested values
$primary_color = Option::get_nested( 'theme_settings', 'colors.primary', '#000000' );
$font_size     = Option::get_nested( 'theme_settings', 'typography.font_size', 14 );

// Update specific nested values
Option::set_nested( 'theme_settings', 'colors.primary', '#ff0000' );
Option::set_nested( 'theme_settings', 'features.dark_mode', true );

// Remove nested keys
Option::remove_nested( 'theme_settings', 'features.animations' );

// Toggle nested boolean values
$current_dark_mode = Option::get_nested( 'theme_settings', 'features.dark_mode', false );
Option::set_nested( 'theme_settings', 'features.dark_mode', ! $current_dark_mode );

Plugin Configuration Management

// Type-safe configuration with validation
class PluginConfig {
	private const PREFIX = 'my_plugin_';

	public static function get_api_key(): string {
		return Option::get_cast( self::PREFIX . 'api_key', 'string', '' );
	}

	public static function is_debug_enabled(): bool {
		return Option::get_cast( self::PREFIX . 'debug_mode', 'bool', false );
	}

	public static function get_cache_duration(): int {
		return Option::get_cast( self::PREFIX . 'cache_duration', 'int', 3600 );
	}

	public static function get_allowed_roles(): array {
		return Option::get_cast( self::PREFIX . 'allowed_roles', 'array', [ 'administrator' ] );
	}

	// Validate configuration
	public static function validate(): array {
		$errors = [];

		if ( ! Option::is_type( self::PREFIX . 'api_key', 'string' ) ) {
			$errors[] = 'API key must be a string';
		}

		if ( Option::is_large( self::PREFIX . 'allowed_roles', 1024 ) ) {
			$errors[] = 'Allowed roles configuration is too large';
		}

		return $errors;
	}
}

Bulk Operations and Cleanup

// Safe bulk updates with backup
$critical_options = [ 'siteurl', 'home', 'blogname', 'admin_email' ];
$backup           = Options::backup( $critical_options );

// Perform bulk update
$new_values = [
	'blogname'        => 'New Site Title',
	'blogdescription' => 'New tagline',
	'admin_email'     => 'new@example.com'
];
$updated    = Options::update( $new_values, true ); // Skip unchanged

// Restore if something went wrong
if ( count( $updated ) !== count( $new_values ) ) {
	Options::restore( $backup );
}

// Plugin cleanup with pattern matching
$plugin_options = Options::get_by_prefix( 'old_plugin_', false ); // Names only
$deleted_count  = Options::delete( $plugin_options );

// Find and clean large options
$all_options   = [ 'theme_options', 'plugin_cache', 'user_preferences' ];
$large_options = Options::find_large( $all_options, 50 * 1024 ); // > 50KB

foreach ( $large_options as $option => $size ) {
	error_log( "Large option found: {$option} ({$size} bytes)" );
	// Optionally compress or clean up
}

Performance Monitoring and Optimization

// Monitor option sizes for performance
function monitor_option_sizes() {
	$monitored_options = [
		'theme_options',
		'active_plugins',
		'wp_user_roles',
		'rewrite_rules'
	];

	$large_options = Options::find_large( $monitored_options, 10 * 1024 ); // > 10KB
	$total_size    = Options::get_size( $monitored_options );

	if ( $total_size > 100 * 1024 ) { // > 100KB total
		// Log warning or trigger optimization
		error_log( "Large options detected. Total size: {$total_size} bytes" );
	}

	return [
		'large_options' => $large_options,
		'total_size'    => $total_size
	];
}

// Configuration validation with type checking
function validate_plugin_config( $plugin_prefix ) {
	$config_options = Options::get_by_prefix( $plugin_prefix );
	$type_errors    = [];

	foreach ( $config_options as $option => $value ) {
		// Check for expected types based on option name
		if ( str_contains( $option, '_count' ) && ! Option::is_type( $option, 'integer' ) ) {
			$type_errors[] = "{$option} should be an integer";
		}

		if ( str_contains( $option, '_enabled' ) && ! Option::is_type( $option, 'boolean' ) ) {
			$type_errors[] = "{$option} should be a boolean";
		}

		if ( str_contains( $option, '_list' ) && ! Option::is_type( $option, 'array' ) ) {
			$type_errors[] = "{$option} should be an array";
		}
	}

	return $type_errors;
}

Array and List Management

// Feature flag management
Option::update( 'enabled_features', [] );

// Add features dynamically
Option::array_append( 'enabled_features', 'dark_mode' );
Option::array_append( 'enabled_features', 'advanced_search' );
Option::array_append( 'enabled_features', 'user_analytics' );

// Check if feature is enabled
if ( Option::array_contains( 'enabled_features', 'dark_mode' ) ) {
	// Enable dark mode functionality
}

// Remove specific features
Option::array_remove_first( 'enabled_features', 'user_analytics' );

// Get feature count
$feature_count = Option::get_array_count( 'enabled_features' );

// Manage user preferences as nested arrays
Option::set_nested( 'user_preferences', 'notifications.email', true );
Option::set_nested( 'user_preferences', 'notifications.sms', false );
Option::set_nested( 'user_preferences', 'display.theme', 'dark' );

$email_notifications = Option::get_nested( 'user_preferences', 'notifications.email', true );

API Reference

Option Class (Single Options)

Core Operations:

exists( string $option ): bool
get( string $option, $default = false )
get_with_default( string $option, $default )
get_cast( string $option, string $cast_type, $default = null )
update( string $option, $value ): bool
update_if_changed( string $option, $value ): bool
delete( string $option ): bool

Numeric Operations:

increment_value( string $option, int $amount = 1 )
decrement_value( string $option, int $amount = 1 )

Array Operations:

array_contains( string $option, $value ): bool
array_append( string $option, $value ): bool
array_remove_all( string $option, $value ): bool
array_remove_first( string $option, $value ): bool
get_array_count( string $option ): int

Nested Operations:

get_nested( string $option, string $key, $default = null )
set_nested( string $option, string $key, $value ): bool
remove_nested( string $option, string $key ): bool

Utility Methods:

get_type( string $option ): ?string
get_size( string $option ): int
toggle( string $option ): ?bool
is_type( string $option, string $type ): bool
is_large( string $option, int $size_limit = 1048576 ): bool

Options Class (Multiple Options)

Core Operations:

exists( array $option_names ): array
get( array $option_names, bool $include_nonexistent = false, $default = false ): array
update( array $options, bool $skip_unchanged = true ): array
delete( array $option_names ): int

Backup & Restore:

backup( array $option_names ): array
restore( array $backup ): array

Pattern Operations:

get_by_pattern( string $pattern, string $type = 'prefix' ): array
get_by_prefix( string $prefix, bool $include_values = true ): array
get_by_suffix( string $suffix, bool $include_values = true ): array
get_by_substring( string $substring, bool $include_values = true ): array
delete_by_pattern( string $pattern, string $type = 'exact' ): int
delete_by_prefix( string $prefix ): int
delete_by_suffix( string $suffix ): int
delete_by_substring( string $substring ): int

Analysis & Comparison:

compare_values( array $expected_values, bool $strict = true ): array
filter_by_value( array $option_names, callable $callback ): array
get_size( array $option_names ): int
find_large( array $option_names, int $size_limit = 1048576 ): array
find_orphaned( array $option_names, array $prefixes = [] ): array

Key Features

Type Safety: Robust type casting and validation with get_cast() and is_type() methods
Dot Notation: Access nested array values with simple string keys like 'settings.theme.color'
Atomic Updates: Change detection prevents unnecessary database writes
Pattern Matching: Flexible pattern-based operations for cleanup and discovery
Backup Safety: Built-in backup and restore capabilities for critical operations
Performance Monitoring: Size calculation and analysis tools with is_large() and find_large()
Bulk Efficiency: Optimized multi-option operations with minimal database queries
Comprehensive Analysis: Value comparison, type checking, and orphan detection tools

Requirements

PHP 7.4+
WordPress 5.0+

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the GPL-2.0-or-later License.

arraypress / wp-option-utils

Maintainers

Details

README

Features

Requirements

Installation

Basic Usage

Single Option Operations

Multiple Option Operations

Advanced Examples

Complex Settings Management

Plugin Configuration Management

Bulk Operations and Cleanup

Performance Monitoring and Optimization

Array and List Management

API Reference

Option Class (Single Options)

Options Class (Multiple Options)

Key Features

Requirements

Contributing

License

Support