WP_Field

HTML Fields Library for WordPress
A foundation for building custom frameworks, settings systems, and admin UIs.
Fluent API, 48 unique field types (+4 aliases), React/Vanilla UI, and modern v3 architecture.

Features • Installation • Quick Start • Field Types • Examples • Dependencies • RU version

---

Features

v3.0 — Modern Laravel-Style API

• ✨ Fluent Interface — Chain methods like Laravel: Field::text('name')->label('Name')->required()
• 🔁 Repeater Fields — Infinite nesting support with min/max constraints
• 🎨 Flexible Content — ACF-style layout builder with multiple block types
• ⚛️ React UI — Modern React components with Vanilla JS fallback
• 🏗️ SOLID Architecture — Interfaces, traits, dependency injection
• 📦 Storage Strategies — PostMeta, TermMeta, UserMeta, Options, CustomTable
• 🛡️ Type Safety — PHPStan Level 9, strict types, full PHPDoc

Core Features

• 🚀 48 Unique Field Types — Text, select, repeater, flexible content, and more
• ♻️ 4 Compatibility Aliases — date_time, datetime-local, image_picker, imagepicker
• 🔗 Conditional Logic — 14 operators with AND/OR relations
• 🧪 Full Test Coverage — Pest/PHPUnit tests with 100% pass rate
• 🎨 WP Components — Native WordPress UI integration
• 🌍 i18n Ready — Multilingual support

Requirements

• PHP 8.3+
• WordPress 6.0+
• Composer (for installation)

Installation

Via Composer (Recommended)

composer require rwsite/wp-field

Manual Installation

1. Clone or download to wp-content/plugins/wp-field-plugin
2. Run composer install --no-dev
3. Activate the plugin in WordPress admin

Build React Components (Optional)

npm install
npm run build

Quick Start

Modern API (v3.0)

use WpField\Field\Field;
use WpField\Container\MetaboxContainer;

// Fluent interface
$field = Field::text('email')
    ->label('Email Address')
    ->placeholder('user@example.com')
    ->required()
    ->email()
    ->class('regular-text');

// Render field
echo $field->render();

// Create metabox with fields
$metabox = new MetaboxContainer('product_details', [
    'title' => 'Product Details',
    'post_types' => ['product'],
]);

$metabox->addField(
    Field::text('sku')->label('SKU')->required()
);

$metabox->addField(
    Field::text('price')->label('Price')->required()
);

$metabox->register();

Repeater Field

$repeater = Field::repeater('team_members')
    ->label('Team Members')
    ->fields([
        Field::text('name')->label('Name')->required(),
        Field::text('position')->label('Position'),
        Field::text('email')->label('Email')->email(),
    ])
    ->min(1)
    ->max(10)
    ->buttonLabel('Add Member')
    ->layout('table');

Flexible Content Field

$flexible = Field::flexibleContent('page_sections')
    ->label('Page Sections')
    ->addLayout('text_block', 'Text Block', [
        Field::text('heading')->label('Heading'),
        Field::text('content')->label('Content'),
    ])
    ->addLayout('image', 'Image', [
        Field::text('image_url')->label('Image URL')->url(),
        Field::text('caption')->label('Caption'),
    ])
    ->min(1)
    ->buttonLabel('Add Section');

Field Types (48 unique + 4 aliases)

Basic (9)

• text — Text input
• password — Password field
• email — Email input
• url — URL input
• tel — Telephone input
• number — Number input
• range — Range slider
• hidden — Hidden field
• textarea — Multi-line text

Choice (5)

• select — Dropdown list
• multiselect — Multiple selection
• radio — Radio buttons
• checkbox — Single checkbox
• checkbox_group — Checkbox group

Advanced (9)

• editor — wp_editor
• media — Media library (ID or URL)
• image — Image with preview
• file — File upload
• gallery — Image gallery
• color — Color picker
• date — Date picker
• time — Time picker
• datetime — Date and time

Composite (2)

• group — Nested fields
• repeater — Repeating elements

Simple Fields (9)

• switcher — On/off switcher
• spinner — Number spinner
• button_set — Button selection
• slider — Value slider
• heading — Heading
• subheading — Subheading
• notice — Notice (info/success/warning/error)
• content — Custom HTML content
• fieldset — Field grouping

Medium Complexity Fields (10)

• accordion — Collapsible sections
• tabbed — Tabs
• typography — Typography settings
• spacing — Spacing controls
• dimensions — Size controls
• border — Border settings
• background — Background options
• link_color — Link colors
• color_group — Color group
• image_select — Image selection

High Complexity Fields (8)

• code_editor — Code editor with syntax highlighting
• icon — Icon picker from library
• map — Google Maps location
• sortable — Drag & drop sorting
• sorter — Enabled/disabled sorting
• palette — Color palette
• link — Link field (URL + text + target)
• backup — Settings export/import

Examples

Dependencies

// Show field only if another field has specific value
Field::text('courier_address')
    ->label('Delivery Address')
    ->when('delivery_type', '==', 'courier');

// Multiple conditions (AND)
Field::text('special_field')
    ->label('Special Field')
    ->when('field1', '==', 'value1')
    ->when('field2', '!=', 'value2');

// Multiple conditions (OR)
Field::text('notification')
    ->label('Notification')
    ->when('type', '==', 'sms')
    ->orWhen('type', '==', 'email');

Repeater

Field::repeater('work_times')
    ->label('Work Times')
    ->min(1)
    ->max(7)
    ->buttonLabel('Add Day')
    ->fields([
        Field::make('select', 'day')
            ->label('Day')
            ->options(['mon' => 'Mon', 'tue' => 'Tue']),
        Field::make('time', 'from')
            ->label('From'),
        Field::make('time', 'to')
            ->label('To'),
    ]);

Group

Field::make('group', 'address')
    ->label('Address')
    ->fields([
        Field::text('city')->label('City'),
        Field::text('street')->label('Street'),
        Field::text('number')->label('Number'),
    ]);

Code Editor

Field::make('code_editor', 'custom_css')
    ->label('Custom CSS')
    ->mode('css') // css, javascript, php, html
    ->height('400px');

Icon Picker

Field::make('icon', 'menu_icon')
    ->label('Menu Icon')
    ->library('dashicons');

Map

Field::make('map', 'location')
    ->label('Location')
    ->apiKey('YOUR_GOOGLE_MAPS_API_KEY')
    ->zoom(12)
    ->center(['lat' => 55.7558, 'lng' => 37.6173]);

Sortable

Field::make('sortable', 'menu_order')
    ->label('Menu Order')
    ->options([
        'home'     => 'Home',
        'about'    => 'About',
        'services' => 'Services',
        'contact'  => 'Contact',
    ]);

Palette

Field::make('palette', 'color_scheme')
    ->label('Color Scheme')
    ->palettes([
        'blue'   => ['#0073aa', '#005a87', '#003d82'],
        'green'  => ['#28a745', '#218838', '#1e7e34'],
        'red'    => ['#dc3545', '#c82333', '#bd2130'],
    ]);

Link

Field::make('link', 'cta_button')
    ->label('CTA Button');

// Get value:
// $link = get_post_meta($post_id, 'cta_button', true);
// ['url' => '...', 'text' => '...', 'target' => '_blank']

Accordion

Field::make('accordion', 'settings_accordion')
    ->label('Settings')
    ->sections([
        [
            'title'  => 'General',
            'open'   => true,
            'fields' => [
                Field::text('title')->label('Title'),
            ],
        ],
        [
            'title'  => 'Advanced',
            'fields' => [
                Field::make('textarea', 'desc')->label('Description'),
            ],
        ],
    ]);

Typography

Field::make('typography', 'heading_typography')
    ->label('Heading Typography');

// Saved as:
// [
//     'font_family' => 'Arial',
//     'font_size' => '24',
//     'font_weight' => '700',
//     'line_height' => '1.5',
//     'text_align' => 'center',
//     'color' => '#333333'
// ]

Dependency Operators

• == — Equal
• != — Not equal
• >, >=, <, <= — Comparison
• in — In array
• not_in — Not in array
• contains — Contains
• not_contains — Not contains
• empty — Empty
• not_empty — Not empty

Interactive Demo

See all 48 field types in action:

👉 Tools → WP_Field Examples (Classic API demo)
👉 /wp-admin/tools.php?page=wp-field-examples

👉 Tools → WP_Field v3.0 Demo (Modern Fluent API)
👉 /wp-admin/tools.php?page=wp-field-v3-demo

The demo pages include:

• ✅ All 48 field types with live examples
• ✅ Code for each field
• ✅ Fluent API demonstrations (v3.0)
• ✅ Repeater and Flexible Content examples
• ✅ Conditional Logic with 14 operators
• ✅ React/Vanilla UI mode switching
• ✅ Dependency system demonstration
• ✅ Ability to save and test

Extensibility

Adding Custom Field Types

add_filter('wp_field_types', function($types) {
    $types['custom_type'] = ['render_custom', ['default' => 'value']];
    return $types;
});

Adding Icon Libraries

add_filter('wp_field_icon_library', function($icons, $library) {
    if ($library === 'fontawesome') {
        return ['fa-home', 'fa-user', 'fa-cog', ...];
    }
    return $icons;
}, 10, 2);

Custom Value Retrieval

add_filter('wp_field_get_value', function($value, $storage_type, $key, $id, $field) {
    if ($storage_type === 'custom') {
        return get_custom_value($key, $id);
    }
    return $value;
}, 10, 5);

Changelog

See CHANGELOG.md for detailed version history.

Project Stats

• PHP Lines: 2705 (WP_Field.php)
• JS Lines: 1222 (wp-field.js)
• CSS Lines: 1839 (wp-field.css)
• Field Types: 48
• Dependency Operators: 12
• Storage Types: 5
• External Dependencies: 0

Compatibility

• WordPress: 6.0+
• PHP: 8.3+
• Dependencies: jQuery, jQuery UI Sortable, WordPress built-in components
• Browsers: Chrome, Firefox, Safari, Edge (latest 2 versions)

Performance

• Minimal CSS size: ~20KB
• Minimal JS size: ~15KB
• Lazy loading for heavy components (CodeMirror, Google Maps)
• Optimized selectors and events

License

GPL v2 or later

Author

Aleksei Tikhomirov (https://rwsite.ru)