PHPackages                             arraypress/wp-option-utils - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. arraypress/wp-option-utils

ActiveLibrary[Utility & Helpers](/categories/utility)

arraypress/wp-option-utils
==========================

A lean WordPress library for working with options and settings

10PHP

Since Jul 2Pushed 1y agoCompare

[ Source](https://github.com/arraypress/wp-option-utils)[ Packagist](https://packagist.org/packages/arraypress/wp-option-utils)[ RSS](/packages/arraypress-wp-option-utils/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

WordPress Option Utils - Lean Settings Management
=================================================

[](#wordpress-option-utils---lean-settings-management)

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
--------

[](#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
------------

[](#requirements)

- PHP 7.4 or later
- WordPress 5.0 or later

Installation
------------

[](#installation)

```
composer require arraypress/wp-option-utils
```

Basic Usage
-----------

[](#basic-usage)

### Single Option Operations

[](#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

[](#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
-----------------

[](#advanced-examples)

### Complex Settings Management

[](#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

[](#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

[](#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

[](#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

[](#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
-------------

[](#api-reference)

### Option Class (Single Options)

[](#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)

[](#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
------------

[](#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
------------

[](#requirements-1)

- PHP 7.4+
- WordPress 5.0+

Contributing
------------

[](#contributing)

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

License
-------

[](#license)

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

Support
-------

[](#support)

- [Documentation](https://github.com/arraypress/wp-option-utils)
- [Issue Tracker](https://github.com/arraypress/wp-option-utils/issues)

###  Health Score

15

—

LowBetter than 3% of packages

Maintenance37

Infrequent updates — may be unmaintained

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity15

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/cd6eb8aff0903d87eb674d1ba3c5f3653899c0d7661504eb0deb7798ed86b643?d=identicon)[arraypress](/maintainers/arraypress)

---

Top Contributors

[![arraypress](https://avatars.githubusercontent.com/u/22668877?v=4)](https://github.com/arraypress "arraypress (2 commits)")

### Embed Badge

![Health badge](/badges/arraypress-wp-option-utils/health.svg)

```
[![Health](https://phpackages.com/badges/arraypress-wp-option-utils/health.svg)](https://phpackages.com/packages/arraypress-wp-option-utils)
```

###  Alternatives

[paragi/php-websocket-client

Websocket client

14424.3k](/packages/paragi-php-websocket-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)