PHPackages                             codesoup/options - 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. codesoup/options

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

codesoup/options
================

Framework-agnostic WordPress options manager using custom post types. Supports ACF, custom metaboxes, and extensible integrations.

v1.2.1(1mo ago)0431[3 issues](https://github.com/code-soup/options/issues)GPL-3.0-or-laterPHPPHP >=7.4.0

Since Jun 9Pushed 1mo agoCompare

[ Source](https://github.com/code-soup/options)[ Packagist](https://packagist.org/packages/codesoup/options)[ Docs](https://www.codesoup.co)[ RSS](/packages/codesoup-options/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (3)Dependencies (5)Versions (8)Used By (0)

CodeSoup Options
================

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

[![CodeSoup Options Preview](assets/media/codesoup-options-preview.png)](assets/media/codesoup-options-preview.png)

Features
--------

[](#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](https://github.com/code-soup/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
------------

[](#requirements)

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

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

[](#installation)

### Via Composer

[](#via-composer)

```
composer require codesoup/options
```

### As WordPress Plugin

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

[](#quick-start)

### Native Metaboxes (No Framework)

[](#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](docs/native.md)** for details.

### With ACF (Default)

[](#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](docs/acf.md)** for details.

Documentation
-------------

[](#documentation)

- **[Examples](docs/examples/)** - Working code examples
- **[Tabbed UI](docs/tabbed-ui.md)** - Modern tabbed interface
- **[Native Metaboxes](docs/native.md)** - Using without any framework
- **[ACF Integration](docs/acf.md)** - Using with Advanced Custom Fields
- **[Custom Integrations](docs/custom-integrations.md)** - CMB2, MetaBox.io, Carbon Fields
- **[API Reference](docs/api.md)** - Complete method documentation
- **[Migration Guide](docs/migration.md)** - Migrating post\_type, prefix, and capabilities

Agent Skills
------------

[](#agent-skills)

AI-optimized documentation for agents is available in the `skills/` directory. See **[skills/README.md](skills/README.md)** for installation and usage.

Configuration
-------------

[](#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](docs/migration-v1.1.md) to upgrade.

License
-------

[](#license)

GPL-3.0+

Support
-------

[](#support)

- **Issues:** [GitHub Issues](https://github.com/codesoup/options/issues)
- **Website:** [codesoup.co](https://www.codesoup.co)

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance91

Actively maintained with recent releases

Popularity15

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity38

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.

###  Release Activity

Cadence

Every ~6 days

Total

4

Last Release

51d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/00b8448f7b4a45eae365d2016244dddf72ab4f8556747fa41521f23863b09a65?d=identicon)[bobz-zg](/maintainers/bobz-zg)

---

Top Contributors

[![Bobz-zg](https://avatars.githubusercontent.com/u/420604?v=4)](https://github.com/Bobz-zg "Bobz-zg (26 commits)")

---

Tags

wordpressSettingsoptionsextensiblecustom-post-typeacfframework agnosticcomposer-packagemetaboxCMB2

### Embed Badge

![Health badge](/badges/codesoup-options/health.svg)

```
[![Health](https://phpackages.com/badges/codesoup-options/health.svg)](https://phpackages.com/packages/codesoup-options)
```

###  Alternatives

[samrap/acf-fluent

A fluent interface for the Advanced Custom Fields WordPress plugin

28358.2k4](/packages/samrap-acf-fluent)[webdevstudios/cmb2-attached-posts

Custom field for CMB2 for creating post relationships.

13566.0k](/packages/webdevstudios-cmb2-attached-posts)[iceicetimmy/acf-post-type-selector

Post type selector for Advanced Custom Fields.

559.0k](/packages/iceicetimmy-acf-post-type-selector)[tacowordpress/tacowordpress

WordPress custom post types that feel like CRUD models

232.2k](/packages/tacowordpress-tacowordpress)

PHPackages © 2026

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