estebanforge / hyperfields

1.7.3 2026-10-29 11:22 UTC

Requires

• php: >=8.2

Requires (Dev)

• brain/monkey: ^2
• friendsofphp/php-cs-fixer: ^3
• mockery/mockery: ^1
• pestphp/pest: ^4
• phpunit/phpunit: ^12

GPL-2.0-or-later

• Esteban Cuevas

Published on Packagist.org on 2026-10-29 11:23 UTC

README

HyperFields is a Composer library for WordPress custom fields.

It provides:

• options pages
• post/user/term field containers
• field validation/sanitization
• conditional logic
• JSON export/import for options with typed-node schema validation
• JSON export/import for pages/CPT content
• pluggable transfer-module orchestration
• transfer audit logging with a built-in admin logs screen

Installation

composer require estebanforge/hyperfields

Load your project Composer autoloader, then call the library bootstrap:

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

if (class_exists('\HyperFields\LibraryBootstrap')) {
    \HyperFields\LibraryBootstrap::init([
        'plugin_file' => __FILE__,
        'plugin_url'  => plugin_dir_url(__FILE__) . 'vendor/estebanforge/hyperfields/',
    ]);
}

HyperFields self-initializes (zero-config). Its bootstrap.php is a Composer autoload.files entry that schedules LibraryBootstrap::init() at after_setup_theme (priority 0). This works across every WordPress load order, including the Bedrock and WP-CLI early-load windows where add_action() is not yet available: there the bootstrap writes the registration straight into $GLOBALS['wp_filter'] in WordPress' preinitialized-hooks format, which core converts into a real hook when plugin.php loads (WP_Hook::build_preinitialized_hooks, since WP 4.7). You do not need to call init() yourself.

Calling LibraryBootstrap::init() explicitly is still supported as an optional deterministic override (for example, to pin a specific plugin_file or plugin_url). It is idempotent and safe under the cross-copy election guard. See docs/library-bootstrap.md for the full guide, arguments, the Bedrock dual-copy note, and the explicit-override contract.

Basic usage

use HyperFields\Field;
use HyperFields\OptionsPage;

$page = OptionsPage::make('My Settings', 'my-settings');

$page->addField(
    Field::make('text', 'site_title', 'Site Title')
        ->setDefault('My Site')
        ->setRequired()
);

$page->register();

Fields added directly to the page fold into an implicit default section, so the example above renders without any explicit addSection() call. Once a page has explicit sections, page-level fields are no longer rendered: addSection() / addSectionToTab() them instead (HyperFields triggers _doing_it_wrong() for each orphan field).

$page->register();

Fields also carry editor schema: `->setTab('Content')` and `->setSection('Copy')` group controls in editor sidebars, `->setLive()` badges fields whose changes re-render a live preview, and `->setConditionalLogic([...])` drives visibility (input is canonicalized to the `{relation, conditions, groups}` shape). These keys and the normalized `[{value, label}]` options list all ride `toArray()` for JSON consumers. HyperBlocks renders them as Gutenberg inspector controls — see its editor sidebar documentation.

## Helper functions

Procedural helpers are available with `hf_` prefix (for example: `hf_field`, `hf_get_field`, `hf_update_field`, `hf_option_page`).

## Schema validation for JSON imports

JSON exports now include embedded type schemas alongside each value. When importing, HyperFields validates that values match their declared schemas, preventing malformed data or injection attacks.

See [`docs/transfer-export-import.md`](docs/transfer-export-import.md) for:
- Typed-node envelope format
- SchemaValidator API
- Building schema maps for exports
- Import validation flow
- Extending with custom format validators
- Transfer audit logging, retention controls, and logs UI hooks

## Requirements

- PHP 8.1+

## Testing

HyperFields uses Pest v4.

```bash
composer run test
composer run test:unit
composer run test:integration
composer run test:coverage
composer run test:xdebug

License

GPL-2.0-or-later