ACF Composer

https://github.com/log1x/acf-composer
Admin
ACF Composer is a development tool for Sage 10 and ACF, enabling programmatic creation and...
Tokens:44,442
Snippets:370
Trust Score:9.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Retrieve manifest as array with example fields

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/manifest.md

Shows how to get the raw manifest collection as a PHP array with an example structure of a field group.

```php
$manifest = app('AcfComposer')->manifest()->toArray();
// e.g. ['App\Fields\Example' => [ 'key' => 'example', 'fields' => [...], ... ]]
```

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

### Run acf:options command

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/console-commands.md

Example usage of the acf:options command. The first creates a basic options page, the second uses the --full flag for a complete configuration example.

```bash
wp acorn acf:options ExampleOptions
wp acorn acf:options Options --full
```

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

### acf:partial usage example

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/console-commands.md

Usage example for the acf:partial command. Creates src/Fields/Partials/{Name}.php from partial.stub.

```bash
wp acorn acf:partial ListItems
```

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

### Usage Example

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/widget.md

Complete example of a custom widget class implementing the Widget contract, including the required methods and field definitions.

```APIDOC
## Usage Example

### Description
Full example of a custom widget class extending the Widget base class, implementing the required contract methods and defining fields.

### Example
```php
<?php

namespace App\Widgets;

use Log1x\AcfComposer\Builder;
use Log1x\AcfComposer\Widget;

class ExampleWidget extends Widget
{
    public $name = 'Example Widget';
    public $description = 'Lorem ipsum...';

    public function with()
    {
        return ['items' => $this->items()];
    }

    public function title()
    {
        return get_field('title', $this->widget->id);
    }

    public function fields()
    {
        $fields = Builder::make('example_widget');

        $fields->addText('title');
        $fields->addRepeater('items')->addText('item')->endRepeater();

        return $fields->build();
    }

    public function items()
    {
        return get_field('items', $this->widget->id) ?: [];
    }
}
```
```

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

### make() static factory example

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/composer.md

Creates a new instance of ExampleField using the ACF Composer container. Uses late static binding so subclasses get their own type.

```php
$composer = ExampleField::make(app('AcfComposer'));
```

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

### Full widget class example

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/widget.md

Complete example of a custom widget class extending the Widget base, implementing required methods and defining fields.

```php
<?php

namespace App\Widgets;

use Log1x\AcfComposer\Builder;
use Log1x\AcfComposer\Widget;

class ExampleWidget extends Widget
{
    public $name = 'Example Widget';
    public $description = 'Lorem ipsum...';

    public function with()
    {
        return ['items' => $this->items()];
    }

    public function title()
    {
        return get_field('title', $this->widget->id);
    }

    public function fields()
    {
        $fields = Builder::make('example_widget');

        $fields->addText('title');
        $fields->addRepeater('items')->addText('item')->endRepeater();

        return $fields->build();
    }

    public function items()
    {
        return get_field('items', $this->widget->id) ?: [];
    }
}
```

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

### ExampleOptions usage example

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/options.md

Example consumer class extending Options. Sets name, title, capability 'manage_options', icon 'dashicons-admin-generic', position 30, and parent 'acf-options-general' to nest under an existing page. Implements fields() using Builder to add a repeater with a text field.

```php
<?php

namespace App\Options;

use Log1x\AcfComposer\Builder;
use Log1x\AcfComposer\Options as Field;

class ExampleOptions extends Field
{
    public $name = 'Example Options';
    public $title = 'Example Options | Options';
    public $capability = 'manage_options';
    public $icon = 'dashicons-admin-generic';
    public $position = 30;

    // Nest under an existing page
    public $parent = 'acf-options-general';

    public function fields()
    {
        $fields = Builder::make('example_options');
        $fields->addRepeater('items')->addText('item')->endRepeater();

        return $fields->build();
    }
}
```

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

### Run acf:widget command

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/console-commands.md

Example usage of the acf:widget command to create a widget named ExampleWidget.

```bash
wp acorn acf:widget ExampleWidget
```

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

### ExampleBlock class usage example

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/block.md

Complete example of a custom ACF Composer block class, showing property definitions, with(), fields(), items(), and assets() methods.

```php
<?php

namespace App\Blocks;

use Log1x\AcfComposer\Block;
use Log1x\AcfComposer\Builder;

class ExampleBlock extends Block
{
    public $name = 'Example Block';
    public $description = 'Lorem ipsum...';
    public $category = 'common';
    public $icon = 'star-half';
    public $supports = ['align' => true, 'mode' => true];
    public $styles = ['light', 'dark'];
    public $template = ['core/paragraph' => ['placeholder' => 'Hello']];
    public $usePostMeta = true;

    public function with()
    {
        return ['items' => $this->items()];
    }

    public function fields()
    {
        $fields = Builder::make('example_block');
        $fields->addRepeater('items')->addText('item')->endRepeater();
        return $fields->build();
    }

    public function items()
    {
        return get_field('items') ?: [];
    }

    public function assets(array $block): void
    {
        // enqueue_block_assets
    }
}
```

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

### AcfComposer instantiation

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/acf-composer.md

Example of manually instantiating the AcfComposer class, though using AcfComposer::make() is recommended.

```php
$composer = new AcfComposer($app); // rarely used directly; use AcfComposer::make() instead
```

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

### Generate a full options page stub with --full

Source: https://github.com/log1x/acf-composer/blob/master/README.md

Generate an options page stub with additional configuration examples by passing the --full flag to the wp acorn acf:options command.

```bash
$ wp acorn acf:options Options --full
```

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

### acf:field usage examples

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/console-commands.md

Usage examples for the acf:field command. Creates src/Fields/{Name}.php from field.stub. The --force flag overwrites existing files.

```bash
wp acorn acf:field ExampleField
wp acorn acf:field ExampleField --force
```

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

### Install ACF Composer via Composer

Source: https://github.com/log1x/acf-composer/blob/master/README.md

Install ACF Composer via Composer. Requires Sage >= 10.0, Acorn >= 3.0, and ACF Pro >= 5.8.0.

```bash
$ composer require log1x/acf-composer
```

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

### wp acorn about output

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/service-provider.md

Example output of the 'wp acorn about' integration. Shows the ACF Composer section with Status (CACHED or NOT CACHED) and Version.

```text
ACF Composer
  Status  ...... CACHED / NOT CACHED
  Version ...... 3.x.x
```

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

### Example: multiple field groups

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/field.md

Shows a Field subclass returning an array of FieldsBuilders, each with its own location and fields. Demonstrates how to register multiple field groups in one composer.

```php
<?php

namespace App\Fields;

use Log1x\AcfComposer\Builder;
use Log1x\AcfComposer\Field;

class Settings extends Field
{
    public function fields()
    {
        return [
            Builder::make('settings_general')
                ->setLocation('options_page', '==', 'settings')
                ->addText('company_name')
                ->build(),
            Builder::make('settings_contact')
                ->setLocation('options_page', '==', 'settings')
                ->addEmail('contact_email')
                ->build(),
        ];
    }
}
```

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

### handleTemplate: Setting a block template

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/block.md

Example of a block template array passed to handleTemplate. The template uses core/heading and core/paragraph blocks with placeholders.

```php
$this->template = [
    'core/heading' => ['placeholder' => 'Hello World'],
    'core/paragraph' => ['placeholder' => 'Welcome.'],
];
```

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

### Partial::compose() example

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/field.md

Shows a Partial subclass returning a FieldsBuilder without calling build(). The consumer's build() is applied to it, allowing the partial to be embedded into other composers.

```php
<?php

namespace App\Fields\Partials;

use Log1x\AcfComposer\Builder;
use Log1x\AcfComposer\Partial;

class ListItems extends Partial
{
    public function fields()
    {
        $fields = Builder::make('listItems');
        $fields->addRepeater('items')->addText('item')->endRepeater();

        return $fields; // no ->build()
    }
}
```

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

### acf:block usage examples

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/console-commands.md

Usage examples for the acf:block command. Creates a block class in src/Blocks/ and a view resources/views/blocks/{slug}.blade.php. The --localize flag uses block.localized.stub for translation-ready name and description.

```bash
wp acorn acf:block ExampleBlock
wp acorn acf:block Example --localize
```

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

### InteractsWithPartial trait get() method

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/composer.md

Provides a get method that resolves partials. Deprecated: use addPartial() on Builder instead.

```php
trait InteractsWithPartial
{
    protected function get($partial = null)
    {
        // ...
    }
}
```

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

### setLocation() example

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/builder.md

Sets the field group location using the parent FieldsBuilder::setLocation() method and attaches the parent context to the returned LocationBuilder.

```php
$fields->setLocation('post_type', '==', 'post');
```

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

### Run acf:cache command

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/console-commands.md

Example usage of the acf:cache command. The first caches all field groups and blocks, the second shows the cache status, and the third writes only the field group manifest.

```bash
wp acorn acf:cache
wp acorn acf:cache --status
wp acorn acf:cache --manifest   # write only the field group manifest
```

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

### Catch DuplicateKeyException

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/errors.md

Example of catching DuplicateKeyException when calling handleComposers(). The exception is thrown during the acf/init WordPress filter inside boot(); in a plain request it propagates through the filter callback.

```php
use Log1x\AcfComposer\Exceptions\DuplicateKeyException;

try {
    app('AcfComposer')->handleComposers();
} catch (DuplicateKeyException $e) {
    // e.g. log and surface the conflicting key
    report($e);
}

```

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

### Search field types with acf:usage

Source: https://github.com/log1x/acf-composer/blob/master/README.md

Searches for registered field types and displays basic information plus a usage example with all possible options.

```sh
$ wp acorn acf:usage
```

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

### Example: single field group

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/field.md

Shows a Field subclass returning a single FieldsBuilder. The fields() method builds a field group with a repeater and sets its location to post type 'post'.

```php
<?php

namespace App\Fields;

use Log1x\AcfComposer\Builder;
use Log1x\AcfComposer\Field;

class Example extends Field
{
    public function fields()
    {
        $fields = Builder::make('example');

        $fields
            ->setLocation('post_type', '==', 'post')
            ->addRepeater('items')->addText('item')->endRepeater();

        return $fields->build();
    }
}
```

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

### Override show() to hide widget on 404 pages

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/widget.md

Override show() to conditionally render the widget. Returning false early-returns from front-end rendering without output. The example hides the widget on 404 pages.

```php
// Hide on 404 pages
public function show(): bool
{
    return ! is_404();
}
```

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

### boot(): void

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/acf-composer.md

Boots the AcfComposer by binding WordPress hooks and initializing components.

```APIDOC
## `boot(): void`

### Description
Binds WordPress hooks and initializes the composer. It registers the default path, handles blocks and widgets, registers the `acf/init` filter, and renders Alpine support into the admin footer.

### Method
`boot`

### Parameters
None.

### Request Example
```php
/** In AcfComposerServiceProvider::boot() */
$composer->boot();
```

### Response
Returns `void`.
```

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

### Booting the AcfComposer instance

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/acf-composer.md

The boot method binds necessary WordPress hooks and initializes block and widget handling.

```php
/** In AcfComposerServiceProvider::boot() */
$composer->boot();
```

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

### handleWidgets(): void

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/acf-composer.md

Instantiates all legacy widget classes queued in `$legacyWidgets` and appends the results to the composers array.

```APIDOC
## `handleWidgets(): void`

### Description
Instantiates every class queued in `$this->legacyWidgets` (`$composer::make($this)->handle()`) and appends the result to `$this->composers[$namespace]`, then resets `$this->legacyWidgets = []`.

### Method
`handleWidgets`

### Parameters
None.

### Return Value
`void`

### Example
```php
$composer->handleWidgets();
```
```

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

### Add partial to field with addPartial

Source: https://github.com/log1x/acf-composer/blob/master/README.md

Example field that includes the ListItems partial by passing its ::class constant to ->addPartial().

```php
<?php

namespace App\Fields;

use App\Fields\Partials\ListItems;
use Log1x\AcfComposer\Builder;
use Log1x\AcfComposer\Field;

class Example extends Field
{
    /**
     * The field group.
     *
     * @return array
     */
    public function fields()
    {
        $fields = Builder::make('example');

        $fields
            ->setLocation('post_type', '==', 'post');

        $fields
            ->addPartial(ListItems::class);

        return $fields->build();
    }
}
```

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

### Define the acf:upgrade command with signature and run it

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/console-commands.md

Run this command to scan registered composer paths for v2-era patterns and apply replacements to v3 syntax. It lists affected files, asks for confirmation, then rewrites each file and reports per-file tasks.

```php
protected $signature = 'acf:upgrade';
```

```bash
wp acorn acf:upgrade
```

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

### Run acf:ide-helpers command with --path option

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/console-commands.md

Run the acf:ide-helpers command using wp acorn, writing the IDE helpers to _ide-helpers.php in the base path.

```bash
wp acorn acf:ide-helpers --path=_ide-helpers.php
```

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

### Catch InvalidFieldsException

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/errors.md

Example of catching InvalidFieldsException when calling getFields(). The exception message is 'Fields must be an array or instance of Log1x\AcfComposer\Builder.'.

```php
use Log1x\AcfComposer\Exceptions\InvalidFieldsException;

try {
    $field->getFields();
} catch (InvalidFieldsException $e) {
    echo $e->getMessage(); // 'Fields must be an array or instance of Log1x\AcfComposer\Builder.'
}

```

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

### Retrieve a composer instance with getComposer

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/acf-composer.md

Demonstrates using getComposer to find a composer class by its render template, or aborting with a 404 if not found.

```php
$composer = app('AcfComposer')->getComposer($block['render_template'] ?? '')
    ?? abort(404);
```

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

### compose(): ?self

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/block.md

The registration entry point that initializes block attributes, defaults, and registers the block with WordPress. Returns the block instance or null if the block name is blank.

```APIDOC
## compose(): ?self

### Description
The registration entry point (from `Composer::handle()` lifecycle). It merges attributes, returns null when the block name is blank, sets default slug, view, and namespace, sets the field-group location, and registers the block either from a cached block.json or programmatically.

### Method
compose

### Returns
- `?self` - Returns the block instance, or null when `getName()` is blank.

### Behavior
1. `mergeAttributes()`.
2. Returns `null` when `getName()` is blank.
3. Defaults `slug` (`Str::slug(Str::kebab($name))`), `view` (`blocks.{slug}`), `namespace` (`{prefix}{slug}`).
4. Sets the field-group location to `block == {namespace}` if none is defined.
5. Registers from the cached `block.json` when it exists, otherwise registers programmatically.
6. Returns `$this`.
```

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

### registerDefaultPath(): void

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/acf-composer.md

Registers the default theme `app/` directory as a composer path.

```APIDOC
## `registerDefaultPath(): void`

### Description
Registers `$this->app->path()` (the theme `app/` directory) via `registerPath()`.

### Method
`registerDefaultPath`

### Parameters
None.

### Return Value
`void`

### Example
```php
$composer->registerDefaultPath();
```
```

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

### Register console commands in boot()

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/service-provider.md

Registers the console commands when running in console. These commands are available via wp acorn and include make, cache, clear, and utility commands.

```php
$this->commands([
    Console\BlockMakeCommand::class,
    Console\CacheCommand::class,
    Console\ClearCommand::class,
    Console\FieldMakeCommand::class,
    Console\IdeHelpersCommand::class,
    Console\OptionsMakeCommand::class,
    Console\PartialMakeCommand::class,
    Console\StubPublishCommand::class,
    Console\UpgradeCommand::class,
    Console\UsageCommand::class,
    Console\WidgetMakeCommand::class,
]);
```

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

### Constructing AcfComposer with make()

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/acf-composer.md

The static make method is the canonical way to construct the container using the Acorn application instance.

```php
$composer = AcfComposer::make($this->app);
```

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

### settings(): Collection

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/block.md

Builds and caches the full block settings collection, including all key fields and optional context fields. Returns a Collection instance.

```APIDOC
## settings(): Collection

### Description
Builds the full block settings collection once, cached in `$this->settings`. Includes key fields such as name, title, description, category, icon, keywords, and more.

### Method
settings

### Returns
- `Collection` - The block settings collection.

### Key Fields
- `name` (string) - The block slug.
- `title` (string) - The block name.
- `description` (string) - The block description.
- `category` (string) - The block category.
- `icon` (mixed) - The block icon.
- `keywords` (array) - The block keywords.
- `post_types` (array) - The post types where the block is available.
- `mode` (string) - The block mode.
- `align` (string) - The block alignment.
- `attributes` (array) - The support attributes.
- `alignText` (string) - The text alignment, defaults to `align` if not set.
- `alignContent` (string) - The content alignment.
- `styles` (array) - The block styles.
- `supports` (array) - The block supports.
- `textdomain` (string) - The text domain.
- `acf_block_version` (string) - The ACF block version.
- `api_version` (string) - The API version.
- `validate` (bool) - Whether to validate.
- `use_post_meta` (bool) - Whether to use post meta.
- `render_callback` (callable) - The render callback.

### Optional Fields
- `parent` - Merged when populated.
- `ancestor` - Merged when populated.
- `example` - Merged from `$this->example` and the `example()` method result when `$this->example !== false`.
- `uses_context` - Merged when populated.
- `provides_context` - Merged when populated.
```

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

### show(): bool

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/widget.md

Returns true by default. Override to conditionally render the widget. Returning false early-returns from the front-end rendering without output.

```APIDOC
## `show(): bool`

### Description
Returns `true` by default. Override to conditionally render the widget. Returning `false` early-returns from the front-end rendering without output.

### Method
`show`

### Return Value
- **bool** - Whether to render the widget.

### Example
```php
// Hide on 404 pages
public function show(): bool
{
    return ! is_404();
}
```
```

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

### make(Application $app): self

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/acf-composer.md

Static factory method to create a new AcfComposer instance.

```APIDOC
## `make(Application $app): self`

### Description
Static factory returning a new instance of the AcfComposer container. This is the canonical way to construct the container.

### Method
`make`

### Parameters
- **$app** (`Roots\Acorn\Application`) - Required - The Acorn application instance.

### Request Example
```php
$composer = AcfComposer::make($this->app);
```

### Response
Returns a new `AcfComposer` instance.
```

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

### handle() composition lifecycle

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/composer.md

Calls optional beforeRegister() and afterRegister() hooks around compose(). Returns $this.

```php
public function handle(): self
{
    $this->call('beforeRegister');
    $this->compose();
    $this->call('afterRegister');

    return $this;
}
```

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

### make(string $name, array $config = []): self

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/builder.md

Static factory method for creating a new Builder instance. Initializes a field group with an optional configuration array.

```APIDOC
## Builder::make

### Description
Creates a new Builder instance with the given name and optional configuration.

### Method
`make`

### Signature
`public static make(string $name, array $config = []): self`

### Parameters
- **$name** (string) - Required - The field group key / name.
- **$config** (array) - Optional - Initial ACF field group configuration. Default: `[]`.

### Example
```php
$fields = Builder::make('example_field');
```
```

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

### settings() key fields array

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/block.md

Shows the structure of the block settings collection returned by settings(). It includes fields like name, title, and supports, with defaults for alignText and alignContent, and a render_callback that echoes the rendered block.

```php
[
    'name' => $this->slug,
    'title' => $this->getName(),
    'description' => $this->getDescription(),
    'category' => $this->category,
    'icon' => $this->getIcon(),
    'keywords' => $this->keywords,
    'post_types' => $this->post_types,
    'mode' => $this->mode,
    'align' => $this->align,
    'attributes' => $this->getSupportAttributes(),
    'alignText' => $this->align_text ?? $this->align,
    'alignContent' => $this->align_content,
    'styles' => $this->getStyles(),
    'supports' => $this->getSupports(),
    'textdomain' => $this->getTextDomain(),
    'acf_block_version' => $this->getBlockVersion(),
    'api_version' => $this->getApiVersion(),
    'validate' => $this->validate,
    'use_post_meta' => $this->usePostMeta,
    'render_callback' => fn (...) => echo $this->render(...),
]
```

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

### Cache and clear commands

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/manifest.md

Commands to run caching during deployment: wp acorn acf:cache and wp acorn acf:clear.

```bash
# via the acf:cache command (see console-commands.md):
wp acorn acf:cache
wp acorn acf:clear
```

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

### compose() method

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/options.md

Composes the options page. Returns null if name is blank; defaults slug to Str::slug(name) and title to name; auto-sets location to options_page == slug when unset; registers via acf_add_options_page() unless menu is false, merging base array with settings (extra args win); returns $this.

```php
public function compose()
{
    if (blank($this->getName())) {
        return null;
    }

    if (empty($this->slug)) {
        $this->slug = Str::slug($this->getName());
    }

    if (blank($this->getTitle())) {
        $this->title = $this->getName();
    }

    if (! Arr::has($this->fields, 'location.0.0')) {
        Arr::set($this->fields, 'location.0.0', [
            'param' => 'options_page',
            'operator' => '==',
            'value' => $this->slug,
        ]);
    }

    $this->register(function () {
        if (! $this->menu) {
            return;
        }

        acf_add_options_page(
            array_merge([
                'menu_title' => $this->getName(),
                'menu_slug' => $this->slug,
                'page_title' => $this->getTitle(),
                'capability' => $this->capability,
                'position' => $this->position,
                'parent_slug' => $this->parent,
                'icon_url' => $this->icon,
                'redirect' => $this->redirect,
                'post_id' => $this->post,
                'autoload' => $this->autoload,
                'update_button' => $this->updateButton(),
                'updated_message' => $this->updatedMessage(),
            ], $this->settings)
        );
    });

    return $this;
}
```

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

### FlexibleContentBuilder usage with addFlexibleContent and addLayout

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/builder.md

Demonstrates adding a flexible content field with two layouts: one using a Partial class and one with a label argument.

```php
$fields
    ->addFlexibleContent('content')
        ->addLayout(FeatureLayout::class)   // Partial as a layout
        ->addLayout('cards', ['label' => 'Cards'])
    ->endFlexibleContent();
```

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

### Auto-discover provider via composer.json extra

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/service-provider.md

Composer.json extra configuration that auto-discovers the service provider. This entry is required for Acorn to load the provider automatically.

```json
"extra": {
    "acorn": {
        "providers": [
            "Log1x\\AcfComposer\\Providers\\AcfComposerServiceProvider"
        ]
    }
}
```

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

### render($block, $content = '', $preview = false, $post_id = 0, $wp_block = false, $context = false)

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/block.md

Renders the block by populating render-time properties, enqueuing assets, and returning the view output.

```APIDOC
## `render($block, $content = '', $preview = false, $post_id = 0, $wp_block = false, $context = false)`

### Description
Renders the block by populating render-time properties, enqueuing assets, and returning the view output.

### Method
`render`

### Parameters
- **$block** (array) - Required - The ACF block array.
- **$content** (string) - Optional - Inner block content. Default `''`.
- **$preview** (bool) - Optional - Preview mode. Default `false`.
- **$post_id** (int) - Optional - Post ID. Default `0`.
- **$wp_block** (\WP_Block) - Optional - Block instance. Default `false`.
- **$context** (array) - Optional - Block context. Default `false`.

### Returns
- **string** - The rendered view output.

### Details
- Populates render-time properties: `$this->block` (object), `$this->content`, `$this->preview`, `$this->post_id`, `$this->instance`, `$this->context`, `$this->post` (via `get_post()`), `$this->classes`, `$this->style`, `$this->inlineStyle`.
- Converts a `$template` array to JSON.
- Enqueues `assets($block)` on `enqueue_block_assets` when outside the admin.
- Returns `$this->view($this->view, ['block' => $this, 'attributes' => $this->getComponentAttributeBag()])`.

### Example
```php
echo $block->render($block, $content, $is_preview, $post_id, $wp_block, $context);
```
```

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

### Define composer defaults and fields

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/composer.md

Demonstrates how to set composer-level defaults in the $defaults property and apply them automatically to fields created via the Builder.

```php
// Example: defaults from config + a composer-level default
protected $defaults = ['true_false' => ['ui' => 1]];

public function fields()
{
    $fields = Builder::make('example');
    $fields->addTrueFalse('show_title'); // gains ['ui' => 1] automatically
    return $fields->build();
}
```

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

### getSupports(): array

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/block.md

Camel-cases the supports keys and merges with raw values, folding alignText into typography.textAlign.

```APIDOC
## getSupports(): array

### Description
Camel-cases `$this->supports` keys (`align_text` → `alignText`), merges with the raw values, and folds `alignText` into `supports.typography.textAlign`.

### Method
GET

### Endpoint
N/A (PHP method)

### Parameters
None

### Returns
- **array** - The processed supports array.

```

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

### Manifest constructor initializes cache path and loads manifest

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/manifest.md

The constructor stores the composer instance, computes the cache path from the config (default storage_path/framework/cache) joined with /acf-composer, and loads existing manifest.php into a collection if it exists.

```php
public function __construct(AcfComposer $composer)
{
    $this->composer = $composer;

    $this->path = Str::finish(
        config('acf-composer.manifest', storage_path('framework/cache')),
        '/acf-composer'
    );

    $this->manifest = $this->exists()
        ? Collection::make(require $this->path())
        : Collection::make();
}
```

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

### GroupBuilder class extending GroupBuilderBase

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/builder.md

Constructor accepts a name, type (default 'group'), and config array. It creates a Builder instance and sets its parent context to this GroupBuilder.

```php
class GroupBuilder extends GroupBuilderBase
{
    use HasParentContext;

    protected $fieldsBuilder;

    public function __construct($name, $type = 'group', $config = [])
    {
        parent::__construct($name, $type, $config);

        $this->fieldsBuilder = Builder::make($name);
        $this->fieldsBuilder->setParentContext($this);
    }
}
```

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

### jsonPath(): string

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/block.md

Returns the path to the block's block.json file.

```APIDOC
## `jsonPath(): string`

### Description
Returns the path to the block's `block.json` file.

### Method
`jsonPath`

### Returns
- **string** - The path to the block.json file.

### Details
- `manifest()->path("blocks/{$this->slug}/block.json")` — see Manifest.
```

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

### Run acf:stubs command

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/console-commands.md

Run the acf:stubs command using wp acorn to publish the stub files.

```bash
wp acorn acf:stubs
```

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

### addPartials() with list and map

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/builder.md

Adds multiple partials at once. String values are treated as partial names with no arguments; array values map partial names to their classes.

```php
$fields->addPartials([
    ListItems::class,
    'accordion' => Accordion::class,
]);
```

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

### Run acf:usage command with and without field argument

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/console-commands.md

Run the acf:usage command using wp acorn. The first invocation shows a search prompt; the second directly targets the 'select' field type.

```bash
wp acorn acf:usage
wp acorn acf:usage select
```

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

### register(string $composer, string $namespace): bool

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/acf-composer.md

Registers a composer class under a namespace, returning a boolean indicating success.

```APIDOC
## `register(string $composer, string $namespace): bool`

### Description
Registers a composer class under a namespace. Returns `false` (and registers nothing) when the class is not a subclass of `Log1x\AcfComposer\Composer`, is a subclass of `Partial`, or is abstract. `Widget` subclasses are queued in `$legacyWidgets[$namespace]` and return `true`. All other composers are appended to `$composers[$namespace]` and return `true`.

### Method
`register`

### Parameters
#### Path Parameters
- **$composer** (string) - Required - Fully-qualified Composer class name.
- **$namespace** (string) - Required - Namespace key grouping the composer.

### Return Value
Returns `true` if the composer was registered or queued, `false` otherwise.

### Example
```php
$composer->register(\App\Fields\Example::class, 'App');
```
```

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

### getIcon(): string|array

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/block.md

Returns the icon, handling asset: prefixed icons via Roots\asset.

```APIDOC
## getIcon(): string|array

### Description
Arrays pass through; `asset:` prefixed icons (`'asset:images/icon'` — `.svg` appended, dots→slashes) are read via `Roots\asset(...)->contents()`; anything else returns the string as-is.

### Method
GET

### Endpoint
N/A (PHP method)

### Parameters
None

### Returns
- **string|array** - The icon value.

```

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

### with() method implementation

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/widget.md

Returns the data array for the widget Blade view. Required by the Widget contract.

```php
public function with()
{
    return ['items' => $this->items()];
}
```

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

### Register a composer namespace

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/acf-composer.md

Registers a composer namespace from a specified path within a theme.

```php
// Register a composer namespace from a bundled theme
$composer->registerPath('/path/to/theme/app');
```

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

### Builder::make() static factory

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/builder.md

Creates a new Builder instance using the static factory method make(). The name parameter is required and serves as the field group key.

```php
$fields = Builder::make('example_field');
```

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

### Widget interface with title() and with() methods

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/types.md

Defines the contract for a Widget. Implemented on Log1x\AcfComposer\Widget by consumers. title() returns the widget title and with() returns data passed to the rendered widget view.

```php
interface Widget
{
    public function title();
    public function with();
}
```

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

### getApiVersion(): int

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/block.md

Returns the API version, defaulting to 2.

```APIDOC
## getApiVersion(): int

### Description
Returns `$this->apiVersion ?? 2`.

### Method
GET

### Endpoint
N/A (PHP method)

### Parameters
None

### Returns
- **int** - The API version.

```

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

### render() consumer call

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/block.md

Typical consumer render path for the render() method, invoked by the registered render callback. Passes the block array, content, preview flag, post ID, WP_Block instance, and context.

```php
// typical consumer render path — invoked by the registered render callback
echo $block->render($block, $content, $is_preview, $post_id, $wp_block, $context);
```

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

### __call($method, $arguments)

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/builder.md

Magic dispatch for addXxx() methods not explicitly defined. Resolves custom field types from parent context or configured types, otherwise falls back to the parent field factory.

```APIDOC
## `__call($method, $arguments)`

### Description
Magic dispatch for every `addXxx(...)` not explicitly defined. If a parent context is set and knows a custom field type for the method, it creates that field. Otherwise it checks configured custom types via `config('acf.types')`, and finally falls back to the ACF Builder field factory.

### Method
`__call`

### Parameters
- **$method** (string) - The name of the method being called.
- **$arguments** (array) - The arguments passed to the method.

### Behavior
1. If a parent context is set and the context knows a custom field type for `$method`, creates the field with that type.
2. Otherwise if `$this->getFieldType($method)` matches a configured custom type (see `config('acf.types')`), creates the field.
3. Otherwise falls through to `parent::__call(...)` (the ACF Builder field factory).

### Example
`addEditorPalette('color')` works after configuring `'types' => ['editorPalette' => 'editor_palette']`.
```

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

### Write manifest file content expression

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/manifest.md

The write() method writes a PHP file that returns a var_export'd array of the manifest collection.

```php
'<?php return '.var_export($manifest, true).';'
```

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

### addField($name, $type, array $args = [])

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/builder.md

Creates and initializes a new FieldBuilder for the given name, type, and settings.

```APIDOC
## Builder::addField

### Description
Creates a new `FieldBuilder` with the specified name, type, and settings, then initializes it on the parent context.

### Parameters
- **$name** (string) - Required - Field name.
- **$type** (string) - Required - ACF field type.
- **$args** (array) - Optional - Field settings. Default: `[]`.

### Returns
Returns the `FieldBuilder` instance.

### Example
```php
$field = $fields->addField('text_field', 'text', ['required' => true]);
```
```

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

### getBlockVersion(): int

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/block.md

Returns the block version, defaulting to 2.

```APIDOC
## getBlockVersion(): int

### Description
Returns `$this->blockVersion ?? 2`.

### Method
GET

### Endpoint
N/A (PHP method)

### Parameters
None

### Returns
- **int** - The block version.

```

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

### getTextDomain(): string

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/block.md

Returns the text domain, falling back to the theme's TextDomain or 'acf-composer'.

```APIDOC
## getTextDomain(): string

### Description
`$this->textDomain ?? wp_get_theme()?->get('TextDomain') ?? 'acf-composer'`.

### Method
GET

### Endpoint
N/A (PHP method)

### Parameters
None

### Returns
- **string** - The text domain.

```

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

### Generate an ACF block with wp acorn acf:block

Source: https://github.com/log1x/acf-composer/blob/master/README.md

Generates a new ACF block using the Acorn command `wp acorn acf:block ExampleBlock`. The generated PHP class extends `Log1x\AcfComposer\Block` and defines the block name, description, category, icon, data passed to the view via `with()`, and a field group built with `Builder::make('example_block')` containing a repeater field. The block is ready to use out of the box.

```bash
$ wp acorn acf:block ExampleBlock
```

```php
<?php

namespace App\Blocks;

use Log1x\AcfComposer\Block;
use Log1x\AcfComposer\Builder;

class ExampleBlock extends Block
{
    /**
     * The block name.
     *
     * @var string
     */
    public $name = 'Example Block';

    /**
     * The block description.
     *
     * @var string
     */
    public $description = 'Lorem ipsum...';

    /**
     * The block category.
     *
     * @var string
     */
    public $category = 'common';

    /**
     * The block icon.
     *
     * @var string|array
     */
    public $icon = 'star-half';

    /**
     * Data to be passed to the block before rendering.
     *
     * @return array
     */
    public function with()
    {
        return [
            'items' => $this->items(),
        ];
    }

    /**
     * The block field group.
     *
     * @return array
     */
    public function fields()
    {
        $fields = Builder::make('example_block');

        $fields
            ->addRepeater('items')
                ->addText('item')
            ->endRepeater();

        return $fields->build();
    }

    /**
     * Return the items field.
     *
     * @return array
     */
    public function items()
    {
        return get_field('items') ?: [];
    }
}
```

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

### getClasses(): string

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/block.md

Builds the block class attribute from WP block supports, appends position and full-height classes, and replaces namespace slug.

```APIDOC
## getClasses(): string

### Description
Builds the block class attribute from the WP block supports, appends `is-position-{alignContent}` when set, appends `full-height` for `fullHeight`, and replaces the namespace slug (`acf_slugify($this->namespace)`) with `$this->slug`. Returns `''` in preview.

### Method
GET

### Endpoint
N/A (PHP method)

### Parameters
None

### Returns
- **string** - The class attribute string.

```

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

### Widget compose() method

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/widget.md

Composes the widget. Returns null without registering when fields or name are empty, defaults slug to Str::slug($name), auto-sets the field location to 'widget == {slug}' when unset, resolves $this->widget from wp_registered_widgets by name, and registers the anonymous WP_Widget subclass on widgets_init at priority 20.

```php
public function compose()
{
    if (empty($this->fields) || empty($this->name)) {
        return;
    }

    if (empty($this->slug)) {
        $this->slug = Str::slug($this->name);
    }

    if (! Arr::has($this->fields, 'location.0.0')) {
        Arr::set($this->fields, 'location.0.0', [
            'param' => 'widget',
            'operator' => '==',
            'value' => $this->slug,
        ]);
    }

    $this->register(function () {
        $this->widget = (object) $this->collect(
            Arr::get($GLOBALS, 'wp_registered_widgets')
        )->filter(fn ($value) => $value['name'] === $this->name)->pop();
    });

    add_filter('widgets_init', function () {
        register_widget($this->widget());
    }, 20);

    return $this;
}
```

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

### Run acf:clear command

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/console-commands.md

Run the acf:clear command using wp acorn to delete the manifest directory.

```bash
wp acorn acf:clear
```

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

### Consume AcfComposer singleton

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/service-provider.md

Consumes the AcfComposer singleton from the service container. The booted() method checks if composer registration is complete.

```php
use Log1x\AcfComposer\AcfComposer;

$composer = app('AcfComposer'); // AcfComposer

if ($composer->booted()) {
    // composer registration is complete
}
```

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

### Composer interface with compose() method

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/types.md

Defines the contract for a Composer. Implemented by Composer::compose() and its subclasses to compose and register fields.

```php
interface Composer
{
    public function compose();
}
```

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

### Generate an options page with wp acorn acf:options

Source: https://github.com/log1x/acf-composer/blob/master/README.md

Create an options page using the Acorn command and then define the generated PHP class. The command generates a new options page class, and the class extends Log1x\AcfComposer\Options, setting the menu name, document title, and a field group with a repeater field.

```bash
$ wp acorn acf:options ExampleOptions
```

```php
<?php

namespace App\Options;

use Log1x\AcfComposer\Builder;
use Log1x\AcfComposer\Options as Field;

class ExampleOptions extends Field
{
    /**
     * The option page menu name.
     *
     * @var string
     */
    public $name = 'Example Options';

    /**
     * The option page document title.
     *
     * @var string
     */
    public $title = 'Example Options | Options';

    /**
     * The option page field group.
     *
     * @return array
     */
    public function fields()
    {
        $fields = Builder::make('example_options');

        $fields
            ->addRepeater('items')
                ->addText('item')
            ->endRepeater();

        return $fields->build();
    }
}
```

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

### getInlineStyle(): string

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/block.md

Returns the style from getHtmlAttributes() or an empty string.

```APIDOC
## getInlineStyle(): string

### Description
Returns `$supports['style'] ?? ''` from `getHtmlAttributes()`.

### Method
GET

### Endpoint
N/A (PHP method)

### Parameters
None

### Returns
- **string** - The inline style string.

```

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

### Publish acf-composer config

Source: https://github.com/log1x/acf-composer/blob/master/_autodocs/api-reference/service-provider.md

Publishes the configuration file to config_path('acf.php') with the tag 'acf-composer'. Run this command to customize the composer behavior.

```bash
wp acorn vendor:publish --tag="acf-composer"
```
Tokens:
Raw