CodeSoup Options

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