README

Version 1.0.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.

Why Custom Post Types?

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
Extensible - Can be extended to use with CMB2, MetaBox.io, Carbon Fields, or native metaboxes

Requirements

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

Installation

Via Composer

composer require codesoup/options

As WordPress Plugin

Download and extract to wp-content/plugins/codesoup-options
Activate the plugin
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',
	)
);

$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',
	)
);

$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

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
Architecture - Class diagram and design patterns
Examples - Working code examples

Key Features

Multiple Instances - Run different option sets with separate configurations

Capability Control - Fine-grained permissions per page

Extensible - Easy integration system for any field framework

Clean Code - PSR-4 autoloading, PHP 8.1+, typed properties

Configuration

Manager::create(
	'instance_key',
	array(
		'post_type'      => 'custom_options',
		'prefix'         => 'custom_',
		'menu_label'     => 'Settings',
		'menu_icon'      => 'dashicons-admin-settings',
		'menu_position'  => 50,
		'parent_menu'    => null,
		'revisions'      => true,
		'cache_duration' => HOUR_IN_SECONDS,
		'debug'          => false,
		'integrations'   => array(
			'acf' => array(
				'enabled' => true,
				'class'   => 'CodeSoup\\Options\\Integrations\\ACF\\Init',
			),
		),
	)
);

License

GPL-3.0+

Support

Issues: GitHub Issues
Website: codesoup.co

codesoup / options

Maintainers

Details