anthonypauwels/wp-acf-builder

An Advanced Custom Field configuration builder using Closure and helpers methods

0.2.0 2023-06-22 10:59 UTC

Requires

• php: ^8.0

MIT

• Anthony Pauwels

• wordpress
• helper
• acf

README

Create ACF fields with ease using a fluent API.

Requiring WordPress with Advanced Custom Fields Pro.

Installation

Require this package with composer.

composer require anthonypauwels/wp-acf-builder

Usage

Basic

The main Builder class provides shortcut methods to help you create your fields. Here is an example of creating fields for your home page template :

$home_group = Builder::pageTemplate('templates/home.php', 'Home Page', function ( Location $group ) {
    $group->group('Header', function ( Group $group ) {
        $group->text('Title');
        $group->text('Tagline');
        $group->text('Button');

        $group->group('Background', function ( Group $group ) {
            $group->text('Video');
            $group->image('Image')->returnUrl();
        } );
    } );

    $group->group('Discover', function ( Group $group ) {
        $group->repeater('Subsection', function ( Repeater $group ) {
            $group->text('Title');
            $group->text('Subtitle');
            $group->wysiwyg('Content');
            $group->image('Image')->returnUrl();

            $group->group('Button', function ( Group $group ) {
                $group->text('Title');
                $group->pageLink('Page')->postType('page');
            } );
        } );
    } );

    $group->group('Blog', function ( Group $group ) {
        $group->text('Title');
        $group->text('Subtitle');

        $group->group('Button', function ( Group $group ) {
            $group->text('Title');
            $group->pageLink('Page')->postType('page');
        } );
    } );
} )->hideAll();

// group is stored into `$home_group` but not already build. You can call the method $home_group->build() to build the group into ACF. 

Builder class provides methods to build fields group for Posts Types, Options Pages and Page Template. Location group also provides helpers methods to show them using conditional parameters :

// Create fields for a post type
Builder::postType('post', 'Post Field', function ( Location $group ) {
    // ...
    
    $group->postType('another_post_type', 'or'); // second parameter is optional and can be `or` or `and`
} );

// Create fields for an options page
Builder::optionsPage('Options', function ( Location $group ) {
    $group->image('Logo')->returnUrl();
    $group->text('Copyright');
} );

Group instances that can exports sub_fields provides helpers methods to create them. It concerns Group, Layout, Location and Repeater. These methods help you to create subfields like TextField, TextareaField, ImageField, etc. Each class has its own helpers to configure themselves.

For example, you can define how the value of an image field must be returned using helpers methods like returnUrl(), returnArray() or returnId()

Groups with subfields helpers can also create subgroups using the same way. A Location can use repeater($name, $closure) to create a repeater field on its own.

The helpers to create group (Repeater, Group, Layout) accept a closure with instance on parameter that provides the same API to configure fields.

Build

You can build your group separately using their method build.

$home_group->build(); // see example above
$about_group->build();
$contact_group->build();

Builder class provides a static method build() that accepts a closure as parameter. This method calls the closure first then create the acf/init action. Every group created inside the closure will be internally marked for build and built inside the WordPress action. Using that way, you do not need to call the build() method of each group, Builder will make it for you.

Builder::build( function () {
    Builder::pageTemplate('templates/home.php', 'Home Page', function ( Location $group ) {
        // ...
    } );
    
    // work also with optionsPage and postType methods
} );

If you want to export your fields into a separate file, you can also require it into the closure :

## AcfServiceProvider.php, by example
Builder::build( function () {
    require 'acf.php';
} );

## acf.php
Builder::pageTemplate('templates/home.php', 'Home Page', function ( Location $group ) {
// ...
} );

Builder::pageTemplate('templates/about.php', 'About Page', function ( Location $group ) {
// ...
} );

Builder::pageTemplate('templates/contact.php', 'Contact Page', function ( Location $group ) {
// ...
} );

Namespace

The static method Builder::namespace can be used to wrap many Builder::pageTemplate calls. A namespace is simply a directory where your templates is stored.

Builder::namespace( 'templates', function () {
    Builder::pageTemplate('home.php', 'Home Page', function ( Location $group ) {
        // ...
    } );
    
    Builder::pageTemplate('about.php', 'About Page', function ( Location $group ) {
        // ...
    } );
} );

Reuse

Here is an example of creating a banner group with predefined fields. When your group is created, you can push them into the fields list of another groups like Location, Repeater and Layout.

$banner_group = Builder::group('Banner', function (Group $group) {
    $group->text('Title');
    
    $group->text('Subtitle');
    
    $group->group('Button', function ( Group $group ) {
        $group->text('Title');
        $group->pageLink('Page')->postType('page');
    } );

    $group->group('Background', function ( Group $group ) {
        $group->text('Video');
        $group->image('Image')->returnUrl();
    } );
} );

Builder::pageTemplate('templates/home.php', 'Home Page', function ( Location $group ) use ( $banner_group ) {
    // ...
    $group->addField( $banner_group );
    // ...
} );

Builder::pageTemplate('templates/contact.php', 'Contact Page', function ( Location $group ) use ( $banner_group ) {
    // ...
    $group->addField( $banner_group );
    // ...
} );

Filters

Fields and groups provides helpers methods for ACF filters. For example, you can create a filter where the returned value is transformed into capital case.

Builder::pageTemplate('home.php', 'Home Page', function ( Location $group ) {
        $group->text('Title')->onValue( function ( $field ) {
            $field['value'] = strtoupper( $field['value'] );
        
            return $field;
        } ); // end of text field Title
    } );

Or pre-populated a repeater fields :

Builder::pageTemplate('home.php', 'Home Page', function ( Location $group ) {
    $group->repeater( 'List', function ( Repeater $repeater ) {
        $repeater->text('Label' );
        $repeater->text('Value' );
    } )->onValue( function ( $value ) {
        // if the value is FALSE or NULL it means the field has never been updated
        // we don't want to change fields that have already been edited
        if ( !$value ) {
            // create a bi dimensional array
            return array_map( function ( $label ) {
                return [
                    '_acf_field_group_home_page_fields_list_label' => $label,
                    '_acf_field_group_home_page_fields_list_value' => '',
                ];
            }, ['First Label', 'Second Label', 'Third Label'] );
        }
        
        return $value;
    } ); // end of repeater List
} );

For more information about ACF filters, check the Advanced Custom Fields documentation about Filters.

Raw parameters

If you want to set an ACF parameters not available on the package, you can use the param method on fields. Imagine that you want to use WPML with your ACF fields, you can set a value to wpml_cf_preferences like this way :

// ...
function ( Group $group ) {
    $group->text('Sub Title')->param('wpml_cf_preferences', 2 ); // This field will be translated
    $group->text('Sub Title')->params( ['wpml_cf_preferences' => 2 ] ); // you can pass array of parameters with `params` method
} )
// ...

Default configuration

Configure a default configuration to all fields can be long and daunting, so you can also use a config method on the Builder that accept an array as parameter.

The Builder has a bunch of new methods and constants to help to you to configure every field :

Builder::config( [
    // define a config value for all fields, like using `param` method
    Builder::all => [
        'wpml_cf_preferences' => 2,
    ],

    // define config for a field using the building methods
    Builder::text => Builder::text()->placeholder('Put some content here'),
    
    // methods can be chained
    Builder::wysiwyg => Builder::wysiwyg()->visualOnly()->basicToolbar()->required(),

    // raw parameters works too
    Builder::email => Builder::email()->param('wpml_cf_preferences', 0),

    // you can also pass the field type string as key
    'url' => Builder::url()->placeholder('https://...'),

    // or a configuration array as value
    Builder::file => [
        'return_format' => 'id'
    ],

    // you can set your Google Map api key here
    Builder::googleMap => Builder::googleMap()->api('your_api_key_here', 'your_client_ID_here'),

    // works with repeater, group, location, flexible and layout too
    Builder::repeater => Builder::repeater()->max( 10 )->param( 'wpml_cf_preferences', 0 ),
] );

You must set default configuration before building fields because the configuration array are merged when build method is called.

API documentation

WP ACF Builder provides a fluent API for each instances available.

• Builder
• Subfields
• Flexible Content
• Group
• Layout Group
• Location Group
• Repeater Group
• AbstractField
• AccordionField
• BooleanField
• ButtonGroupField
• CheckboxField
• ColorField
• DateField
• DateTimeField
• EmailField
• FileField
• GalleryField
• GoogleMapField
• ImageField
• LinkField
• MessageField
• NumberField
• OEmbedField
• PageLinkField
• PasswordField
• PostObjectField
• RadioField
• RangeField
• RelationshipField
• SelectField
• TabField
• TaxonomyField
• TextareaField
• TextField
• TimeField
• UserField
• WysiwygField
• Generic methods

Builder

Builder::build( function () { } );
Builder::namespace( 'templates', function () { } );
Builder::fieldsGroup( 'Group label', function ( Group $group ) { } );
Builder::repeaterGroup( 'Repeater label', function ( Repeater $repeater ) { } );
Builder::flexibleContent( 'Flexible Content label', function ( Flexible $flexible ) { } );
Builder::locationGroup( 'Group Location label', function ( Location $location ) { } );
Builder::postType( 'Location Post Type', function ( Location $location ) { } );
Builder::pageTemplate( 'Location Page Template', function ( Location $location ) { } );
Builder::optionsPage( 'Location Options Page', function ( Location $location ) { } );

Subfields

Class Group, Location, Layout and Repeater use Subfields trait that provides the methods to create fields:

$group->addField( $field ); // instance of Field
$group->prependFields( $fields ); // array of Field instances
$group->appendFields( $fields ); // array of Field instances
$group->text( 'Label', 'name', 'key' );
$group->textarea( 'Label', 'name', 'key' );
$group->wysiwyg( 'Label', 'name', 'key' );
$group->number( 'Label', 'name', 'key' );
$group->email( 'Label', 'name', 'key' );
$group->url( 'Label', 'name', 'key' );
$group->boolean( 'Label', 'name', 'key' );
$group->pageLink( 'Label', 'name', 'key' );
$group->postObject( 'Label', 'name', 'key' );
$group->file( 'Label', 'name', 'key' );
$group->image( 'Label', 'name', 'key' );
$group->gallery( 'Label', 'name', 'key' );
$group->select( 'Label', 'name', 'key' );
$group->checkbox( 'Label', 'name', 'key' );
$group->user( 'Label', 'name', 'key' );
$group->password( 'Label', 'name', 'key' );
$group->taxonomy( 'Label', 'name', 'key' );
$group->relationship( 'Label', 'name', 'key' );
$group->oEmbed( 'Label', 'name', 'key' );
$group->googleMap( 'Label', 'name', 'key' );
$group->link( 'Label', 'name', 'key' );
$group->date( 'Label', 'name', 'key' );
$group->time( 'Label', 'name', 'key' );
$group->dateTime( 'Label', 'name', 'key' );
$group->buttonGroup( 'Label', 'name', 'key' );
$group->color( 'Label', 'name', 'key' );
$group->range( 'Label', 'name', 'key' );
$group->message( 'Label', 'name', 'key' );
$group->tab( 'Label', 'key' );
$group->accordion( 'Label', 'key' );
$group->group( 'Label', function ( Group $group ) { }, 'name', 'key' );
$group->repeater( 'Label', function ( Repeater $repeater ) { }, 'name', 'key' );
$group->flexible( 'Label', function ( Flexible $flexible ) { }, 'name', 'key' );

Flexible Content

$flexible->onLayoutTitle( function () { ... } ); // check ACF documentation about Flexible Content title filter
$flexible->layout('Layout Label', function ( Layout $layout ) { ... } );
$flexible->addLayout( $layout ); // instance of class Layout
$flexible->button('Add a layout');
$flexible->min(3); // default to 0
$flexible->max(9); // default to 0 (infinity)

Group

$group->layout('block'); // block | table | row
$group->blockLayout();
$group->tableLayout();
$group->rowLayout();

Layout Group

$layout->layout('block'); // block | table | row
$layout->blockLayout();
$layout->tableLayout();
$layout->rowLayout();

Location Group

$location->showIf('page_template', '=', 'home.php', 'and');
$location->andShowIf('page_template', '=', 'home.php');
$location->orShowIf('page_template', '=', 'home.php');
$location->priorityOrder();
$location->position('normal'); // side | acf_after_title | normal
$location->positionOnSide();
$location->positionAfterTitle();
$location->positionBelow();
$location->style(); // default | seamless
$location->styleWithBox();
$location->styleWithoutBox();
$location->labelsOn('top'); // top | left
$location->labelsAboveFields();
$location->labelsBesideFields();
$location->instructionsBelow('label'); // label | field
$location->instructionsBelowLabels();
$location->instructionsBelowFields();
$location->hideOnScreen('revisions'); // hide listed elements
$location->hideAll('the_content', 'featured_image'); // list exceptions on parameters 
$location->enable(); // pass `false` to disable
$location->disable();
$location->showInApi(); // pass `false` to hide in API
$location->hideInApi();
$location->description('Group description');
$location->page(2434, 'and');
$location->pageParent(4244, 'and');
$location->pageTemplate('home.php', 'and');
$location->post(2424, 'and');
$location->postType('post', 'and');
$location->postCategory('foobar', 'and');
$location->postTaxonomy('categories', 'and');
$location->postFormat('standard', 'and');
$location->postStatus('publish', 'and');
$location->menu('all', 'and');
$location->menuItem('all', 'and');
$location->widget('all', 'and');
$location->userRole('administrator', 'and');
$location->optionsPage('acf-options-common', 'and');
$location->build();

Repeater Group

$repeater->layout('block'); // block | table | row
$repeater->blockLayout();
$repeater->tableLayout();
$repeater->rowLayout();
$repeater->button('Add a row');
$repeater->min(3); // default to 0
$repeater->max(9); // default to 0 (infinity)

AbstractField

Every field inherit from AbstractField class that provide generic API. Example below works with all fields :

$group->text(/* ... */)->param('key', 'value');
$group->text(/* ... */)->params( [ 'key' => 'value', 'foo' => 'bar' ] );
$group->text(/* ... */)->default('Here is a default value');
$group->text(/* ... */)->instructions('Here is an instruction message');
$group->text(/* ... */)->required(); // pass `false` to not required
$group->text(/* ... */)->notRequired();
$group->text(/* ... */)->wrapper(460, '.foo .bar', 'random-id');
$group->text(/* ... */)->wrapperWidth(460);
$group->text(/* ... */)->wrapperClass('.foo .bar');
$group->text(/* ... */)->wrapperId('random-id');
$group->text(/* ... */)->showIf('key', '=', 'value', 'and');
$group->text(/* ... */)->andShowIf('key', '=', 'value');
$group->text(/* ... */)->orShowIf('key', '=', 'value');
$group->text(/* ... */)->onLoad( function ( $field ) { ... } );
$group->text(/* ... */)->onValue( function ( $field ) { ... } );
$group->text(/* ... */)->onUpdate( function ( $field ) { ... } );
$group->text(/* ... */)->onFormat( function ( $field ) { ... } );
$group->text(/* ... */)->toArray();

AccordionField

$group->accordion(/* ... */)->open(); // pass `false` to close
$group->accordion(/* ... */)->close();
$group->accordion(/* ... */)->multiExpand(); // pass `false` to do not multi expand
$group->accordion(/* ... */)->dontMultiExpand();

BooleanField

$group->boolean(/* ... */)->message('Here is an informative message');

ButtonGroupField

$group->buttonGroup(/* ... */)->choices( ['red' => 'Rouge', 'green' => 'Vert', 'blue' => 'Bleu'] );
$group->buttonGroup(/* ... */)->nullable(); // pass `false` to set not nullable
$group->buttonGroup(/* ... */)->notNullable();
$group->buttonGroup(/* ... */)->layout('vertical'); // vertical | horizontal
$group->buttonGroup(/* ... */)->vertical();
$group->buttonGroup(/* ... */)->horizontal();

CheckboxField

$group->checkbox(/* ... */)->choices( ['red' => 'Rouge', 'green' => 'Vert', 'blue' => 'Bleu'] );
$group->checkbox(/* ... */)->allowCustom(); // pass `false` to disallow custom
$group->checkbox(/* ... */)->disallowCustom();
$group->checkbox(/* ... */)->saveCustom(); // pass `false` to not save custom
$group->checkbox(/* ... */)->dontSaveCustom();
$group->checkbox(/* ... */)->layout('vertical'); // vertical | horizontal
$group->checkbox(/* ... */)->vertical();
$group->checkbox(/* ... */)->horizontal();

ColorField

$group->color(/* ... */)->enableOpacity(); // pass `false` to disable opacity
$group->color(/* ... */)->disableOpacity();
$group->color(/* ... */)->return('string'); // array | string
$group->color(/* ... */)->returnArray();
$group->color(/* ... */)->returnString();

DateField

$group->date(/* ... */)->display('g:i a');
$group->date(/* ... */)->return('Y-m-d');
$group->date(/* ... */)->weekStartsOn(0); // value must be between 0 (sunday) and 6 (saturday)
$group->date(/* ... */)->weekStartsOnMonday();
$group->date(/* ... */)->weekStartsOnTuesday();
$group->date(/* ... */)->weekStartsOnWednesday();
$group->date(/* ... */)->weekStartsOnThursday();
$group->date(/* ... */)->weekStartsOnFriday();
$group->date(/* ... */)->weekStartsOnSaturday();
$group->date(/* ... */)->weekStartsOnSunday();

DateTimeField

$group->datetime(/* ... */)->display('g:i a');
$group->datetime(/* ... */)->return('Y-m-d H:i:s');
$group->datetime(/* ... */)->weekStartsOn(0); // value must be between 0 (sunday) and 6 (saturday)
$group->datetime(/* ... */)->weekStartsOnMonday();
$group->datetime(/* ... */)->weekStartsOnTuesday();
$group->datetime(/* ... */)->weekStartsOnWednesday();
$group->datetime(/* ... */)->weekStartsOnThursday();
$group->datetime(/* ... */)->weekStartsOnFriday();
$group->datetime(/* ... */)->weekStartsOnSaturday();
$group->datetime(/* ... */)->weekStartsOnSunday();

EmailField

$group->email(/* ... */)->placeholder('This is placeholder');
$group->email(/* ... */)->append('Append text');
$group->email(/* ... */)->prepend('Prepend text');

FileField

$group->file(/* ... */)->previewSize('thumbnail');
$group->file(/* ... */)->previewThumbnail();
$group->file(/* ... */)->previewMedium();
$group->file(/* ... */)->previewMediumLarge();
$group->file(/* ... */)->previewLarge();
$group->file(/* ... */)->previewFullSize();
$group->file(/* ... */)->restrictLibrary('all'); // all | uploadedTo
$group->file(/* ... */)->showAll();
$group->file(/* ... */)->onlyUploaded();
$group->file(/* ... */)->mimeTypes('pdf');
$group->file(/* ... */)->minSize(0);
$group->file(/* ... */)->maxSize(1000);
$group->file(/* ... */)->size(0, 1000);
$group->file(/* ... */)->return('array'); // array | url
$group->file(/* ... */)->returnObject();
$group->file(/* ... */)->returnArray();
$group->file(/* ... */)->returnUrl();

GalleryField

$group->gallery(/* ... */)->minWidth(25);
$group->gallery(/* ... */)->maxWidth(1920);
$group->gallery(/* ... */)->width(25, 1920);
$group->gallery(/* ... */)->minHeight(25);
$group->gallery(/* ... */)->maxHeight(960);
$group->gallery(/* ... */)->height(25, 960);
$group->gallery(/* ... */)->previewSize('thumbnail');
$group->gallery(/* ... */)->previewThumbnail();
$group->gallery(/* ... */)->previewMedium();
$group->gallery(/* ... */)->previewMediumLarge();
$group->gallery(/* ... */)->previewLarge();
$group->gallery(/* ... */)->previewFullSize();
$group->gallery(/* ... */)->restrictLibrary('all'); // all | uploadedTo
$group->gallery(/* ... */)->showAll();
$group->gallery(/* ... */)->onlyUploaded();
$group->gallery(/* ... */)->mimeTypes('jpeg', 'png');
$group->gallery(/* ... */)->minSize(0);
$group->gallery(/* ... */)->maxSize(1000);
$group->gallery(/* ... */)->size(0, 1000);
$group->gallery(/* ... */)->return('array'); // array | url
$group->gallery(/* ... */)->returnObject();
$group->gallery(/* ... */)->returnArray();
$group->gallery(/* ... */)->returnUrl();
$group->gallery(/* ... */)->min(3); // default to 0
$group->gallery(/* ... */)->max(9); // default to 0 (infinity)
$group->gallery(/* ... */)->insertNew('append'); // append | prepend
$group->gallery(/* ... */)->insertAppend();
$group->gallery(/* ... */)->insertPrepend();

GoogleMapField

$group->googleMap(/* ... */)->latitude(-37.81411);
$group->googleMap(/* ... */)->longitude(144.96328);
$group->googleMap(/* ... */)->coordinates(-37.81411, 144.96328);
$group->googleMap(/* ... */)->zoom(14);
$group->googleMap(/* ... */)->height(400);

// set your Google Map api key and client ID here. Works for all GoogleMapField, you can set it globally via the config
$group->googleMap(/* ... */)->api("your_api_key", "your_client_id");

ImageField

$group->image(/* ... */)->minWidth(25);
$group->image(/* ... */)->maxWidth(1920);
$group->image(/* ... */)->width(25, 1920);
$group->image(/* ... */)->minHeight(25);
$group->image(/* ... */)->maxHeight(960);
$group->image(/* ... */)->height(25, 960);
$group->image(/* ... */)->previewSize('thumbnail');
$group->image(/* ... */)->previewThumbnail();
$group->image(/* ... */)->previewMedium();
$group->image(/* ... */)->previewMediumLarge();
$group->image(/* ... */)->previewLarge();
$group->image(/* ... */)->previewFullSize();
$group->image(/* ... */)->restrictLibrary('all'); // all | uploadedTo
$group->image(/* ... */)->showAll();
$group->image(/* ... */)->onlyUploaded();
$group->image(/* ... */)->mimeTypes('jpeg', 'png');
$group->image(/* ... */)->minSize(0);
$group->image(/* ... */)->maxSize(1000);
$group->image(/* ... */)->size(0, 1000);
$group->image(/* ... */)->return('array'); // array | url
$group->image(/* ... */)->returnObject();
$group->image(/* ... */)->returnArray();
$group->image(/* ... */)->returnUrl();

LinkField

$group->postObject(/* ... */)->return('array'); // array | url
$group->postObject(/* ... */)->returnArray();
$group->postObject(/* ... */)->returnUrl();

MessageField

$group->message(/* ... */)->message('Here is an informative message');
$group->message(/* ... */)->append('Append text');
$group->message(/* ... */)->prepend('Prepend text');
$group->message(/* ... */)->escapeHtml(); // pass `false` to not escape HTML
$group->message(/* ... */)->dontEscapeHtml();
$group->message(/* ... */)->newLines('wpautop'); // wpautop | br | '' (empty string)
$group->message(/* ... */)->paragraphs();
$group->message(/* ... */)->breakLines();
$group->message(/* ... */)->noFormatting();

NumberField

$group->number(/* ... */)->placeholder('This is placeholder');
$group->number(/* ... */)->append('Append text');
$group->number(/* ... */)->prepend('Prepend text');
$group->number(/* ... */)->min(3); // default to 0
$group->number(/* ... */)->max(9); // default to 0 (infinity)
$group->number(/* ... */)->step(3); // default to 0

OEmbedField

$group->oEmbed(/* ... */)->width(400);
$group->oEmbed(/* ... */)->height(800);
$group->oEmbed(/* ... */)->dimension(400, 800);

PageLinkField

$group->pageLink(/* ... */)->taxonomy( 'categories' );
$group->pageLink(/* ... */)->postType( 'posts' );
$group->pageLink(/* ... */)->nullable(); // pass `false` to set not nullable
$group->pageLink(/* ... */)->notNullable();
$group->pageLink(/* ... */)->multiple(); // pass `false` to set not multiple
$group->pageLink(/* ... */)->notMultiple();

PasswordField

$group->password(/* ... */)->placeholder('This is placeholder');
$group->password(/* ... */)->append('Append text');
$group->password(/* ... */)->prepend('Prepend text');

PostObjectField

$group->postObject(/* ... */)->taxonomies( ['categories'] );
$group->postObject(/* ... */)->postsType( ['posts'] );
$group->postObject(/* ... */)->return('object'); // object | id
$group->postObject(/* ... */)->returnObject();
$group->postObject(/* ... */)->returnId();
$group->postObject(/* ... */)->onQuery( function () { ... } ); // check ACF documentation about Post Object field filters 
$group->postObject(/* ... */)->onResult( function () { ... } );

RadioField

$group->radio(/* ... */)->choices( ['red' => 'Rouge', 'green' => 'Vert', 'blue' => 'Bleu'] );
$group->radio(/* ... */)->allowOtherChoice(); // pass `false` to set disallow other choice
$group->radio(/* ... */)->disallowOtherChoice();
$group->radio(/* ... */)->saveOtherChoice(); // pass `false` to set do not save other choice
$group->radio(/* ... */)->dontSaveOtherChoice();
$group->radio(/* ... */)->layout('vertical'); // vertical | horizontal
$group->radio(/* ... */)->vertical();
$group->radio(/* ... */)->horizontal();

RangeField

$group->range(/* ... */)->append('Append text');
$group->range(/* ... */)->prepend('Prepend text');
$group->range(/* ... */)->min(3); // default to 0
$group->range(/* ... */)->max(9); // default to 0 (infinity)
$group->range(/* ... */)->step(3); // default to 0

RelationshipField

$group->relationship(/* ... */)->taxonomies( ['categories'] );
$group->relationship(/* ... */)->postsType( ['posts'] );
$group->relationship(/* ... */)->filters( ['search' => true, 'post_type' => false, 'taxonomy' => false] );
$group->relationship(/* ... */)->filterOnSearch(); // pass `false` to set not filter on search
$group->relationship(/* ... */)->dontFilterOnSearch();
$group->relationship(/* ... */)->filterByPostType(); // pass `false` to set not filter by post type
$group->relationship(/* ... */)->dontFilterByPostType();
$group->relationship(/* ... */)->filterByTaxonomy(); // pass `false` to set not filter by taxonomy
$group->relationship(/* ... */)->dontFilterByTaxonomy();
$group->relationship(/* ... */)->return('object'); // object | id
$group->relationship(/* ... */)->returnObject();
$group->relationship(/* ... */)->returnId();
$group->relationship(/* ... */)->onQuery( function () { ... } ); // check ACF documentation about relationship field filters 
$group->relationship(/* ... */)->onResult( function () { ... } );
$group->relationship(/* ... */)->min(3); // default to 0
$group->relationship(/* ... */)->max(9); // default to 0 (infinity)

SelectField

$group->select(/* ... */)->choices( ['red' => 'Rouge', 'green' => 'Vert', 'blue' => 'Bleu'] );
$group->select(/* ... */)->placeholder('This is placeholder');
$group->select(/* ... */)->nullable(); // pass `false` to set not nullable
$group->select(/* ... */)->notNullable();
$group->select(/* ... */)->multiple(); // pass `false` to set not multiple
$group->select(/* ... */)->notMultiple();
$group->select(/* ... */)->ui('default'); // default | select2
$group->select(/* ... */)->defaultUi();
$group->select(/* ... */)->select2Ui();
$group->select(/* ... */)->useAjax(); // pass `false` to not use ajax
$group->select(/* ... */)->dontUseAjax();

TabField

$group->tab(/* ... */)->placeholder('top'); // top | left
$group->tab(/* ... */)->topAligned();
$group->tab(/* ... */)->leftAligned();

TaxonomyField

$group->taxonomy(/* ... */)->which('category');
$group->taxonomy(/* ... */)->appearance('checkbox'); // checkbox || multi_select || radio || select
$group->taxonomy(/* ... */)->asCheckbox();
$group->taxonomy(/* ... */)->asMultiSelect();
$group->taxonomy(/* ... */)->asRadio();
$group->taxonomy(/* ... */)->asSelect();
$group->taxonomy(/* ... */)->saveTerms(); // pass `false` to not save terms
$group->taxonomy(/* ... */)->dontSaveTerms();
$group->taxonomy(/* ... */)->return();
$group->taxonomy(/* ... */)->returnObject();
$group->taxonomy(/* ... */)->returnId();
$group->taxonomy(/* ... */)->allowAddTerm(); // pass `false` to disallow add term
$group->taxonomy(/* ... */)->disallowAddTerm();
$group->taxonomy(/* ... */)->onQuery( function () { ... } ); // check ACF documentation about taxonomy field filters 
$group->taxonomy(/* ... */)->onResult( function () { ... } );

TextareaField

$group->textarea(/* ... */)->placeholder('This is placeholder');
$group->textarea(/* ... */)->append('Append text');
$group->textarea(/* ... */)->prepend('Prepend text');
$group->textarea(/* ... */)->readOnly(); // pass `false` to set not read only
$group->textarea(/* ... */)->notReadOnly();
$group->textarea(/* ... */)->disable(); // pass `false` to enable
$group->textarea(/* ... */)->enable();
$group->textarea(/* ... */)->maxLength(50);
$group->textarea(/* ... */)->rows(10);
$group->textarea(/* ... */)->rows(10);
$group->textarea(/* ... */)->newLines('wpautop'); // wpautop | br | '' (empty string)
$group->textarea(/* ... */)->paragraphs();
$group->textarea(/* ... */)->breakLines();
$group->textarea(/* ... */)->noFormatting();

TextField

$group->text(/* ... */)->placeholder('This is placeholder');
$group->text(/* ... */)->append('Append text');
$group->text(/* ... */)->prepend('Prepend text');
$group->text(/* ... */)->readOnly(); // pass `false` to set not read only
$group->text(/* ... */)->notReadOnly();
$group->text(/* ... */)->disable(); // pass `false` to enable
$group->text(/* ... */)->enable();
$group->text(/* ... */)->maxLength(50);

TimeField

$group->time(/* ... */)->display('g:i a');
$group->time(/* ... */)->return('Y-m-d H:i:s');

UrlField

$group->url(/* ... */)->placeholder('This is placeholder');

UserField

$group->user(/* ... */)->nullable(); // pass `false` to set not nullable
$group->user(/* ... */)->notNullable();
$group->user(/* ... */)->multiple(); // pass `false` to set not multiple
$group->user(/* ... */)->notMultiple();
$group->user(/* ... */)->roles(['administrator', 'editor']); // array of roles

WysiwygField

$group->wysiwyg(/* ... */)->tabs('all'); // all | visual | text
$group->wysiwyg(/* ... */)->allTabs();
$group->wysiwyg(/* ... */)->visualOnly();
$group->wysiwyg(/* ... */)->textOnly();
$group->wysiwyg(/* ... */)->toolbar('full'); // full | basic
$group->wysiwyg(/* ... */)->fullToolbar();
$group->wysiwyg(/* ... */)->basicToolbar();
$group->wysiwyg(/* ... */)->showMediaButton(); // pass `false` to hide media button
$group->wysiwyg(/* ... */)->hideMediaButton();

Generic methods

Both fields and groups can use these methods:

$field->toArray();
$field->toJson();
$field->dd();

Requirement

PHP 8.0 or above