### First-Time Setup

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/wp7-react-examples.md

Initial setup commands for HyperFields React integration, including installing npm dependencies.

```bash
cd /path/to/HyperFields
npm install
```

--------------------------------

### Run Docker Environment Setup

Source: https://github.com/estebanforge/hyperpress/blob/main/CLAUDE.md

Execute the setup script for initial interactive setup and dependency checks within the Docker environment.

```bash
./setup
```

--------------------------------

### Start Docker Environment

Source: https://github.com/estebanforge/hyperpress/blob/main/CLAUDE.md

Starts the Docker environment, ensuring proper SELinux and permission handling.

```bash
./start
```

--------------------------------

### Setup and Environment Management (Docker)

Source: https://github.com/estebanforge/hyperpress/blob/main/GEMINI.md

Use these commands for initial setup, starting/stopping the Docker environment, and interacting with WP-CLI. Ensure Docker is running before executing.

```bash
./setup
```

```bash
./start
```

```bash
./stop
```

```bash
./wp <command>
```

```bash
docker-compose logs -f
```

--------------------------------

### Complete HTMX Setup with Extensions

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperpress-core/docs/developer-configuration.md

Configure Hyperpress for a comprehensive HTMX setup, including core features and commonly used extensions. This example prioritizes local file loading for HTMX assets.

```php
add_filter('hyperpress/config/default_options', function($defaults) {
    $defaults['active_library'] = 'htmx';
    $defaults['load_from_cdn'] = false; // Use local files
    $defaults['load_hyperscript'] = true;
    $defaults['set_htmx_hxboost'] = true; // Progressive enhancement
    $defaults['load_htmx_backend'] = true; // Use in admin too

    // Enable commonly used HTMX extensions
    $defaults['load_extension_debug'] = true;
    $defaults['load_extension_loading-states'] = true;
    $defaults['load_extension_preload'] = true;
    $defaults['load_extension_sse'] = true;

    return $defaults;
});
```

--------------------------------

### HyperBlocks Installation

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperblocks/AGENTS.md

Instructions on how to install HyperBlocks using Composer and load the autoloader.

```APIDOC
## Installation

```bash
composer require estebanforge/hyperblocks
```

Load the Composer autoloader from the host project:

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

HyperBlocks' `bootstrap.php` is included via Composer `autoload.files`. It also bootstraps HyperFields automatically — no extra steps needed.

**Requirements**: PHP 8.2+, WordPress latest.
```

--------------------------------

### Migration Guide - Phase 1

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/wp7-react-examples.md

Starting migration by applying React to new fields by default.

```php
// New fields get React by default
ReactField::make('image', 'avatar', 'User Avatar');
```

--------------------------------

### Example Endpoint URLs

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperpress-core/docs/how-to-use.md

Lists example direct URLs for accessing hypermedia templates, corresponding to the file structure.

```text
/wp-html/v1/live-search
/wp-html/v1/related-posts
/wp-html/v1/private/author
/wp-html/v1/private/author-posts
```

--------------------------------

### Minimal SSE Example

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperpress-core/docs/datastar-helpers.md

This is the smallest possible example to stream updates via SSE from a hypermedia template partial and consume them on the frontend.

```php
// In your hypermedia template partial file, e.g., hypermedia/my-sse-endpoint.hp.php

// Apply rate limiting (SSE-specific; sends SSE error feedback when blocked)
if (hp_ds_is_rate_limited()) {
    return; // Rate limited
}

// Initialize SSE (headers are sent automatically)
$sse = hp_ds_sse();
if (!$sse) {
    hp_die('SSE not available');
}

// Read client signals
$signals = hp_ds_read_signals();
$delay = $signals['delay'] ?? 0;
$message = 'Hello, world!';

// Stream message character by character
for ($i = 0; $i < strlen($message); $i++) {
    hp_ds_patch_elements('<div id="message">' . substr($message, 0, $i + 1) . '</div>');

    // Sleep for the provided delay in milliseconds
    usleep($delay * 1000);
}

// Script will automatically exit and send the SSE stream

```

--------------------------------

### Install Datastar PHP SDK

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/starfederation/datastar-php/README.md

Install the Datastar PHP SDK using composer. Requires PHP 8.1 or later.

```shell
composer require starfederation/datastar-php
```

--------------------------------

### No Swap Response Endpoint Examples

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperpress-core/docs/how-to-use.md

Provides examples of URLs for templates designed to perform server-side actions without returning HTML, using the `noswap/` convention.

```text
/wp-html/v1/noswap/save-user?user_id=5&name=John&last_name=Doe
/wp-html/v1/noswap/delete-user?user_id=5
```

--------------------------------

### Example Usage and Output

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/version-bump.md

Demonstrates how to run the version-bump script and shows an example of its output, including the interactive prompt and confirmation checklist.

```bash
# Run the script
composer version-bump

# Example output:
┌─────────────────────────────────────┐
│   HyperFields Version Bump
└─────────────────────────────────────┘

  Current version: 1.1.12

  Enter new version (X.Y.Z): 1.2.0

  Bumping: 1.1.12 -> 1.2.0

  ✓ composer.json
  ✓ package.json
  ✓ bootstrap.php (default/fallback versions)
  ✓ src/OptionsPage.php (fallback versions)

┌─────────────────────────────────────┐
│  Version bumped to 1.2.0
└─────────────────────────────────────┘

  Next steps:
    1. Update changelog/release notes
    2. composer production
    3. git add -A && git commit -m 'Bump version to 1.2.0'
```

--------------------------------

### Minimal SSE Example

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperpress-core/docs/datastar-helpers.md

A basic example showing how to send HTML content via Datastar and consume it with frontend HTML.

```php
hp_ds_send_html('<div id="result">Hello from Datastar!</div>');
```

--------------------------------

### Setup SQLite Test Database

Source: https://github.com/estebanforge/hyperpress/blob/main/CLAUDE.md

Configures the SQLite database for running tests. Execute this command from the project root.

```bash
composer run test:setup
```

--------------------------------

### Installation

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/README.md

Install the HyperFields library using Composer.

```bash
composer require estebanforge/hyperfields
```

--------------------------------

### HyperFields Targeting Syntax Quick Reference

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/hyperfields-examples.md

A quick reference for HyperFields targeting syntax, covering post, user, and term targeting with various methods and combinations. Use this guide for practical examples and syntax.

```php
// Post targeting
->where('post_type')              // All posts of type
->wherePostId(123)                // Specific post ID
->wherePostSlug('homepage')       // Specific post slug
->wherePostIds([1, 2, 3])         // Multiple post IDs
->wherePostSlugs(['home', 'about']) // Multiple post slugs

// User targeting
->where('administrator')          // User role
->whereUserId(123)                // Specific user ID
->whereUserIds([1, 2, 3])         // Multiple user IDs

// Term targeting
->where('category')               // Taxonomy
->whereTermId(123)                // Specific term ID
->whereTermSlug('featured')       // Specific term slug
->whereTermIds([1, 2, 3])         // Multiple term IDs
->whereTermSlugs(['featured', 'trending']) // Multiple term slugs
```

--------------------------------

### Example export bundle structure

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/transfer-and-content-export-import.md

The resulting JSON structure after applying a custom SchemaConfig.

```json
{
  "site": {
    "url": "https://example.com",
    "environment": "staging"
  },
  "schema_version": 2,
  "type": "my_plugin_manifest",
  "generated_at": "...",
  "modules": {
    "options": {}
  },
  "errors": []
}
```

--------------------------------

### Install HyperPress via Composer

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperpress-core/docs/installation.md

Use this command to install HyperPress as a library in your project via Composer. This is useful for integrating hypermedia libraries into your own plugins or themes.

```bash
composer require estebanforge/hyperpress
```

--------------------------------

### Complete SSE Example

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperpress-core/docs/datastar-helpers.md

A practical example combining multiple Datastar helpers for processing uploads with SSE, including rate limiting, progress updates, and completion signals.

```php
// hypermedia/process-upload.hp.php
<?php
// Apply strict rate limiting for uploads (5 uploads per 5 minutes)
if (hp_ds_is_rate_limited([
    'requests_per_window' => 5,
    'time_window_seconds' => 300,
    'identifier' => 'file_upload_' . get_current_user_id(),
    'error_message' => __('Upload rate limit exceeded. You can upload 5 files every 5 minutes.', 'api-for-htmx'),
    'error_selector' => '#upload-errors'
])) {
    return; // Rate limited - error sent via SSE
}

// Initialize SSE
$sse = hp_ds_sse();
if (!$sse) {
    hp_die('SSE not available');
}

// Show progress
hp_ds_patch_elements('<div id="status">Processing upload...</div>');
hp_ds_patch_signals(['progress' => 0]);

// Simulate file processing
for ($i = 1; $i <= 5; $i++) {
    sleep(1);
    hp_ds_patch_signals(['progress' => $i * 20]);
    hp_ds_patch_elements('<div id="status">Processing... ' . ($i * 20) . '%</div>');
}

// Complete
hp_ds_patch_elements('<div id="status" class="success">Upload complete!</div>');
hp_ds_patch_signals(['progress' => 100, 'completed' => true]);

// Redirect after 2 seconds
hp_ds_execute_script('setTimeout(() => { window.location.href = "/dashboard"; }, 2000);');
?>
```

--------------------------------

### renderConfigured Example

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/hyperfields.md

Example demonstrating how to use `ExportImportUI::renderConfigured` with a `ExportImportPageConfig` object for immutable, config-driven wiring.

```php
use HyperFields\Admin\ExportImportPageConfig;
use HyperFields\Admin\ExportImportUI;

$config = new ExportImportPageConfig(
    options: ['my_plugin_options' => 'My Plugin Settings'],
    optionGroups: ['my_plugin_options' => 'Core'],
    prefix: 'myp_',
);

echo ExportImportUI::renderConfigured($config);
```

--------------------------------

### Install HyperPress-Core with Composer

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperpress-core/README.md

Use this command to add HyperPress-Core as a dependency to your project via Composer.

```bash
composer require estebanforge/hyperpress-core
```

--------------------------------

### Example: Register a post metabox

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/hyperfields.md

This snippet provides an example of registering a custom metabox for posts and saving its value.

```php
add_action('add_meta_boxes', function() {
    add_meta_box('custom_title', 'Custom Title', function($post) {
        $field = HyperFields::makeField('text', 'custom_title', 'Custom Title')
            ->setDefault('');
        $value = PostField::for_post($post->ID, 'text', 'custom_title', 'Custom Title')->getValue();
        echo '<input type="text" name="custom_title" value="' . esc_attr($value) . '" />';
    }, 'post');
});

// Save value
add_action('save_post', function($post_id) {
    if (isset($_POST['custom_title'])) {
        PostField::for_post($post_id, 'text', 'custom_title', 'Custom Title')->setValue($_POST['custom_title']);
    }
});
```

--------------------------------

### Complete ReactField Example

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/wp7-enhancements.md

An example showcasing the creation of an options page with various ReactField types, including text, color, and image fields, with default values and specific React props.

```php
use HyperFields\OptionsPage;
use HyperFields\Field\ReactField;

$page = OptionsPage::make('My Settings', 'my-settings')
    ->addSection('general', 'General Settings')
    ->addField(
        ReactField::make('text', 'site_title', 'Site Title')
            ->setDefault('My Website')
    )
    ->addField(
        ReactField::make('color', 'brand_color', 'Brand Color')
            ->setDefault('#2271b1')
            ->setHelp('Pick your brand color')
    )
    ->addField(
        ReactField::make('image', 'logo', 'Site Logo')
            ->setReactProp('maxWidth', 400)
            ->setReactProp('maxHeight', 200)
    )
    ->register();
```

--------------------------------

### Install HyperBlocks using Composer

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperblocks/README.md

Use this command to add HyperBlocks to your PHP project via Composer.

```bash
composer require estebanforge/hyperblocks
```

--------------------------------

### hp_ds_sse() usage

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperpress-core/docs/datastar-helpers.md

Example of getting or creating the ServerSentEventGenerator instance.

```php
$sse = hp_ds_sse();
if ($sse) {
    // SSE is available, proceed with real-time updates
    $sse->patchElements('<div id="status">Connected</div>');
}

```

--------------------------------

### Register field component

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/wp7-react-examples.md

Example of registering a new custom field component in the ReactFieldsApp.

```jsx
import MyField from './components/MyField';

const fieldComponents = {
    // ...existing components
    myfield: MyField,
};
```

--------------------------------

### Create a new field component

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/wp7-react-examples.md

Example of creating a new custom field component in React.

```jsx
// assets/js/src/components/MyField.jsx
export default function MyField({ label, value, onChange, ...props }) {
    return (
        <div className="hyperpress-field-myfield">
            <label>{label}</label>
            <input value={value} onChange={(e) => onChange(e.target.value)} />
        </div>
    );
}
```

--------------------------------

### Conditional React Usage

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/wp7-react-examples.md

Example showing how to conditionally enable or disable React rendering for a field using setUseReact().

```php
$field = ReactField::make('text', 'username', 'Username');
if ($useReact) {
    $field->setUseReact(true);
} else {
    $field->setUseReact(false); // Falls back to HTML
}
```

--------------------------------

### Custom React Props

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/wp7-react-examples.md

Example of setting custom React props for a field, such as maxWidth, maxHeight, and buttonLabel for an image field.

```php
ReactField::make('image', 'hero_image', 'Hero Image')
    ->setReactProp('maxWidth', 1200)
    ->setReactProp('maxHeight', 600)
    ->setReactProp('buttonLabel', 'Upload Hero Image');
```

--------------------------------

### React-Enhanced Field (NEW)

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/wp7-react-examples.md

Example demonstrating how to use ReactField for enhanced interactivity, replacing Field::make() with ReactField::make().

```php
use HyperFields\OptionsPage;
use HyperFields\Field\ReactField;

$page = OptionsPage::make('My Settings', 'my-settings')
    ->addSection('general', 'General', 'General settings')
    ->addField(
        ReactField::make('text', 'site_title', 'Site Title')
            ->setDefault('My Website')
    )
    ->addField(
        ReactField::make('image', 'logo', 'Site Logo')
            ->setHelp('Upload a logo (React-enhanced)')
    );

$page->register();
```

--------------------------------

### Basic Field (HTML - unchanged)

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/wp7-react-examples.md

Example of a standard text field using the basic Field class, which renders as HTML.

```php
use HyperFields\OptionsPage;
use HyperFields\Field;

$page = OptionsPage::make('My Settings', 'my-settings')
    ->addSection('general', 'General', 'General settings')
    ->addField(
        Field::make('text', 'site_title', 'Site Title')
            ->setDefault('My Website')
    );

$page->register();
```

--------------------------------

### Prepare for Production

Source: https://github.com/estebanforge/hyperpress/blob/main/CLAUDE.md

Prepares the project for production by running coding standard fixes and optimizing the autoloader.

```bash
composer run production
```

--------------------------------

### Migrate complex fields

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/wp7-react-examples.md

Example of migrating complex fields like repeaters and color pickers to React components using ReactField.

```php
// Migrate complex fields first (images, colors, repeaters)
ReactField::make('repeater', 'slides', 'Slides');
ReactField::make('color', 'brand_color', 'Brand Color');
```

--------------------------------

### Template File Structure Example

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperpress-core/docs/how-to-use.md

Illustrates the expected directory structure and file naming convention for hypermedia templates within a theme.

```text
hypermedia/live-search.hp.php
hypermedia/related-posts.hp.php
hypermedia/private/author.hp.php
hypermedia/private/author-posts.hp.php
```

--------------------------------

### Custom Component

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/wp7-react-examples.md

Example of specifying a custom React component for a field, using setReactComponent(). The component must be registered in the React app.

```php
ReactField::make('custom', 'my_field', 'My Custom Field')
    ->setReactComponent('MyCustomComponent');
    // Component must be registered in React app
```

--------------------------------

### LibraryBootstrap::init() - Vendored Usage

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/library-bootstrap.md

The `init()` method is the entry point for using HyperFields as a Composer dependency. It should be called once after the autoloader is loaded and before any HyperFields classes are used. Explicitly passing `plugin_file` and `plugin_url` is recommended for vendored contexts to avoid auto-detection failures.

```APIDOC
## POST /hyperfields/librarybootstrap/init

### Description
Initializes the HyperFields library when used as a Composer dependency within another plugin. This method should be called once after your autoloader is loaded and before any HyperFields classes are used. It is idempotent, meaning repeated calls have no additional effect.

### Method
POST

### Endpoint
/hyperfields/librarybootstrap/init

### Parameters
#### Request Body
- **plugin_file** (string) - Required - Absolute path to the host plugin's main file. Used as the base for URL resolution.
- **plugin_url** (string) - Required - Public URL to the HyperFields library root (trailing slash).
- **base_dir** (string) - Optional - Absolute path to the HyperFields library root. Defaults to the directory containing `LibraryBootstrap.php`.
- **version** (string) - Optional - Version string used for asset cache-busting. Defaults to the value in the library's `composer.json`.

### Request Example
```json
{
  "plugin_file": "/path/to/your/plugin/my-plugin.php",
  "plugin_url": "http://example.com/wp-content/plugins/my-plugin/vendor/estebanforge/hyperfields/"
}
```

### Response
#### Success Response (200)
This method does not return a specific JSON response. Its effect is internal initialization.

#### Response Example
(No specific response body for success)

### Notes
- Always pass explicit `plugin_file` and `plugin_url` arguments when using HyperFields in a vendored context to ensure correct asset loading and prevent silent failures, especially in complex directory structures or symlinked environments.
- Transfer-audit logging hooks are automatically initialized during bootstrap.
```

--------------------------------

### Run Development Commands

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperblocks/AGENTS.md

A collection of Composer scripts for testing, code style checks, and version bumping.

```bash
composer run test            # Full test suite (Pest)
```

```bash
composer run test:unit       # Unit tests only
```

```bash
composer run test:coverage   # HTML coverage report
```

```bash
composer run cs:fix          # Auto-fix code style (php-cs-fixer)
```

```bash
composer run cs:check        # Dry-run style check
```

```bash
composer run version-bump    # Bump version in composer.json + bootstrap
```

--------------------------------

### Registering HyperBlocks

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperblocks/docs/hyperblocks-examples.md

Use the init hook to register blocks. Ensure HyperFields is initialized if necessary by using after_setup_theme with a priority greater than 0.

```php
add_action('init', function (): void {
    // register blocks here
});
```

--------------------------------

### Deploy to WordPress.org

Source: https://github.com/estebanforge/hyperpress/blob/main/CLAUDE.md

Deploy the plugin to the WordPress.org repository. Requires SVN credentials.

```bash
./deploy.sh
```

--------------------------------

### Example: Taxonomy meta field

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/hyperfields.md

Example of creating a color field for taxonomy meta.

```php
$field = HyperFields::makeField('color', 'category_color', 'Category Color');
$value = TermField::forTerm($term_id, 'color', 'category_color', 'Category Color')->getValue();
```

--------------------------------

### Example: User meta field

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/hyperfields.md

Example of creating a checkbox field for user meta.

```php
$field = HyperFields::makeField('checkbox', 'onboarding_done', 'Onboarding Done');
$value = UserField::forUser($user_id, 'checkbox', 'onboarding_done', 'Onboarding Done')->getValue();
```

--------------------------------

### Bootstrap in symlinked or monorepo environments

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperblocks/docs/library-bootstrap.md

Use standard plugin_dir_path for the autoloader; WordPress handles URL resolution via plugin registration.

```php
// my-plugin.php — plugin_dir_url() resolves against WP's plugin registration, not the symlink target.

require_once plugin_dir_path(__FILE__) . 'vendor/autoload.php';

// bootstrap.php is included by autoload.files — nothing else needed.
```

--------------------------------

### Quick Start: HTML to ReactField

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/wp7-enhancements.md

Demonstrates the minimal change required to switch from a standard text field to a ReactField.

```php
Before (HTML):
```php
Field::make('text', 'title', 'Title');
```

After (React):
```php
use HyperFields\Field\ReactField;

ReactField::make('text', 'title', 'Title');
```
```

--------------------------------

### Configure HyperBlocks Paths and Settings

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperblocks/CLAUDE.md

Use the static Config class to register block directories, read configuration values, and set runtime configurations.

```php
use HyperBlocks\Config;

Config::registerBlockPath('/path/to/blocks');  // add a directory to scan for blocks
Config::get('auto_discovery', true);           // read a value
Config::set('debug', true);                    // set at runtime
```

--------------------------------

### Run project tests

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperblocks/AGENTS.md

Execute the test suite from the project root using Composer.

```bash
# From the HyperBlocks root
composer run test
```

--------------------------------

### Block Creation and Configuration

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperblocks/docs/hyperblocks.md

This section covers the creation of new blocks and configuration of their properties like name, icon, fields, and render templates.

```APIDOC
## Block Creation and Configuration

### `Block::make(string $title): Block`

Creates a new block builder. The default name is derived automatically as `hyperblocks/<sanitize_title($title)>`. Always call `setName()` to use a proper namespace.

```php
use HyperBlocks\Block\Block;

$block = Block::make('Hero Banner');
// default name: hyperblocks/hero-banner
```

### `->setName(string $name): self`

Override the block name. Must follow the WordPress `namespace/slug` format.

```php
$block->setName('my-theme/hero-banner');
```

### `->setIcon(string $slug): self`

Set the block icon using a [Dashicon](https://developer.wordpress.org/resource/dashicons/) slug.

```php
$block->setIcon('cover-image');
```

### `->addFields(Field[] $fields): self`

Append one or more `Field` objects. Chainable; call multiple times to build incrementally.

```php
use HyperBlocks\Block\Field;

$block->addFields([
    Field::make('text',     'heading',    'Heading'),
    Field::make('textarea', 'subheading', 'Subheading'),
]);
```

### `->addFieldGroup(string $groupId): self`

Attach a pre-registered `FieldGroup` by its ID. Fields from the group are merged at registration time; block fields take precedence over group fields when names collide.

```php
$block->addFieldGroup('common-settings');
```

### `->setRenderTemplate(string $template): self`

Set the template used to render the block on the frontend.

Two forms accepted:

- `file:relative/path.hb.php` — a PHP file resolved against registered block paths, `WP_CONTENT_DIR`, or the active theme.
- Inline PHP string — executed directly (useful for simple blocks; prefer file templates in production).

```php
// File template (preferred)
$block->setRenderTemplate('file:blocks/hero-banner.hb.php');

// Inline string
$block->setRenderTemplate('<h1><?php echo esc_html($heading); ?></h1>');
```

### `->setRenderTemplateFile(string $path): self`

Shorthand for `setRenderTemplate('file:' . $path)`.

```php
$block->setRenderTemplateFile('blocks/hero-banner.hb.php');
```

Template path rules:
- Must be relative (no leading `/`).
- Must not contain `..` (path traversal is rejected).
- File must exist inside `WP_CONTENT_DIR`, the active theme directory, `HYPERBLOCKS_PATH`, or a directory registered with `Config::registerBlockPath()`.
- Extension must match `Config::get('template_extensions', '.hb.php,.php')`.
```

--------------------------------

### Initialize HyperBlocks inside a plugin class

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperblocks/docs/library-bootstrap.md

Define constants in the main plugin file to ensure correct URL resolution when deferring setup to a bootstrap class.

```php
// my-plugin.php

define('MY_PLUGIN_FILE', __FILE__);
define('MY_PLUGIN_DIR',  plugin_dir_path(__FILE__));
define('MY_PLUGIN_URL',  plugin_dir_url(__FILE__));

add_action('plugins_loaded', function (): void {
    require_once MY_PLUGIN_DIR . 'vendor/autoload.php';
    MyPlugin\Bootstrap::init();
});
```

```php
// src/Bootstrap.php

namespace MyPlugin;

class Bootstrap
{
    public static function init(): void
    {
        add_action('init', [self::class, 'registerBlocks']);
    }

    public static function registerBlocks(): void
    {
        \HyperBlocks\Config::registerBlockPath(MY_PLUGIN_DIR . 'blocks');
    }
}
```

--------------------------------

### Frontend HTML Example

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperpress-core/docs/datastar-helpers.md

This HTML snippet demonstrates the frontend structure for a live user search, including input fields, buttons, and containers for results and validation messages. It utilizes Datastar attributes for signals, event handling, and data binding.

```html
<!-- Live search with real-time validation -->
<div data-signals:query="" data-signals:results="[]" data-signals:loading="false">
    <h3>User Search</h3>

    <!-- Search input with live validation -->
    <input
        type="text"
        data-bind:query
        data-on:input="@get('<?php hp_endpoint_url('search-users-validate'); ?>')"
        placeholder="Search users..."
    />

    <!-- Search button -->
    <button
        data-on:click="@get('<?php hp_endpoint_url('search-users'); ?>')"
        data-bind:disabled="$loading"
    >
        <span data-show="!$loading">Search</span>
        <span data-show="$loading">Searching...</span>
    </button>

    <!-- Results container -->
    <div id="search-results" data-show="$results.length > 0">
        <!-- Results will be populated via SSE -->
    </div>

    <!-- No results message -->
    <div data-show="$results.length === 0 && !$loading && $query.length > 0">
        No users found
    </div>
</div>
```

--------------------------------

### Basic Usage: Creating an Options Page

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/README.md

Example of creating a basic options page with a text field.

```php
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();
```

--------------------------------

### Initialize Hyperpress Library Bootstrap

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/library-bootstrap.md

Use this when your plugin's vendor directory is not in the standard WordPress path, such as in a monorepo. `plugin_dir_url(__FILE__)` correctly resolves the URL based on WordPress's plugin registration, not the filesystem path.

```php
// my-plugin.php — constants are safe because plugin_dir_url() resolves
// against WP's own plugin registration, not the filesystem path.

\HyperFields\LibraryBootstrap::init([
    'plugin_file' => __FILE__,
    'plugin_url'  => plugin_dir_url(__FILE__) . 'vendor/estebanforge/hyperfields/',
    'version'     => '1.2.3', // optional: pin to your vendored version
]);
```

--------------------------------

### No Swap Template File Structure

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperpress-core/docs/how-to-use.md

Illustrates the directory structure for 'no swap' templates.

```text
hypermedia/noswap/save-user.hp.php
hypermedia/noswap/delete-user.hp.php
```

--------------------------------

### Image Field Declaration

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/hyperfields.md

Example of declaring an image field.

```php
$field = HyperFields::makeField('image', 'hero_image', 'Hero image');
```

--------------------------------

### Textarea field declaration

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/hyperfields.md

Example of declaring a textarea field.

```php
$field = HyperFields::makeField('textarea', 'bio', 'Author bio')
    ->setRows(4)
    ->setDefault('');

```

--------------------------------

### Guard HyperBlocks Initialization

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperblocks/docs/library-bootstrap.md

Use this check to ensure that `add_action` exists before attempting to include the autoloader, suitable for non-WordPress environments like WP-CLI scripts or testing without Brain Monkey.

```php
if (function_exists('add_action')) {
    require_once __DIR__ . '/vendor/autoload.php';
    // bootstrap.php is included by autoload.files
}
```

--------------------------------

### Configuration Helper Function

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperblocks/docs/hyperblocks.md

Retrieves configuration values with an optional default.

```php
hyperblocks_config(string $key, mixed $default = null): mixed
```

--------------------------------

### Define a Gutenberg Block using Fluent API

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperblocks/AGENTS.md

Example of creating a 'Hero Banner' block with text and image fields, attaching a field group, and setting a render template file. Ensure template paths are relative and within allowed directories.

```php
use HyperBlocks\Block\Block;
use HyperBlocks\Block\Field;
use HyperBlocks\Registry;

$block = Block::make('Hero Banner')            // title; auto-name: hyperblocks/hero-banner
    ->setName('my-theme/hero-banner')          // override with explicit namespace/slug
    ->setIcon('cover-image')                   // dashicon slug
    ->addFields([
        Field::make('text', 'heading', 'Heading')->setDefault('Welcome'),
        Field::make('image', 'bg_image', 'Background'),
    ])
    ->addFieldGroup('common-settings')         // attach a registered FieldGroup by id
    ->setRenderTemplateFile('blocks/hero-banner.hb.php');  // file: prefix added automatically

Registry::getInstance()->registerFluentBlock($block);
```

--------------------------------

### Date/Time Field Declaration

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/hyperfields.md

Example of declaring date and time fields.

```php
$field = HyperFields::makeField('date', 'event_date', 'Event Date');
$field->setDefault('');
$time  = HyperFields::makeField('time', 'event_time', 'Event Time');
```

--------------------------------

### Exporting Options with Schema Rules

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/transfer-and-content-export-import.md

Demonstrates how to export options with optional schema maps to enforce validation rules during future imports.

```php
use HyperFields\ExportImport;

// Auto-detected types only (basic safety)
$json = ExportImport::exportOptions(['my_plugin_options']);

// Full schema rules embedded in the export
$json = ExportImport::exportOptions(
    ['my_plugin_color', 'my_plugin_name', 'my_plugin_settings'],
    '',  // prefix
    [
        'my_plugin_color' => [
            'type'   => 'string',
            'format' => 'hex_color',
        ],
        'my_plugin_name' => [
            'type' => 'string',
            'max'  => 255,
        ],
        'my_plugin_settings' => [
            'type'   => 'array',
            'fields' => [
                'enabled'    => ['type' => 'string', 'enum' => ['yes', 'no']],
                'recipients' => ['type' => 'string', 'max' => 2000, 'format' => 'email_csv'],
            ],
        ],
    ]
);
```

--------------------------------

### hp_ds_read_signals() usage

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperpress-core/docs/datastar-helpers.md

Example of reading signals sent from the Datastar client.

```php
// Read client signals
$signals = hp_ds_read_signals();
$user_input = $signals['search_query'] ?? '';
$page_number = $signals['page'] ?? 1;

// Use signals for processing
if (!empty($user_input)) {
    $results = search_posts($user_input, $page_number);
    hp_ds_patch_elements($results_html, ['selector' => '#results']);
}

```

--------------------------------

### GET /hyperblocks/v1/block-fields

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperpress-core/docs/hyperblocks.md

Retrieves the field definitions for a specific block, used by the editor to render InspectorControls.

```APIDOC
## GET /hyperblocks/v1/block-fields

### Description
Returns field definitions for the requested block name. Sources fields from Fluent PHP blocks first, then falls back to JSON blocks.

### Method
GET

### Endpoint
/hyperblocks/v1/block-fields

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the block to retrieve fields for.
```

--------------------------------

### Date Field Save/Retrieve

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/hyperfields.md

Example of saving and retrieving data for a date field.

```php
hf_update_field('event_date', '2025-09-01', 123, [ 'type' => 'date' ]);
$date = hf_get_field('event_date', 123, [ 'default' => '' ]);
echo esc_html($date);
```

--------------------------------

### Initialize and Send Headers with ServerSentEventGenerator

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/starfederation/datastar-php/README.md

Creates a new ServerSentEventGenerator instance and sends the necessary response headers. If your framework handles headers, manually send the headers returned by ServerSentEventGenerator::headers() instead.

```php
use starfederation\datastar\enums\EventType;
use starfederation\datastar\enums\ElementPatchMode;
use starfederation\datastar\ServerSentEventGenerator;

// Creates a new `ServerSentEventGenerator` instance.
$sse = new ServerSentEventGenerator();

// Sends the response headers. 
// If your framework has its own way of sending response headers, manually send the headers returned by `ServerSentEventGenerator::headers()` instead.
$sse->sendHeaders();
```

--------------------------------

### Association Field Save/Retrieve

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/hyperfields.md

Example of saving and retrieving data for an association field.

```php
hf_update_field('related_posts', [12,45], 123, [ 'type' => 'association' ]);
$related = hf_get_field('related_posts', 123, [ 'default' => [] ]);
// $related is an array of post IDs by default
```

--------------------------------

### Configuration Management in HyperBlocks

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperblocks/docs/hyperblocks.md

Use the Config class to get, set, and manage configuration values. Register block paths and retrieve template extensions.

```php
use HyperBlocks\Config;

Config::get('auto_discovery', true);
Config::set('debug', true);
Config::registerBlockPath('/abs/path/to/dir');
Config::getBlockPaths();
Config::getTemplateExtensions();
Config::isDebug(): bool
Config::isCacheEnabled(): bool
Config::getRestNamespace(): string
Config::getEditorScriptHandle(): string
```

--------------------------------

### Tabs Field Declaration

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/hyperfields.md

Example of creating a tabs field to group other fields.

```php
$tabs = HyperFields::makeTabs('settings_tabs', 'Settings');
$tabs->addTab('general', 'General', [ HyperFields::makeField('text', 'site_tagline', 'Tagline') ]);
```

--------------------------------

### Enforce module import policies in production

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/transfer-and-content-export-import.md

Control module import behavior based on the environment. This example skips 'emails' and 'content' modules in production environments to enforce specific import policies.

```php
use HyperFields\Transfer\Manager;

// Skip selected modules in production.
add_filter(
    'hyperfields/transfer_manager/import/module_decision',
    static function (array $decision, string $moduleKey, $payload, array $context, array $bundle): array {
        if (wp_get_environment_type() === 'production' && in_array($moduleKey, ['emails', 'content'], true)) {
            return [
                'action' => 'skip',
                'reason' => 'blocked_in_production',
            ];
        }

        return $decision;
    },
    10,
    5
);
```

--------------------------------

### Number field save/retrieve

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/hyperfields.md

Example of saving and retrieving a number field value.

```php
hf_update_field('priority', 20, 123, [ 'type' => 'number' ]);
$priority = (int) hf_get_field('priority', 123, [ 'default' => 0 ]);

```

--------------------------------

### Textarea field save/retrieve

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/hyperfields.md

Example of saving and retrieving a textarea field value.

```php
hf_update_field('bio', '<p>Bio here</p>', 'user_45', [ 'type' => 'textarea' ]);
$bio = hf_get_field('bio', 'user_45', [ 'default' => '' ]);
echo wp_kses_post($bio); // allow basic tags if your workflow permits

```

--------------------------------

### Text field save/retrieve

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperfields/docs/hyperfields.md

Example of saving and retrieving a text field value.

```php
hf_update_field('site_tagline', 'Hello world', 'options', [ 'type' => 'text' ]);
$tagline = hf_get_field('site_tagline', 'options', [ 'default' => '' ]);
echo esc_html($tagline);
```

--------------------------------

### Configure HyperBlocks Paths and Settings

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperblocks/AGENTS.md

Use the static Config class to manage HyperBlocks settings. Register block directories, retrieve configuration values, and set runtime configurations. This is essential for initializing HyperBlocks and controlling its behavior.

```php
use HyperBlocks\Config;

Config::registerBlockPath('/path/to/blocks');  // add a directory to scan for blocks
Config::get('auto_discovery', true);           // read a value
Config::set('debug', true);                    // set at runtime

```

--------------------------------

### Passing Data via URL Parameters

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperpress-core/docs/how-to-use.md

Shows how to pass data to templates using query parameters in GET requests.

```text
/wp-html/v1/live-search?search=hello
/wp-html/v1/related-posts?category_id=5
```

--------------------------------

### hp_ds_location() redirect

Source: https://github.com/estebanforge/hyperpress/blob/main/vendor/estebanforge/hyperpress-core/docs/datastar-helpers.md

Example of redirecting the browser to a new URL via SSE.

```php
// Redirect after processing
hp_ds_location('/dashboard');

// Redirect to external URL
hp_ds_location('https://example.com/success');

```