README

WordPress-native admin framework for theme and plugin developers.

AdminForge is a modern, PSR-4 compliant library for building WordPress admin interfaces. It provides an intuitive API for creating settings pages, meta boxes, and custom fields—all designed exclusively for WordPress environments.

Why AdminForge?

• WordPress-First Design: Built on WordPress APIs, not abstracted away from them
• Modern PHP: PHP 8.0+, strict types, union types, named parameters
• Zero Configuration: Sensible defaults, works out of the box
• Type-Safe: Full IDE autocomplete support with comprehensive type hints
• Performance-Optimized: O(1) meta access, two-tier caching, conditional asset loading
• Security-Conscious: Auto-nonce verification, comprehensive sanitization, capability checks
• Extensible: Designed with clear extension points for custom implementations

Requirements

• PHP: 8.0 or higher
• WordPress: 5.8 or higher

Installation

Via Composer (Recommended)

composer require amirhossein103/adminforge

In Your WordPress Plugin

<?php
/**
 * Plugin Name: My Awesome Plugin
 */

// Composer autoloader
require_once __DIR__ . '/vendor/autoload.php';

// Start using AdminForge
use AdminForge\Admin\MenuPage;
use AdminForge\MetaBox\MetaBox;
use AdminForge\Settings\Settings;

In Your WordPress Theme

<?php
// functions.php

// Composer autoloader
require_once get_template_directory() . '/vendor/autoload.php';

// Start using AdminForge

Quick Start Examples

1. Create a Settings Page

use AdminForge\Admin\SettingsPage;

add_action('admin_menu', function() {
    $page = new SettingsPage('My Plugin Settings', 'my_plugin', [
        'slug' => 'my-plugin-settings',
        'icon' => 'dashicons-admin-settings',
        'position' => 30
    ]);

    // Add fields
    $page->addField('text', 'api_key', 'API Key', [
        'hint' => 'Enter your API key',
        'required' => true
    ]);

    $page->addField('checkbox', 'enable_cache', 'Enable Caching', [
        'hint' => 'Improve performance with caching'
    ]);

    $page->addField('select', 'theme_color', 'Theme Color', [
        'options' => [
            'blue' => 'Blue',
            'red' => 'Red',
            'green' => 'Green'
        ]
    ]);

    $page->register();
});

// Retrieve settings anywhere
$api_key = Settings::get('my_plugin.api_key', '');
$cache_enabled = Settings::getBool('my_plugin.enable_cache', false);

2. Create a Meta Box

use AdminForge\MetaBox\MetaBox;

add_action('add_meta_boxes', function() {
    $metaBox = new MetaBox('product_info', 'Product Information', ['product', 'post']);

    $metaBox->addField([
        'id' => 'price',
        'type' => 'number',
        'label' => 'Price',
        'hint' => 'Enter product price in USD'
    ]);

    $metaBox->addField([
        'id' => 'sku',
        'type' => 'text',
        'label' => 'SKU',
        'placeholder' => 'PROD-12345'
    ]);

    $metaBox->addField([
        'id' => 'in_stock',
        'type' => 'checkbox',
        'label' => 'In Stock'
    ]);

    $metaBox->register();
});

// Retrieve meta values (performance-optimized)
use AdminForge\Helpers\MetaHelper;

// Option 1: Individual access
$price = get_post_meta($post_id, 'price', true);

// Option 2: Batch loading (single DB query)
MetaHelper::loadAll($post_id);
$price = MetaHelper::get($post_id, 'price', 0);
$sku = MetaHelper::get($post_id, 'sku', '');
$in_stock = MetaHelper::get($post_id, 'in_stock', false);

3. Create a Custom Admin Page

use AdminForge\Admin\MenuPage;

class MyCustomPage extends MenuPage
{
    protected string $pageTitle = 'My Dashboard';
    protected string $menuTitle = 'Dashboard';
    protected string $slug = 'my-dashboard';
    protected string $icon = 'dashicons-dashboard';

    public function render(): void
    {
        ?>
        <div class="wrap">
            <h1><?php echo esc_html($this->pageTitle); ?></h1>
            <p>Welcome to your custom dashboard!</p>

            <?php
            // Use WordPress functions naturally
            $user = wp_get_current_user();
            echo '<p>Hello, ' . esc_html($user->display_name) . '</p>';
            ?>
        </div>
        <?php
    }
}

// Register the page
add_action('admin_menu', function() {
    (new MyCustomPage())->register();
});

4. Create Custom Fields

use AdminForge\Fields\FieldFactory;

// Text field
$field = FieldFactory::create('text', 'username', [
    'label' => 'Username',
    'placeholder' => 'Enter username',
    'required' => true
]);
echo $field->render();

// Color picker
$color = FieldFactory::create('color', 'brand_color', [
    'label' => 'Brand Color',
    'default' => '#3498db'
]);
echo $color->render();

// Media uploader
$media = FieldFactory::create('media', 'featured_image', [
    'label' => 'Featured Image',
    'button_text' => 'Select Image'
]);
echo $media->render();

// Repeater field (complex repeating sections)
$repeater = FieldFactory::create('repeater', 'team_members', [
    'label' => 'Team Members',
    'fields' => [
        ['id' => 'name', 'type' => 'text', 'label' => 'Name'],
        ['id' => 'role', 'type' => 'text', 'label' => 'Role'],
        ['id' => 'bio', 'type' => 'textarea', 'label' => 'Bio']
    ]
]);
echo $repeater->render();

Available Field Types

AdminForge includes 12+ built-in field types:

Settings API

AdminForge provides a powerful settings management system with dot notation support:

use AdminForge\Settings\Settings;

// Simple get/set
Settings::set('my_plugin.api_key', 'abc123');
$key = Settings::get('my_plugin.api_key', '');

// Nested arrays
Settings::set('appearance.colors', [
    'primary' => '#0073aa',
    'secondary' => '#00a0d2'
]);
$primary = Settings::get('appearance.colors.primary'); // '#0073aa'

// Type-safe getters
$port = Settings::getInt('server.port', 8080);
$enabled = Settings::getBool('features.cache', false);
$name = Settings::getString('site.name', 'My Site');
$options = Settings::getArray('menu.items', []);

// Array operations (useful for checkboxes)
Settings::pushToArray('features.enabled', 'dark_mode');
Settings::removeFromArray('features.enabled', 'old_feature');
Settings::toggleInArray('features.beta', 'feature_x');

// Check if setting exists
if (Settings::has('my_plugin.configured')) {
    // ...
}

// Group-based access
$appearance = Settings::group('appearance');
$appearance->set('theme', 'dark');
$theme = $appearance->get('theme');
$all = $appearance->all();

// Import/Export
$json = Settings::export('my_plugin'); // Export specific group
Settings::import($json, $merge = true); // Import and merge

// Backups
Settings::backup('pre-update-backup');
Settings::restore('pre-update-backup');
$backups = Settings::listBackups();

Performance Optimization

MetaHelper: O(1) Meta Access

use AdminForge\Helpers\MetaHelper;

// Without MetaHelper: N database queries
foreach ($posts as $post) {
    $price = get_post_meta($post->ID, 'price', true);     // Query 1
    $sku = get_post_meta($post->ID, 'sku', true);         // Query 2
    $stock = get_post_meta($post->ID, 'in_stock', true);  // Query 3
}

// With MetaHelper: 1 database query total
$post_ids = wp_list_pluck($posts, 'ID');
MetaHelper::preload($post_ids); // Single query loads all meta

foreach ($posts as $post) {
    $price = MetaHelper::get($post->ID, 'price', 0);      // O(1) array access
    $sku = MetaHelper::get($post->ID, 'sku', '');         // O(1) array access
    $stock = MetaHelper::get($post->ID, 'in_stock', false); // O(1) array access
}

Two-Tier Caching

AdminForge uses a two-tier caching strategy:

1. Runtime cache: In-memory cache for the current request (fastest)
2. WordPress Object Cache: Persistent cache across requests (Redis, Memcached compatible)

use AdminForge\Core\Cache;

// Cached for 1 hour
$data = Cache::remember('expensive_operation', 3600, function() {
    return expensive_database_query();
});

// Clear specific cache
Cache::forget('expensive_operation');

// Clear all caches
Cache::flush();

Security Best Practices

AdminForge follows WordPress security standards:

Automatic Nonce Verification

// Meta boxes automatically include nonces
$metaBox = new MetaBox('product_info', 'Product Information', 'product');
$metaBox->register(); // Nonces handled automatically

// Settings pages automatically verify nonces
$page = new SettingsPage('Settings', 'my_plugin');
// Form submissions automatically verified

Comprehensive Sanitization

use AdminForge\Security\SecurityTrait;

class MyPlugin
{
    use SecurityTrait;

    public function saveData($input)
    {
        $sanitized = [
            'email' => $this->sanitizeEmail($input['email']),
            'url' => $this->sanitizeUrl($input['url']),
            'text' => $this->sanitizeText($input['text']),
            'html' => $this->sanitizeHtml($input['content']),
            'int' => $this->sanitizeInt($input['count']),
        ];

        // Or use type-based sanitization
        $value = $this->sanitizeByType($input['field'], 'email');

        return $sanitized;
    }
}

Capability Checks

// Built into admin pages
class MyPage extends MenuPage
{
    protected string $capability = 'manage_options'; // Requires admin

    public function render(): void
    {
        // Only accessible to users with 'manage_options' capability
    }
}

// Manual capability checks
use AdminForge\Security\SecurityTrait;

if ($this->userCan('edit_posts')) {
    // User can edit posts
}

Extending AdminForge

Custom Field Types

use AdminForge\Fields\BaseField;
use AdminForge\Fields\FieldFactory;

class SliderField extends BaseField
{
    public function render(): string
    {
        $value = $this->getValue() ?? $this->config['default'] ?? 50;
        $min = $this->config['min'] ?? 0;
        $max = $this->config['max'] ?? 100;

        return sprintf(
            '<input type="range" id="%s" name="%s" min="%d" max="%d" value="%d" />',
            esc_attr($this->id),
            esc_attr($this->id),
            $min,
            $max,
            $value
        );
    }
}

// Register custom field type
FieldFactory::register('slider', SliderField::class);

// Use it
$field = FieldFactory::create('slider', 'volume', [
    'label' => 'Volume',
    'min' => 0,
    'max' => 100,
    'default' => 50
]);

Custom Page Types

use AdminForge\Admin\MenuPage;

class AnalyticsDashboard extends MenuPage
{
    protected string $pageTitle = 'Analytics';
    protected string $menuTitle = 'Analytics';
    protected string $slug = 'my-analytics';
    protected string $capability = 'view_analytics'; // Custom capability

    protected function init(): void
    {
        // Called during construction
        // Add custom initialization logic
    }

    public function enqueueAssets(string $hook): void
    {
        // Only load on this specific page
        if ($hook !== $this->getHookSuffix()) {
            return;
        }

        wp_enqueue_script('chart-js', '//cdn.example.com/chart.js');
        wp_enqueue_style('my-analytics', plugin_dir_url(__FILE__) . 'analytics.css');
    }

    public function render(): void
    {
        // Use WordPress data naturally
        $stats = new WP_Query(['post_type' => 'product', 'posts_per_page' => -1]);

        ?>
        <div class="wrap">
            <h1>Analytics Dashboard</h1>
            <p>Total Products: <?php echo $stats->found_posts; ?></p>

            <div id="chart-container"></div>
        </div>
        <?php
    }
}

WordPress Integration

AdminForge embraces WordPress conventions:

Hooks and Filters

// Register pages on admin_menu
add_action('admin_menu', function() {
    (new MySettingsPage())->register();
});

// Register meta boxes on add_meta_boxes
add_action('add_meta_boxes', function() {
    (new MyMetaBox())->register();
});

// Access WordPress globals naturally
global $wpdb;
$results = $wpdb->get_results("SELECT * FROM {$wpdb->posts} WHERE post_type = 'product'");

Translations

// All strings are translatable
__('Settings saved successfully', 'my-plugin');
esc_html__('Welcome to AdminForge', 'my-plugin');

WordPress APIs

// Use WordPress functions naturally
$user = wp_get_current_user();
$post = get_post($post_id);
$meta = get_post_meta($post_id, 'key', true);

// WordPress hooks work as expected
do_action('my_plugin_before_save', $data);
$value = apply_filters('my_plugin_value', $value);

Library vs. Plugin Mode

AdminForge can be used as a library in your plugin/theme OR as a standalone plugin.

As a Library (Recommended)

composer require amirhossein103/adminforge

// Your plugin/theme code
use AdminForge\Admin\MenuPage;
use AdminForge\Settings\Settings;

// Use only the components you need
// No unwanted admin menus or automatic initialization

As a Standalone Plugin

1. Download/clone the repository
2. Place in wp-content/plugins/adminforge
3. Activate through WordPress admin

Note: When activated as a plugin, AdminForge creates a demo admin page. You can disable this by not initializing the core singleton:

// Remove the default init hook
remove_action('plugins_loaded', 'AdminForge\adminforge_init');

API Reference

Core Classes

• AdminForge\Settings\Settings - Settings management with dot notation
• AdminForge\Fields\FieldFactory - Create field instances
• AdminForge\Helpers\MetaHelper - Performance-optimized meta access
• AdminForge\Core\Cache - Two-tier caching system
• AdminForge\Core\Config - Configuration management

Page Classes

• AdminForge\Admin\MenuPage - Top-level admin menu pages
• AdminForge\Admin\SubMenuPage - Submenu pages
• AdminForge\Admin\SettingsPage - Settings pages with auto-forms
• AdminForge\Admin\BasePage - Abstract base for custom pages

Meta Boxes

• AdminForge\MetaBox\MetaBox - Custom meta boxes with auto-nonce

Fields

• AdminForge\Fields\FieldInterface - Field contract
• AdminForge\Fields\BaseField - Abstract base field class
• AdminForge\Fields\TextField - Text input fields
• AdminForge\Fields\SelectField - Select dropdowns
• AdminForge\Fields\CheckboxField - Checkboxes
• AdminForge\Fields\MediaField - WordPress media uploader
• AdminForge\Fields\RepeaterField - Repeating field groups
• And more...

Utilities

• AdminForge\Helpers\Helper - General utility functions
• AdminForge\Helpers\DataHydrator - Data extraction and filtering
• AdminForge\Security\SecurityTrait - Security helpers (trait)

Contributing

Contributions are welcome! This is a WordPress-native library, so contributions should:

• Follow WordPress coding standards
• Use WordPress APIs (not reinvent them)
• Include PHPDoc blocks
• Maintain backward compatibility in minor versions
• Add tests for new features

See CONTRIBUTING.md for detailed guidelines.

Changelog

1.0.0 (2025-12-29)

Initial stable release for Packagist

• ✅ PSR-4 autoloading with PHP 8.0+ strict types
• ✅ Settings API with dot notation support
• ✅ 12+ field types including Repeater
• ✅ Meta box system with auto-nonce security
• ✅ Performance-optimized MetaHelper (O(1) access)
• ✅ Two-tier caching system
• ✅ Comprehensive security sanitization
• ✅ Admin page system with tabs support
• ✅ Full WordPress integration
• ✅ Production-ready and stable

License

MIT License - see LICENSE for details.

Credits

Author: Amirhossein (@amirhossein103)

Special Thanks:

• WordPress Core Team for the excellent APIs
• The PHP community for modern standards (PSR-4, PSR-12)

Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki
• Source: GitHub Repository

Made with ❤️ for WordPress developers