README

Version 1.1.0 - WordPress options manager using custom post types with built-in ACF integration.

Manage WordPress options using custom post types instead of the wp_options table. Includes built-in Advanced Custom Fields integration and can be extended to use with any field framework (CMB2, MetaBox.io, Carbon Fields) or native metaboxes.

Features

• Tabbed UI - Organize options in tabs with horizontal or vertical layouts
• Automatic Capabilities - Post type and custom page capabilities automatically added to administrator role
• Revision History - Track changes over time
• Post Locking - Prevent concurrent edits
• Better Organization - Multiple option pages with capability control
• Built-in ACF Integration - Works out of the box with Advanced Custom Fields
• CodeSoup Metabox Schema - Designed to work with CodeSoup Metabox Schema for declarative form generation
• Extensible - Can be extended to use with CMB2, MetaBox.io, Carbon Fields, or native metaboxes
• Two UI Modes - Choose between traditional pages mode or tabbed interface

Requirements

• PHP >= 7.4
• WordPress >= 6.0
• Optional: ACF, CMB2, MetaBox.io, or Carbon Fields

Installation

Via Composer

composer require codesoup/options

As WordPress Plugin

1. Download and extract to wp-content/plugins/codesoup-options
2. Activate the plugin
3. Add configuration to your theme or plugin

Quick Start

Native Metaboxes (No Framework)

use CodeSoup\Options\Manager;

$manager = Manager::create(
	'site_settings',
	array(
		'menu_label'   => 'Site Settings',
		'integrations' => array(
			'acf' => array( 'enabled' => false ),
		),
	)
);

$manager->register_page(
	array(
		'id'         => 'general',
		'title'      => 'General Settings',
		'capability' => 'manage_options',
	)
);

$manager->register_metabox(
	array(
		'page'  => 'general',
		'title' => 'Site Information',
		'path'  => __DIR__ . '/templates/site-info.php',
		'class' => 'site-info-metabox',
	)
);

$manager->init();

// Retrieve options
$options = Manager::get( 'site_settings' )->get_options( 'general' );

Note: You must create your own HTML fields in the template and implement a save handler using Manager::save_options(). See Native Metaboxes for details.

With ACF (Default)

use CodeSoup\Options\Manager;

$manager = Manager::create( 'theme_settings' );

$manager->register_page(
	array(
		'id'          => 'general',
		'title'       => 'General',
		'capability'  => 'manage_options',
		'description' => 'General site settings and configuration',
	)
);

$manager->init();

// Retrieve options
$logo = Manager::get( 'theme_settings' )->get_option( 'general', 'site_logo' );

Note: Create ACF field groups and assign them using the "CodeSoup Options" location rule (select your page ID, e.g., "general"). ACF handles saving automatically - no save_post hook needed. See ACF Integration for details.

Documentation

• Examples - Working code examples
• Tabbed UI - Modern tabbed interface
• Native Metaboxes - Using without any framework
• ACF Integration - Using with Advanced Custom Fields
• Custom Integrations - CMB2, MetaBox.io, Carbon Fields
• API Reference - Complete method documentation
• Migration Guide - Migrating post_type, prefix, and capabilities

Agent Skills

AI-optimized documentation for agents is available in the skills/ directory. See skills/README.md for installation and usage.

Configuration

Manager::create(
	'instance_key',
	array(
		// Core settings
		'post_type'      => 'custom_options',
		'prefix'         => 'custom_',
		'revisions'      => true,
		'debug'          => false,

		// Menu configuration
		'menu'           => array(
			'label'    => 'Settings',
			'icon'     => 'dashicons-admin-settings',
			'position' => 50,
			'parent'   => null,
		),

		// UI configuration
		'ui'             => array(
			'mode'          => 'pages',  // 'pages' or 'tabs' (see docs/tabbed-ui.md)
			'tab_position'  => 'top',    // 'top' or 'left' (tabs mode only)
			'templates_dir' => null,     // Custom templates directory path
		),

		// Assets configuration
		'assets'         => array(
			'disable_styles'  => false,  // Disable plugin styles
			'disable_scripts' => false,  // Disable plugin scripts
			'disable_branding' => false, // Disable CodeSoup branding header
		),

		// Integrations
		'integrations'   => array(
			'acf' => array(
				'enabled' => true,
				'class'   => 'CodeSoup\\Options\\Integrations\\ACF\\Init',
			),
		),
	)
);

Note: The old flat configuration structure triggers deprecation warnings. See Migration Guide to upgrade.

License

GPL-3.0+

Support

• Issues: GitHub Issues
• Website: codesoup.co