Quickstart

Get up and running with OptStack in minutes.

Installation

Option 1: As a WordPress Plugin

Download and install OptStack as a standalone plugin:

# Clone or download to wp-content/plugins/
cd wp-content/plugins/
git clone https://github.com/miketropi/optstack.git

Then activate the plugin from the WordPress admin dashboard.

Option 2: As a Composer Library

Use OptStack as a dependency in your own plugins or themes:

composer require optstack/optstack

Bootstrap with runtime context injection in your theme's functions.php or plugin file:

funtions.php

$autoloader = get_template_directory() . '/vendor/autoload.php';
 
if (file_exists($autoloader)) {
    require_once $autoloader;
}
 
/**
 * Initialize OptStack.
 */
function theme_init(): void
{
    \OptStack\WordPress\Bootstrap::boot([
        'version' => wp_get_theme()->get('Version'),
    ]);
}
 
theme_init();
 
// Include theme options example
require_once get_template_directory() . '/theme-options.php';

Basic Usage

Create Your Options File

Create a new file theme-options.php in your theme directory. You can use our comprehensive example as a starting point:

View full example on GitHub → (opens in a new tab)

Here's a simplified version to get started:

theme-options.php

<?php
/**
 * Theme Options with OptStack
 */
 
declare(strict_types=1);
 
use OptStack\OptStack;
 
// Prevent direct access
if (!defined('ABSPATH')) {
    exit;
}
 
add_action('optstack_init', function () {
    OptStack::make('theme_options')
        ->forOptions()
        ->menuParent('themes.php')
        ->menuIcon('dashicons-admin-appearance')
        ->label('Theme Options')
        ->description('Customize your theme appearance')
        ->define(function ($stack) {
            
            // General Settings Tab
            $stack->tab('general', function ($tab) {
                $tab->group('identity', function ($group) {
                    $group->field('site_logo', [
                        'type' => 'media',
                        'label' => 'Site Logo',
                        'attributes' => [
                            'allowedTypes' => ['image'],
                        ],
                    ]);
                    
                    $group->field('site_tagline', [
                        'type' => 'text',
                        'label' => 'Site Tagline',
                    ]);
                }, [
                    'label' => 'Site Identity',
                    'layout' => 'box',
                ]);
            }, [
                'label' => 'General',
            ]);
            
        })
        ->build();
});

Include in Your Theme

Add this line to your theme's functions.php after the OptStack bootstrap:

require_once get_template_directory() . '/theme-options.php';

Access Your Options

Use OptStack::getField() to retrieve field values with dot notation support:

use OptStack\OptStack;
 
// Basic syntax
OptStack::getField(
    string $stackId,    // Stack identifier
    string $key,        // Field key (supports dot notation)
    mixed $default,     // Default value if not found
    ?int $objectId      // Object ID (for post/term/user contexts)
);
 
// Get simple field
$tagline = OptStack::getField('theme_options', 'site_tagline', 'Default tagline');
 
// Get nested field in a group (dot notation)
$logo = OptStack::getField('theme_options', 'identity.site_logo', '');
$primary_color = OptStack::getField('theme_options', 'colors.primary', '#3b82f6');
 
// Update a field value
OptStack::updateField('theme_options', 'identity.site_tagline', 'New Tagline');

Alternative: Direct WordPress Functions

You can also use native WordPress functions:

// Get all options
$options = get_option('theme_options', []);
 
// Access nested values manually
$logo = $options['identity']['site_logo'] ?? '';

For more details on retrieving field values, see the Field Usage Guide.

Introduction Storage System