Note The package has been renamed in version 13, see the upgrade guide.

Extended ACF

Register advanced custom fields with object oriented PHP.

Extended ACF provides an object oriented API to register groups and fields with ACF. If you register fields in your theme, you can safely rely on version control when working with other developers. Oh, and you don't have to worry about unique field keys.

Installation
Usage
Fields
Location
Conditional Logic
Custom Settings
Custom Fields
Upgrade Guide

Installation

Require this package, with Composer, in the root directory of your project.

composer require vinkla/extended-acf

Download the Advanced Custom Fields Pro plugin and put it in either the plugins or mu-plugins directory. Visit the WordPress dashboard and activate the plugin.

Learn more about installing ACF PRO with Composer.

Usage

Use the register_extended_field_group() function to register a new field group. It extends the default register_field_group() function provided in the ACF plugin. The difference is that it appends the key value to field groups and fields. Below you'll find an example of a field group.

use Extended\ACF\Fields\Image;
use Extended\ACF\Fields\Text;
use Extended\ACF\Location;

add_action('acf/init', function() {
    register_extended_field_group([
        'title' => 'About',
        'fields' => [
            Image::make('Image'),
            Text::make('Title'),
        ],
        'location' => [
            Location::where('post_type', 'page')
        ],
    ]);
});

Settings

Visit the official ACF documentation to read more about the field group settings. Find more examples in the examples directory:

Fields

All fields have their responding class (except the clone field). All fields must have a label. If no name is given, it will use the label as name in lowercase letters. The name can only contain alphanumeric characters, underscores and dashes.

use Extended\ACF\Fields\Text;

Text::make('Title', 'heading')
    ->instructions('Add the text value')
    ->required();

Basic Fields

Email - The email field creates a simple email input.

use Extended\ACF\Fields\Email;

Email::make('Email')
    ->instructions('Add the employees email address.')
    ->required();

Number - The number field creates a simple number input.

use Extended\ACF\Fields\Number;

Number::make('Age')
    ->instructions('Add the employees age.')
    ->min(18)
    ->max(65)
    ->required();

Password - The password field creates a simple password input.

use Extended\ACF\Fields\Password;

Password::make('Password')
    ->instructions('Add the employees secret pwned password.')
    ->required();

Range - The range field provides an interactive experience for selecting a numerical value.

use Extended\ACF\Fields\Range;

Range::make('Rate')
    ->instructions('Add the employees completion rate.')
    ->min(0)
    ->max(100)
    ->step(10)
    ->required();

Text - The text field creates a simple text input.

use Extended\ACF\Fields\Text;

Text::make('Name')
    ->instructions('Add the employees name.')
    ->characterLimit(100)
    ->required();

Textarea - The textarea field creates a simple textarea.

use Extended\ACF\Fields\Textarea;

Textarea::make('Biography')
    ->instructions('Add the employees biography.')
    ->newLines('br') // br or wpautop
    ->characterLimit(2000)
    ->rows(10)
    ->required();

URL - The url field creates a simple url input.

use Extended\ACF\Fields\Url;

Url::make('Website')
    ->instructions('Add the employees website link.')
    ->required();

Choice Fields

Button Group - The button group field creates a list of radio buttons.

use Extended\ACF\Fields\ButtonGroup;

ButtonGroup::make('Color')
    ->instructions('Select the box shadow color.')
    ->choices([
        'cyan' => 'Cyan',
        'hotpink' => 'Hotpink',
    ])
    ->defaultValue('hotpink')
    ->returnFormat('value') // array, label or value (default)
    ->required();

Checkbox - The checkbox field creates a list of tick-able inputs.

use Extended\ACF\Fields\Checkbox;

Checkbox::make('Color')
    ->instructions('Select the border color.')
    ->choices([
        'cyan' => 'Cyan',
        'hotpink' => 'Hotpink',
    ])
    ->defaultValue('cyan')
    ->returnFormat('value') // array, label or value (default)
    ->layout('horizontal') // vertical or horizontal
    ->required();

Radio - The radio button field creates a list of select-able inputs.

use Extended\ACF\Fields\RadioButton;

RadioButton::make('Color')
    ->instructions('Select the text color.')
    ->choices([
        'cyan' => 'Cyan',
        'hotpink' => 'Hotpink',
    ])
    ->defaultValue('hotpink')
    ->returnFormat('value') // array, label or value (default)
    ->required();

Select - The select field creates a drop down select or multiple select input.

use Extended\ACF\Fields\Select;

Select::make('Color')
    ->instructions('Select the background color.')
    ->choices([
        'cyan' => 'Cyan',
        'hotpink' => 'Hotpink',
    ])
    ->defaultValue('cyan')
    ->returnFormat('value') // array, label or value (default)
    ->allowMultiple()
    ->allowNull()
    ->required();

True False - The true / false field allows you to select a value that is either 1 or 0.

use Extended\ACF\Fields\TrueFalse;

TrueFalse::make('Social Media', 'display_social_media')
    ->instructions('Select whether to display social media links or not.')
    ->defaultValue(false)
    ->stylisedUi() // optional on and off text labels
    ->required();

Content Fields

File - The file field allows a file to be uploaded and selected.

use Extended\ACF\Fields\File;

File::make('Resturant Menu', 'menu')
    ->instructions('Add the menu <strong>pdf</strong> file.')
    ->mimeTypes(['pdf'])
    ->library('all') // all or uploadedTo
    ->fileSize('400 KB', 5) // MB if entered as int
    ->returnFormat('array') // id, url or array (default)
    ->required();

Gallery - The gallery field provides a simple and intuitive interface for managing a collection of images.

use Extended\ACF\Fields\Gallery;

Gallery::make('Images')
    ->instructions('Add the gallery images.')
    ->mimeTypes(['jpg', 'jpeg', 'png'])
    ->height(500, 1400)
    ->width(1000, 2000)
    ->min(1)
    ->max(6)
    ->fileSize('400 KB', 5) // MB if entered as int
    ->library('all') // all or uploadedTo
    ->returnFormat('array') // id, url or array (default)
    ->previewSize('medium') // thumbnail, medium or large
    ->required();

Image - The image field allows an image to be uploaded and selected.

use Extended\ACF\Fields\Image;

Image::make('Background Image')
    ->instructions('Add an image in at least 12000x100px and only in the formats <strong>jpg</strong>, <strong>jpeg</strong> or <strong>png</strong>.')
    ->mimeTypes(['jpg', 'jpeg', 'png'])
    ->height(500, 1400)
    ->width(1000, 2000)
    ->fileSize('400 KB', 5) // MB if entered as int
    ->library('all') // all or uploadedTo
    ->returnFormat('array') // id, url or array (default)
    ->previewSize('medium') // thumbnail, medium or large
    ->required();

Oembed - The oEmbed field allows an easy way to embed videos, images, tweets, audio, and other content.

use Extended\ACF\Fields\Oembed;

Oembed::make('Tweet')
    ->instructions('Add a tweet from Twitter.')
    ->required();

WYSIWYG - The WYSIWYG field creates a full WordPress tinyMCE content editor.

use Extended\ACF\Fields\WysiwygEditor;

WysiwygEditor::make('Content')
    ->instructions('Add the text content.')
    ->mediaUpload(false)
    ->tabs('visual')
    ->toolbar('simple') // toolbar name in snake_case
    ->required();

jQuery Fields

Color Picker - The color picker field allows a color to be selected via a JavaScript popup.

use Extended\ACF\Fields\ColorPicker;

ColorPicker::make('Text Color')
    ->instructions('Add the text color.')
    ->defaultValue('#4a9cff')
    ->required();

Date Picker - The date picker field creates a jQuery date selection popup.

use Extended\ACF\Fields\DatePicker;

DatePicker::make('Birthday')
    ->instructions('Add the employee\'s birthday.')
    ->displayFormat('d/m/Y')
    ->returnFormat('d/m/Y')
    ->required();

Time Picker - The time picker field creates a jQuery time selection popup.

use Extended\ACF\Fields\TimePicker;

TimePicker::make('Start Time', 'time')
    ->instructions('Add the start time.')
    ->displayFormat('H:i')
    ->returnFormat('H:i')
    ->required();

Date Time Picker - The date time picker field creates a jQuery date & time selection popup.

use Extended\ACF\Fields\DateTimePicker;

DateTimePicker::make('Event Date', 'date')
    ->instructions('Add the event\'s start date and time.')
    ->displayFormat('d-m-Y H:i')
    ->returnFormat('d-m-Y H:i')
    ->required();

Google Map - The Google Map field creates an interactive map with the ability to place a marker.

use Extended\ACF\Fields\GoogleMap;

GoogleMap::make('Address', 'address')
    ->instructions('Add the Google Map address.')
    ->center(57.456286, 18.377716)
    ->zoom(14)
    ->required();

Layout Fields

Accordion - The accordion field is used to organize fields into collapsible panels.

use Extended\ACF\Fields\Accordion;

Accordion::make('Address')
    ->open()
    ->multiExpand(),

// Allow accordion to remain open when other accordions are opened.
// Any field after this accordion will become a child.

Accordion::make('Endpoint')
    ->endpoint()
    ->multiExpand(),

// This field will not be visible, but will end the accordion above.
// Any fields added after this will not be a child to the accordion.

Clone - The clone field allows you to select and display existing fields or groups. This field doesn't have a custom field class. Instead create a new file with your field and import it using require where you need it.

// fields/email.php
use Extended\ACF\Fields\Email;

return Email::make('Email')
    ->required();

// employee.php
register_extended_field_group([
    'fields' => [
        require __DIR__.'/fields/email.php';
    ]
]);

Flexible Content - The flexible content field acts as a blank canvas to which you can add an unlimited number of layouts with full control over the order.

use Extended\ACF\Fields\FlexibleContent;
use Extended\ACF\Fields\Layout;
use Extended\ACF\Fields\Text;

FlexibleContent::make('Components', 'page_components')
    ->instructions('Add the employees occupation.')
    ->buttonLabel('Add a page component')
    ->layouts([
        Layout::make('Image')
            ->layout('block')
            ->fields([
                Text::make('Description')
            ])
    ])
    ->required();

Group - The group allows you to create a group of sub fields.

use Extended\ACF\Fields\Group;
use Extended\ACF\Fields\Image;
use Extended\ACF\Fields\Text;

Group::make('Hero')
    ->instructions('Add a hero block with title, content and image to the page.')
    ->fields([
        Text::make('Title'),
        Image::make('Background Image'),
    ])
    ->layout('row')
    ->required();

Message - The message fields allows you to display a text message.

use Extended\ACF\Fields\Message;

Message::make('Message')
    ->message('George. One point twenty-one gigawatts.')
    ->escapeHtml();

Repeater - The repeater field allows you to create a set of sub fields which can be repeated again and again whilst editing content!

use Extended\ACF\Fields\Image;
use Extended\ACF\Fields\Repeater;
use Extended\ACF\Fields\Text;

Repeater::make('Employees')
    ->instructions('Add the employees.')
    ->fields([
        Text::make('Name'),
        Image::make('Profile Picture'),
    ])
    ->min(2)
    ->collapsed('name')
    ->buttonLabel('Add employee')
    ->pagination(10)
    ->layout('table') // block, row or table
    ->required();

Tab - The tab field is used to group together fields into tabbed sections. Any fields or groups added after a acf_tab will become a child to that tab. Setting 'endpoint' to true on a tab will create a new group of tabs.

use Extended\ACF\Fields\Tab;

Tab::make('Tab 1'),
Tab::make('Tab 2'),
Tab::make('Tab 3')
    ->placement('top') // top or left
    ->endpoint(), // This will make a break in the tabs and create a new group of tabs.

Relational Fields

Link - The link field provides a simple way to select or define a link (url, title, target).

use Extended\ACF\Fields\Link;

Link::make('Read More Link')
    ->returnFormat('array') // url or array (default)
    ->required();

Page Link - The page link field allows the selection of 1 or more posts, pages or custom post types.

use Extended\ACF\Fields\PageLink;

PageLink::make('Contact Link')
    ->postTypes(['contact'])
    ->taxonomies(['category:city'])
    ->allowArchives() // optionally pass 'false' to disallow archives
    ->allowNull()
    ->allowMultiple()
    ->required();

Post Object - The post object field creates a select field where the choices are your pages + posts + custom post types.

use Extended\ACF\Fields\PostObject;

PostObject::make('Animal')
    ->instructions('Select an animal')
    ->postTypes(['animal'])
    ->allowNull()
    ->allowMultiple()
    ->returnFormat('object') // id or object (default)
    ->required();

Relationship - The relationship field creates a very attractive version of the post object field.

use Extended\ACF\Fields\Relationship;

Relationship::make('Contacts')
    ->instructions('Add the contacts.')
    ->postTypes(['contact'])
    ->filters([
        'search', 
        'post_type',
        'taxonomy'
    ])
    ->elements(['featured_image'])
    ->min(3)
    ->max(6)
    ->returnFormat('object') // id or object (default)
    ->required();

Taxonomy - The taxonomy field allows the selection of 1 or more taxonomy terms.

use Extended\ACF\Fields\Taxonomy;

Taxonomy::make('Cinemas')
    ->instructions('Select one or more cinema terms.')
    ->taxonomy('cinema')
    ->appearance('checkbox') // checkbox, multi_select, radio or select
    ->addTerm(true) // Allow new terms to be created whilst editing (true or false)
    ->loadTerms(true) // Load value from posts terms (true or false)
    ->saveTerms(true) // Connect selected terms to the post (true or false)
    ->returnFormat('id'); // object or id (default)

User - The user field creates a select field for all your users.

use Extended\ACF\Fields\User;

User::make('User')
    ->roles([
        'administrator',
        'author'
    ])
    ->returnFormat('array'); // id, object or array (default)

// Available roles are administrator, author, subscriber, contributor and editor. Default is no filter.

Location

The location class let you write custom location rules without the name, operator and value keys. If no operator is given it will use the operator as the value.

use Extended\ACF\Location;

Location::where('post_type', 'post')->and('post_type', '!=', 'post'); // available operators: ==, !=

Note: The if method was renamed to where in version 12, see the upgrade guide.

Conditional Logic

The conditional class help you write conditional logic without knowing the field keys.

use Extended\ACF\ConditionalLogic;
use Extended\ACF\Fields\File;
use Extended\ACF\Fields\Select;
use Extended\ACF\Fields\Url;
use Extended\ACF\Fields\Textarea;
use Extended\ACF\Fields\Text;

Select::make('Type')
    ->choices([
        'document' => 'Document',
        'link' => 'Link to resource',
        'embed' => 'Embed',
    ]),
File::make('Document', 'file')
    ->conditionalLogic([
        ConditionalLogic::where('type', '==', 'document') // available operators: ==, !=, >, <, ==pattern, ==contains, ==empty, !=empty
    ]),
Url::make('Link', 'url')
    ->conditionalLogic([
        ConditionalLogic::where('type', '==', 'link')
    ]),

// "and" condition
Textarea::make('Embed Code')
    ->conditionalLogic([
        ConditionalLogic::where('type', '!=', 'document')->and('type', '!=', 'link')
    ]),

// use multiple conditional logic for "or" condition
Text::make('Title')
    ->conditionalLogic([
        ConditionalLogic::where('type', '!=', 'document'),
        ConditionalLogic::where('type', '!=', 'link')
    ]),

// conditional logic that relies on another field from a different field group
Text::make('Sub Title')
    ->conditionalLogic([
      ConditionalLogic::where(
        group: 'other-group',
        name: 'enable_highlight', 
        operator: '==', 
        value: 'on', 
      )
    ]),

Custom Settings

If you want to add custom settings to the fields, you can use the withSettings method. If you add settings which are already registered on the field, they'll be overwritten.

Text::make('Name')
	->withSettings(['key' => 'value'])
	->required()

Another option is to extend field classes available in the package.

namespace App\Fields;

use Extended\ACF\Fields\Select as Field;

class Select extends Field
{
    public function myNewSetting(string $value): self
    {
        $this->settings['my-new-settings'] = $value;

        return $this;
    }
}

Custom Fields

If you want to create custom field classes you may extend the base field class. You may also import available setting traits in order to add common methods such as required() and intstructions().

namespace App\Fields;

use Extended\ACF\Fields\Field;
use Extended\ACF\Fields\Settings\Instructions;
use Extended\ACF\Fields\Settings\Required;

class OpenStreetMap extends Field
{
    use Instructions;
    use Required;

    protected $type = 'open_street_map';

    public function latitude(float $latitude): static
    {
        $this->settings['latitude'] = $latitude;

        return $this;
    }
    
    public function longitude(float $longitude): static
    {
        $this->settings['longitude'] = $longitude;

        return $this;
    }
    
    public function zoom(float $zoom): static
    {
        $this->settings['zoom'] = $zoom;

        return $this;
    }
}

When you're ready you can import use your field like any other field available in this library:

use App\Fields\OpenStreetMap;

OpenStreetMap::make('Map')
    ->latitude(56.474)
    ->longitude(11.863)
    ->zoom(10);

Upgrade Guide

This upgrade guide contains information on breaking changes in major releases of the package.

13

The package has been renamed to vinkla/extended-acf. If you're using version 12 or lower, you may simply change the package name in your composer.json file and everything will work as before.

-"wordplate/acf": "^12.0",
+"vinkla/extended-acf": "^12.0"

If you're upgrading to version 13, you'll also need to change your imports. The namespace has been changed to Extended\ACF.

-use WordPlate\Acf\Fields\Text;
-use WordPlate\Acf\Fields\Number;
+use Extended\ACF\Fields\Text;
+use Extended\ACF\Fields\Number;

12

The location query method if has been changed to where, you'll need to update your field groups accordingly.

use Extended\ACF\Location;

-Location::if('post_type', 'post');
+Location::where('post_type', 'post');

vinkla/extended-acf

vinkla

Reviews

Repository Details