ACF Builder

https://github.com/stoutlogic/acf-builder
Admin
ACF Builder provides a fluent API and builder pattern to create, register, and reuse Advanced Custom...
Tokens:19,387
Snippets:69
Trust Score:7.6
License:GPL-2.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Run Tests with Gulp

Source: https://github.com/stoutlogic/acf-builder/blob/master/README.md

Demonstrates how to set up and run the project's tests using Gulp, a task runner, which includes installing dependencies and starting the task.

```bash
npm install
gulp
```

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

### Manual Installation of ACF Builder

Source: https://github.com/stoutlogic/acf-builder/wiki/Installing

For manual installation, copy the ACF Builder files into your theme or plugin directory. Ensure that the autoload.php file is included in your main PHP file (e.g., functions.php) to enable class autoloading.

```PHP
require_once('path/to/acf-builder/autoload.php');
```

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

### Install ACF Builder with Composer

Source: https://github.com/stoutlogic/acf-builder/wiki/Installing

The recommended method for installing ACF Builder is using Composer. This command adds the package to your project's dependencies.

```Shell
composer require stoutlogic/acf-builder
```

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

### Install ACF Builder via Composer

Source: https://github.com/stoutlogic/acf-builder/blob/master/README.md

Provides the command to install the ACF Builder library using Composer, the dependency manager for PHP.

```bash
composer require stoutlogic/acf-builder
```

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

### ACF Builder Tabs Example

Source: https://github.com/stoutlogic/acf-builder/wiki/Tabs

Demonstrates how to create tabs in ACF Builder by adding 'tab' fields to a FieldsBuilder object. Shows how to add text and WYSIWYG fields under one tab, and image and color picker fields under another.

```php
use StoutLogic\AcfBuilder\FieldsBuilder;

$banner = new FieldsBuilder('banner');
$banner
    ->addTab('Content')
    ->addText('title')
    ->addWysiwyg('content')
    
    ->addTab('Background Settings')
    ->addImage('background_image')
    ->addColorPicker('background_color');
```

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

### Run Tests with PHPUnit

Source: https://github.com/stoutlogic/acf-builder/blob/master/README.md

Shows how to execute the project's tests using PHPUnit, typically found within the vendor directory after installation.

```bash
vendor/bin/phpunit
```

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

### PHP: ACF Builder Field Key Generation Example

Source: https://github.com/stoutlogic/acf-builder/wiki/Generated-Keys

Demonstrates how ACF Builder generates namespaced keys for fields within a flexible content structure. The example shows a `FieldsBuilder` with flexible content, layouts, and nested fields, illustrating the resulting key hierarchy.

```php
$builder = new FieldsBuilder('page_content');
$builder->addFlexibleContent('sections')
              ->addLayout('banner')
                  ->addText('title')
                  ->addWysiwyg('content')
              ->addLayout('content_columns')
                  ->addRepeater('columns', ['min' => 1, 'max' => 2])
                      ->addWysiwyg('content');
```

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

### ACF Tab Endpoint Setting

Source: https://github.com/stoutlogic/acf-builder/wiki/Tabs

Shows how to use the `endPoint()` function after `addTab()` to denote the start of a new row or group of tabs, which can be helpful for managing many tabs.

```php
$banner
   ->addTab('Content')
   ...
   ->addTab('Settings')
       ->endPoint()
   ...
```

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

### Basic Repeater Field Setup

Source: https://github.com/stoutlogic/acf-builder/wiki/Repeater

Demonstrates how to create a basic repeater field named 'slides' with 'title' and 'content' sub-fields using ACF Builder.

```php
use StoutLogic\AcfBuilder\FieldsBuilder;

$slider = new FieldsBuilder('slider');
$slider
    ->addText('title')
    ->addRepeater('slides')
        ->addText('title')
        ->addWysiwyg('content');
```

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

### ACF Post Object Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Example of adding a Post Object field, enabling users to select posts from the WordPress site.

```php
$fields 
    ->addPostObject('post_object_field', [
        'label' => 'Post Object Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'post_type' => [],
        'taxonomy' => [],
        'allow_null' => 0,
        'multiple' => 0,
        'return_format' => 'object',
        'ui' => 1,
    ]);
```

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

### ACF Checkbox Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Example of creating a Checkbox field. This allows users to select multiple options from a list.

```php
$fields
    ->addCheckbox('checkbox_field', [
        'label' => 'Checkbox Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'choices' => [],
        'allow_custom' => 0,
        'save_custom' => 0,
        'default_value' => [],
        'layout' => 'vertical',
        'toggle' => 0,
        'return_format' => 'value',
    ]);
```

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

### Complex Location Logic with AND and OR

Source: https://github.com/stoutlogic/acf-builder/wiki/Location

Demonstrates how to implement complex conditional logic for field group visibility using `and` and `or` methods. The example shows how to create rules like '(post_type == page) or (post_type == post and post != 10)'. The generated 'location' array structure is also shown.

```php
use StoutLogic\AcfBuilder\FieldsBuilder;

$banner = new FieldsBuilder('banner');

$banner
    ->addText('title')
    ->addWysiwyg('content')
    ->setLocation('post_type', '==', 'page')
        ->or('post_type', '==', 'post')
        ->and('post', '!=', '10')
    ->addText('subtitle');
```

```php
...,
'fields' => [
    [
        'name' => 'title',
        ...
    ],
    [
        'name' => 'content',
        ...
    ],
    [
        'name' => 'subtitle',
        ...
    ],
],
'location' => [
    [
        [
            'param' => 'post_type',
            'operator'  =>  '==',
            'value' => 'page',
        ],
    ],
    [
        [
            'param' => 'post_type',
            'operator'  =>  '==',
            'value' => 'post',
        ],
        [
            'param' => 'post',
            'operator'  =>  '!=',
            'value' => '10',
        ],
    ],
]
...
```

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

### ACF True / False Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Example of implementing a True / False field. This field typically uses a toggle switch for binary choices.

```php
$fields 
    ->addTrueFalse('truefalse_field', [
        'label' => 'True / False Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'message' => '',
        'default_value' => 0,
        'ui' => 0,
        'ui_on_text' => '',
        'ui_off_text' => '',
    ]);
```

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

### ACF Gallery Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Example of how to add a Gallery field using ACF Builder. This field allows users to upload and manage multiple images.

```php
$fields 
    ->addGallery('gallery_field', [
        'label' => 'Gallery Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'min' => '',
        'max' => '',
        'insert' => 'append',
        'library' => 'all',
        'min_width' => '',
        'min_height' => '',
        'min_size' => '',
        'max_width' => '',
        'max_height' => '',
        'max_size' => '',
        'mime_types' => '',
    ]);
```

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

### Set Field Group Location

Source: https://github.com/stoutlogic/acf-builder/wiki/Location

Sets the location rules for a field group, determining where it will appear. The `setLocation` method takes parameters for the condition type, operator, and value. This example makes the field group appear on all 'page' post types.

```php
use StoutLogic\AcfBuilder\FieldsBuilder;

$banner = new FieldsBuilder('banner');
$banner
    ->addText('title')
    ->addWysiwyg('content')
    ->setLocation('post_type', '==', 'page');
```

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

### Modify Existing Field Group Locations

Source: https://github.com/stoutlogic/acf-builder/wiki/Location

Shows how to add new conditions to an existing field group's location rules using the `getLocation` method followed by `or` or `and`. This example adds a condition to display the banner field group on 'team_member' post types.

```php
$banner
    ->getLocation()
    ->or('post_type', '==', 'team_member');
```

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

### ACF Builder Field Configuration Shortcuts

Source: https://github.com/stoutlogic/acf-builder/wiki/Fields

Demonstrates using declarative shortcut methods like `setInstructions`, `setDefaultValue` to configure field properties after initial declaration, offering a more readable syntax.

```php
use StoutLogic\AcfBuilder\FieldsBuilder;

$background = new FieldsBuilder('background');
$background
    ->addImage('background_image', ['preview_size' => 'medium'])
    ->addTrueFalse('background_fixed', ['label' => 'Fixed'])
        ->setInstructions("Check to add a parallax effect where the background image doesn't move when scrolling")
    ->addColorPicker('background_color')
        ->setDefaultValue('#ffffff');
```

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

### ACF Builder Field Group Sample

Source: https://github.com/stoutlogic/acf-builder/wiki/Fields

Provides a sample PHP code snippet using ACF Builder to create a 'background' field group with image, true/false, and color picker fields, including custom configurations and instructions.

```php
use StoutLogic\AcfBuilder\FieldsBuilder;

$background = new FieldsBuilder('background');
$background
    ->addImage('background_image', ['preview_size' => 'medium'])
    ->addTrueFalse('background_fixed', [
        'label' => 'Fixed',
        'instructions' => "Check to add a parallax effect where the background image doesn't move when scrolling"
      ])
    ->addColorPicker('background_color', ['default_value' => '#ffffff']);

$background->build();
```

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

### Create Flexible Content Field with Layouts

Source: https://github.com/stoutlogic/acf-builder/wiki/Flexible-Content

Demonstrates creating a Flexible Content field named 'sections' with two layouts: 'banner' and 'content_columns'. The 'content_columns' layout includes a repeater.

```php
use StoutLogic\AcfBuilder\FieldsBuilder;

$content = new FieldsBuilder('page_content');
$content
    ->addFlexibleContent('sections')
        ->addLayout('banner')
            ->addText('title')
            ->addWysiwyg('content')
        ->addLayout('content_columns')
            ->addRepeater('columns', ['min' => 1, 'max' => 2])
                ->addWysiwyg('content');
```

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

### Reuse Layouts in Flexible Content

Source: https://github.com/stoutlogic/acf-builder/wiki/Flexible-Content

Shows how to create reusable layout configurations using separate FieldsBuilder instances and then add them to a Flexible Content field.

```php
use StoutLogic\AcfBuilder\FieldsBuilder;

$banner = new FieldsBuilder('banner');
$banner
    ->addText('title')
    ->addWysiwyg('content');

$columns = new FieldsBuilder('content_columns');
$columns
    ->addRepeater('columns', ['min' => 1, 'max' => 2])
        ->addWysiwyg('content');

$content = new FieldsBuilder('page_content');
$content
    ->addFlexibleContent('sections')
        ->addLayout($banner)
        ->addLayout($columns);
```

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

### Create and Register ACF Field Group

Source: https://github.com/stoutlogic/acf-builder/wiki/Using

Demonstrates creating a new field group named 'banner' with text, WYSIWYG, and image fields. It then sets the location rules to display this group on 'page' and 'post' post types and registers the field group using the 'acf/init' action.

```php
$banner = new StoutLogic\AcfBuilder\FieldsBuilder('banner');
$banner
    ->addText('title')
    ->addWysiwyg('content')
    ->addImage('background_image')
    ->setLocation('post_type', '==', 'page')
        ->or('post_type', '==', 'post');

add_action('acf/init', function() use ($banner) {
   acf_add_local_field_group($banner->build());
});
```

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

### Create Banner Field Group with ACF Builder

Source: https://github.com/stoutlogic/acf-builder/wiki/Home

Demonstrates how to create a 'banner' field group with a title, content editor, and background image using the ACF Builder library. It also shows how to set the location for this field group to apply to both pages and posts.

```php
$banner = new StoutLogic\AcfBuilder\FieldsBuilder('banner');
$banner
    ->addText('title')
    ->addWysiwyg('content')
    ->addImage('background_image')
    ->setLocation('post_type', '==', 'page')
        ->or('post_type', '==', 'post');
       
add_action('acf/init', function() use ($banner) {
   acf_add_local_field_group($banner->build());
});
```

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

### Reuse ACF Field Configurations

Source: https://github.com/stoutlogic/acf-builder/blob/master/README.md

Illustrates how to define a reusable field group ('background') and then include it in multiple other field groups ('banner', 'section'). This promotes code reuse and consistency across different ACF configurations.

```php
use StoutLogic\AcfBuilder\FieldsBuilder;

$background = new FieldsBuilder('background');
$background
    ->addTab('Background')
    ->addImage('background_image')
    ->addTrueFalse('fixed')
        ->instructions("Check to add a parallax effect where the background image doesn't move when scrolling")
    ->addColorPicker('background_color');

$banner = new FieldsBuilder('banner');
$banner
    ->addTab('Content')
    ->addText('title')
    ->addWysiwyg('content')
    ->addFields($background)
    ->setLocation('post_type', '==', 'page');

$section = new FieldsBuilder('section');
$section
    ->addTab('Content')
    ->addText('section_title')
    ->addRepeater('columns', ['min' => 1, 'layout' => 'block'])
        ->addTab('Content')
        ->addText('title')
        ->addWysiwyg('content')
        ->addFields($background)
        ->endRepeater()
    ->addFields($background)
    ->setLocation('post_type', '==', 'page');
```

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

### Repeater Field Configuration Settings

Source: https://github.com/stoutlogic/acf-builder/wiki/Repeater

Shows how to configure repeater fields with settings such as minimum and maximum number of items, custom button labels, and layout options (table, block, row).

```php
use StoutLogic\AcfBuilder\FieldsBuilder;

$slider = new FieldsBuilder('slider');
$slider
    ->addText('title')
    ->addRepeater('slides', [
            'min' => 1,
            'max' => 7,
            'button_label' => 'Add Slide',
            'layout' => 'block',
          ])
        ->addText('title')
        ->addWysiwyg('content');
```

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

### Instantiate FieldsBuilder with Defaults

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Groups

Demonstrates the default behavior when creating a new FieldsBuilder instance without any configuration options. The library automatically generates a 'key' and 'title' based on the provided name.

```php
$banner = new StoutLogic\AcfBuilder\FieldsBuilder('banner');
```

```json
[
    'key' => 'group_banner',
    'title' => 'Banner',
]
```

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

### ACF Field Group Array Configuration

Source: https://github.com/stoutlogic/acf-builder/wiki/Home

The output array configuration generated by `$banner->build()` for the banner field group. This JSON structure represents the field group's key, title, fields (with their types and labels), and location rules.

```json
{
    "key": "group_banner",
    "title": "Banner",
    "fields": [
        {
            "key": "field_banner_title",
            "name": "title",
            "label": "Title",
            "type": "text"
        },
        {
            "key": "field_banner_content",
            "name": "content",
            "label": "Content",
            "type": "wysiwyg"
        },
        {
            "key": "field_banner_background_image",
            "name": "background_image",
            "label": "Background Image",
            "type": "image"
        }
    ],
    "location": [
        [
            [
                "param": "post_type",
                "operator": "==",
                "value": "page"
            ]
        ],
        [
            [
                "param": "post_type",
                "operator": "==",
                "value": "post"
            ]
        ]
    ]
}
```

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

### Nested Flexible Content Fields

Source: https://github.com/stoutlogic/acf-builder/wiki/Flexible-Content

Illustrates how to embed a Flexible Content field within another Flexible Content field's layout, demonstrating nested structures.

```php
use StoutLogic\AcfBuilder\FieldsBuilder;

$content = new FieldsBuilder('page_content');
$content
    ->addFlexibleContent('sections')
        ->addLayout('content_columns')
            ->addRepeater('columns', ['min' => 1, 'max' => 2])
                ->addFlexibleContent('column_type', ['min' => 1, 'max' => 1])
                    ->addLayout('copy')
                        ->addWysiwyg('content')
                    ->addLayout('image')
                        ->addImage('image')
                    ->endFlexibleContent()
                ->endRepeater()
        ->addLayout('banner')
            ->addText('title')
            ->addWysiwyg('content');
```

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

### ACF Repeater Layout for Tabs

Source: https://github.com/stoutlogic/acf-builder/wiki/Tabs

Provides guidance on setting the repeater layout to 'block' or 'row' when using tabs within repeaters to prevent UI issues, as the default table layout can cause tabs to break.

```php
...
    ->addRepeater('columns', ['layout' => 'block']
...
```

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

### Create and Register ACF Field Group

Source: https://github.com/stoutlogic/acf-builder/blob/master/README.md

Demonstrates how to create a new ACF field group using FieldsBuilder, add various field types, set location rules, and register it using acf_add_local_field_group. The build() method generates the array structure required by ACF.

```php
$banner = new StoutLogic\AcfBuilder\FieldsBuilder('banner');
$banner
    ->addText('title')
    ->addWysiwyg('content')
    ->addImage('background_image')
    ->setLocation('post_type', '==', 'page')
        ->or('post_type', '==', 'post');

add_action('acf/init', function() use ($banner) {
   acf_add_local_field_group($banner->build());
});
```

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

### Conditional Field Visibility (PHP)

Source: https://github.com/stoutlogic/acf-builder/wiki/Conditions

Demonstrates how to make fields visible or hidden based on the values of other fields using ACF Builder's conditional logic. This includes simple equality/inequality checks and more complex AND/OR logic.

```php
use StoutLogic\AcfBuilder\FieldsBuilder;

$colors = new FieldsBuilder('colors');
$colors
    ->addRadio('color')
        ->addChoices('red', 'blue', 'green', 'other')
    ->addText('other_value')
        ->conditional('color', '==', 'other');
```

```php
use StoutLogic\AcfBuilder\FieldsBuilder;

$address = new FieldsBuilder('address');
$address
    ->addText('line1')
    ->addText('line2')
        ->conditional('line1', '!=', '');
```

```php
use StoutLogic\AcfBuilder\FieldsBuilder;

$banner = new FieldsBuilder('banner');
$banner
    ->addImage('background_image')
    ->addTrueFalse('add_title')
    ->addText('title')
        ->conditional('add_title', '==', '1')
    ->addRadio('title_color')
        ->addChoices('black', 'white')
        ->conditional('add_title', '==', '1')
    ->addRadio('title_background_color')
        ->addChoices(['transparent' => 'none'], 'black')
        ->conditional('add_title', '==', '1')
            ->and('title_color', '==', 'white');
```

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

### ACF Field Group Structure Output

Source: https://github.com/stoutlogic/acf-builder/blob/master/README.md

Shows the resulting array structure generated by the `$banner->build()` method, which is compatible with Advanced Custom Fields Pro's `acf_add_local_field_group` function. This includes field keys, names, labels, types, and location rules.

```php
[
    'key' => 'group_banner',
    'title' => 'Banner',
    'fields' => [
        [
            'key' => 'field_title',
            'name' => 'title',
            'label' => 'Title',
            'type' => 'text'
        ],
        [
            'key' => 'field_content',
            'name' => 'content',
            'label' => 'Content',
            'type' => 'wysiwyg'
        ],
        [
            'key' => 'field_background_image',
            'name' => 'background_image',
            'label' => 'Background Image',
            'type' => 'image'
        ],
    ],
    'location' => [
        [
            [
                'param' => 'post_type',
                'operator' => '==',
                'value' => 'page'
            ]
        ],
        [
            [
                'param' => 'post_type',
                'operator' => '==',
                'value' => 'post'
            ]
        ]
    ]
]
```

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

### Add URL Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Adds a URL input field for web addresses. Supports label, instructions, required status, wrapper attributes, default value, and placeholder text.

```php
$fields
    ->addUrl('url_field', [
        'label' => 'URL Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'default_value' => '',
        'placeholder' => '',
    ]);
```

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

### ACF Tab Field Array Structure

Source: https://github.com/stoutlogic/acf-builder/wiki/Tabs

Illustrates the array structure generated by ACF Builder for a 'tab' field. This includes the 'key', 'name', 'label', and 'type' properties, with 'name' and 'key' having '_tab' appended.

```php
[
    'key' => 'field_banner_content_tab',
    'name' => 'content_tab',
    'label' => 'Content',
    'type' => 'tab'
]
```

```php
[
    'key' => 'field_banner_background_settings_tab',
    'name' => 'background_settings_tab',
    'label' => 'Background Settings',
    'type' => 'tab'
]
```

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

### Instantiate FieldsBuilder Overwriting Defaults

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Groups

Shows how to override the default 'key' and 'title' values, or add new configuration options like 'style', when initializing a FieldsBuilder by passing an array to the constructor.

```php
$banner = new StoutLogic\AcfBuilder\FieldsBuilder('banner', [
    'key' => 'group_header_banner',
    'style' => 'seamless'
]);
```

```json
[
    'key' => 'group_header_banner',
    'title' => 'Banner',
    'style' => 'seamless',
]
```

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

### Add Field Generic Method

Source: https://github.com/stoutlogic/acf-builder/wiki/Fields

Demonstrates the generic method to add a field to a field group, specifying the field's name, type, and configuration options.

```php
$builder->addField($name, $type, $config = []);
```

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

### ACF Link Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Demonstrates how to add a Link field, allowing users to input a URL with optional text.

```php
$fields 
    ->addLink('link_field', [
        'label' => 'Link Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'return_format' => 'array',
    ]);
```

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

### Generated Field Group Structure

Source: https://github.com/stoutlogic/acf-builder/wiki/Fields

Illustrates the expected PHP array structure generated by ACF Builder for a field group, showing keys, names, labels, types, and configurations for each field.

```php
[
    'key' => 'group_background',
    'title' => 'Background',
    'fields' => [
        [
            'key' => 'field_background_background_image',
            'name' => 'background_image',
            'label' => 'Background Image',
            'type' => 'image',
            'preview_size' => 'medium'
        ],
        [
            'key' => 'field_background_background_fixed',
            'name' => 'background_fixed',
            'label' => 'Fixed',
            'type' => 'true_false',
            'instructions' => "Check to add a parallax effect where the background image doesn't move when scrolling"
        ],
        [
            'key' => 'field_background_background_color',
            'name' => 'background_color',
            'label' => 'Background Color',
            'type' => 'color_picker',
            'default_value' => '#ffffff'
        ],
    ]
]
```

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

### Add Oembed Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Adds an oEmbed field for embedding media from various services (e.g., YouTube, Vimeo). Supports label, instructions, required status, wrapper attributes, and custom width/height.

```php
$fields 
    ->addOembed('oembed_field', [
        'label' => 'Oembed Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'width' => '',
        'height' => '',
    ]);
```

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

### Add Image Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Adds an image upload field. Allows configuration of label, instructions, required status, wrapper attributes, return format (array, URL, or ID), preview size, library settings, and size/mime type constraints.

```php
$fields
    ->addImage('image_field', [
        'label' => 'Image FIeld',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'return_format' => 'array',
        'preview_size' => 'thumbnail',
        'library' => 'all',
        'min_width' => '',
        'min_height' => '',
        'min_size' => '',
        'max_width' => '',
        'max_height' => '',
        'max_size' => '',
        'mime_types' => '',
    ]);
```

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

### Add File Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Adds a file upload field. Supports label, instructions, required status, wrapper attributes, return format (array, URL, or ID), library settings, and size/mime type constraints.

```php
$fields 
    ->addFile('file_Field', [
        'label' => 'File Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'return_format' => 'array',
        'library' => 'all',
        'min_size' => '',
        'max_size' => '',
        'mime_types' => '',
    ]);
```

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

### ACF Select Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Demonstrates adding a Select field with options. This field allows users to choose a single value from a predefined list.

```php
$fields 
    ->addSelect('select_field', [
        'label' => 'Select Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'choices' => [],
        'default_value' => [],
        'allow_null' => 0,
        'multiple' => 0,
        'ui' => 0,
        'ajax' => 0,
        'return_format' => 'value',
        'placeholder' => '',  
    ]);
```

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

### Add Text Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Adds a text input field to the ACF form. Allows configuration of label, instructions, required status, wrapper attributes, default value, placeholder, prepend, and append text.

```php
$fields
    ->addText('text_field', [
        'label' => 'Text Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'default_value' => '',
        'placeholder' => '',
        'prepend' => '',
        'append' => '',
        'maxlength' => '',
  ]);
```

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

### Add Number Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Adds a number input field for numerical values. Includes options for label, instructions, required status, wrapper attributes, default value, placeholder, prepend/append text, min/max values, and step increment.

```php
$fields 
    ->addNumber('number_Field', [
        'label' => 'Number Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'default_value' => '',
        'placeholder' => '',
        'prepend' => '',
        'append' => '',
        'min' => '',
        'max' => '',
        'step' => '',
  ]);
```

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

### ACF Builder: Compose Fields with addFields

Source: https://github.com/stoutlogic/acf-builder/wiki/Composing-Fields

Demonstrates composing field groups using the `addFields` method in ACF Builder. This allows reusing field configurations across different parts of your WordPress admin UI, such as background settings for various page elements.

```php
use StoutLogic\AcfBuilder\FieldsBuilder;

$backgroundSettings = new FieldsBuilder('background_settings');
$backgroundSettings
    ->addImage('background_image')
    ->addTrueFalse('background_image_fixed')
    ->addColorPicker('background_color');

$columns = new FieldsBuilder('columns');
$columns
    ->addTab('Columns')
        ->addRepeater('columns', ['min' => 1, 'max' => 3, 'layout' => 'block'])
            ->addTab('Content')
                ->addWysiwyg('content')
            ->addTab('Background')
                ->addFields($backgroundSettings)
            ->endRepeater()

     ->addTab('Background')
         ->addFields($backgroundSettings);

$banner = new FieldsBuilder('banner');
$banner
    ->addRepeater('slides', ['min' => 1, 'layout' => 'block'])
        ->addFields($columns)
    ->setLocation('post_type', '==', 'page');

$sections = new FieldsBuilder('sections');
$sections
    ->addFlexibleContent('sections')
       ->addLayout($banner)
       ->addLayout($columns)
    ->setLocation('page_template', '==', 'default');

$aboutSections = new FieldsBuilder('about_sections');
$aboutSections
    ->addFlexibleContent('sections')
       ->addLayout($banner)
       ->addLayout($columns)
       ->addLayout('team_members')
           ->addTab('Intro')
               ->addText('title')
               ->addWysiwyg('intro')
           ->addTab('Background')
               ->addFields($background_settings)
    ->setLocation('page_template', '==', 'about');
```

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

### Add Wysiwyg Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Adds a Rich Text Editor (WYSIWYG) field for formatted content. Configurable with label, instructions, required status, wrapper attributes, default value, and editor settings like tabs, toolbar, media upload, and delay.

```php
$fields 
    ->addWysiwyg('wysiwyg_field', [
        'label' => 'WYSIWYG Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'default_value' => '',
        'tabs' => 'all',
        'toolbar' => 'full',
        'media_upload' => 1,
        'delay' => 0,
    ]);
```

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

### Add Password Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Adds a password input field that masks the entered characters. Options include label, instructions, required status, wrapper attributes, placeholder text, and prepend/append text.

```php
$fields 
    ->addPassword('password_field', [
        'label' => 'Password Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'placeholder' => '',
        'prepend' => '',
        'append' => '',
    ]);
```

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

### Nested Repeater Fields

Source: https://github.com/stoutlogic/acf-builder/wiki/Repeater

Illustrates how to embed a repeater field ('columns') within another repeater field ('slides'), allowing for nested data structures. The `endRepeater()` method is used to correctly chain field definitions.

```php
use StoutLogic\AcfBuilder\FieldsBuilder;

$slider = new FieldsBuilder('slider');
$slider
    ->addText('title')
    ->addRepeater('slides', ['min' => 1, 'button_label' => 'Add Slide'])
        ->addText('title')
        ->addRepeater('columns', ['min' => 1, 'max' => 2, 'button_label' => 'Add Column'])
            ->addWysiwyg('content')
            ->endRepeater()
        ->addImage('background_image');
```

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

### Add Email Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Adds an email input field with basic validation for email format. Configurable with label, instructions, required status, wrapper attributes, default value, placeholder, and prepend/append text.

```php
$fields 
    ->addEmail('email_field', [
        'label' => 'Email Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'default_value' => '',
        'placeholder' => '',
        'prepend' => '',
        'append' => '',
    ]);
```

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

### Modify Field Group Configuration

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Groups

Illustrates how to modify or add group configuration settings after a FieldsBuilder object has been instantiated using the `setGroupConfig` method. This method allows for chaining and returns the FieldsBuilder instance.

```php
$banner->setGroupConfig('position', 'acf_after_title');
```

```json
[
    'key' => 'group_header_banner',
    'title' => 'Banner',
    'style' => 'seamless',
    'position' => 'acf_after_title',
]
```

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

### Add Textarea Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Adds a textarea input field for longer text entries. Supports label, instructions, required status, wrapper attributes, default value, placeholder, maxlength, rows, and new_lines settings.

```php
$fields 
  ->addTextarea('textarea_field', [
      'label' => 'Textarea Field',
      'instructions' => '',
      'required' => 0,
      'wrapper' => [
          'width' => '',
          'class' => '',
          'id' => '',
      ],
      'default_value' => '',
      'placeholder' => '',
      'maxlength' => '',
      'rows' => '',
      'new_lines' => '',
  ]);
```

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

### ACF Page Link Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Code snippet for adding a Page Link field, allowing users to link to internal pages on the site.

```php
$fields 
    ->addPageLink('page_link_field', [
        'label' => 'Page Link Field',
        'type' => 'page_link',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'post_type' => [],
        'taxonomy' => [],
        'allow_null' => 0,
        'allow_archives' => 1,
        'multiple' => 0,
    ]);
```

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

### ACF Date Time Picker Field Configuration

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Configures a Date Time Picker field in ACF Builder, allowing users to select both a date and a time. Includes standard field configuration options.

```php
$fields
    ->addDateTimePicker('date_time_picker_field', [
        'label' => 'Date Time Picker Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
    ]);
```

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

### ACF Time Picker Field Configuration

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Configures a Time Picker field in ACF Builder, allowing users to select a time. Supports custom display and return formats.

```php
$fields
    ->addTimePicker('time_picker_field', [
        'label' => 'Time Picker Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'display_format' => 'g:i a',
        'return_format' => 'g:i a',
    ]);
```

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

### ACF Google Map Field Configuration

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Configures a Google Map field in ACF Builder, allowing users to select a location on a map. Supports setting initial map center coordinates, zoom level, and field height.

```php
$fields
    ->addGoogleMap('google_map_field', [
        'label' => 'Google Map Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'center_lat' => '',
        'center_lng' => '',
        'zoom' => '',
        'height' => '',
    ]);
```

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

### ACF Date Picker Field Configuration

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Configures a Date Picker field in ACF Builder, allowing users to select a date. Supports custom display and return formats, and setting the first day of the week.

```php
$fields
    ->addDatePicker('date_picker_field', [
        'label' => 'Date Picker Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'display_format' => 'd/m/Y',
        'return_format' => 'd/m/Y',
        'first_day' => 1,
    ]);
```

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

### ACF Taxonomy Field Configuration

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Configures a taxonomy field in ACF Builder, allowing selection of terms from a specified taxonomy (e.g., 'category'). Supports checkbox field type, term addition, and returns data as an ID.

```php
$fields
    ->addTaxonomy('taxonomy_field', [
        'label' => 'Taxonomy Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'taxonomy' => 'category',
        'field_type' => 'checkbox',
        'allow_null' => 0,
        'add_term' => 1,
        'save_terms' => 0,
        'load_terms' => 0,
        'return_format' => 'id',
        'multiple' => 0,
    ]);
```

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

### Modify Field Configuration

Source: https://github.com/stoutlogic/acf-builder/wiki/Modifying-Fields

Modifies the configuration of an existing field by providing its name and a new configuration array. Throws FieldNotFoundException if the field does not exist.

```php
$fieldsBuilder
    ->modifyField('title', ['label' => 'Headline']);
```

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

### ACF Relationship Field Configuration

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Configures a relationship field in ACF Builder, allowing selection of posts from specific post types and taxonomies. Supports filtering by search, post type, and taxonomy, and returns data as an object.

```php
$fields
    ->addRelationship('relationship_field', [
        'label' => 'Relationship Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'post_type' => [],
        'taxonomy' => [],
        'filters' => [
            0 => 'search',
            1 => 'post_type',
            2 => 'taxonomy',
        ],
        'elements' => '',
        'min' => '',
        'max' => '',
        'return_format' => 'object',
    ]);
```

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

### ACF User Field Configuration

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Configures a user field in ACF Builder, allowing selection of users. Supports filtering by role and allows for multiple selections or null values.

```php
$fields
    ->addUser('user_field', [
        'label' => 'User Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'role' => '',
        'allow_null' => 0,
        'multiple' => 0,
    ]);
```

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

### ACF Message Field Configuration

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Configures a Message field in ACF Builder, used to display custom messages or instructions within the ACF form. Supports basic text content and new line formatting.

```php
$fields 
    ->addMessage('message_field', 'Message', [
        'label' => 'Message Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'message' => '',
        'new_lines' => 'wpautop',
        'esc_html' => 0,
    ]);
```

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

### ACF Color Picker Field Configuration

Source: https://github.com/stoutlogic/acf-builder/wiki/Field-Types

Configures a Color Picker field in ACF Builder, allowing users to select a color. Supports setting a default color value.

```php
$fields 
    ->addColorPicker('color_picker_field', [
        'label' => 'Color Picker Field',
        'instructions' => '',
        'required' => 0,
        'wrapper' => [
            'width' => '',
            'class' => '',
            'id' => '',
        ],
        'default_value' => '',
    ]);
```

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

### Remove Field

Source: https://github.com/stoutlogic/acf-builder/wiki/Modifying-Fields

Removes a field from the builder by its name and optionally adds a new field in its place.

```php
$builder
    ->removeField('title')
    ->addText('headline');
```
Tokens:
Raw