anthonypauwels / wp-acf-builder
An Advanced Custom Field configuration builder using Closure and helpers methods
Requires
- php: ^8.0
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