How to Create ACF Field Groups Programmatically with PHP

By Krasen Slavov Advanced Custom Fields (ACF) Tutorials

Programmatic ACF field registration through acf_add_local_field_group() enables version-controlled field configurations eliminating manual UI setup and database storage. From basic field group arrays and field type definitions to conditional logic arrays and dynamic field generation, programmatic registration ensures consistent deployments. This comprehensive guide teaches acf_add_local_field_group() syntax, field array structure, location rules, conditional logic, field cloning, and advanced techniques creating maintainable ACF configurations through code.

Why Register Fields Programmatically?

Benefits of Programmatic Registration:

  1. Version Control: Field configurations in Git
  2. Deployment: Automatic field sync across environments
  3. Code Review: Field changes reviewed in pull requests
  4. Portability: Easy theme/plugin distribution
  5. Performance: Faster than database lookups
  6. Documentation: Self-documenting field structure
  7. Automation: Dynamic field generation

Database vs Programmatic:

Database (UI):
- Stored in wp_posts
- Manual export/import
- Sync issues between environments

Programmatic (PHP):
- Stored in theme/plugin files
- Git versioned
- Automatic sync via code deployment

Basic Field Group Registration

Simple Field Group (functions.php):

function mytheme_register_acf_fields() {
    // Check if ACF is installed
    if (!function_exists('acf_add_local_field_group')) {
        return;
    }

    acf_add_local_field_group(array(
        'key' => 'group_product_details',
        'title' => 'Product Details',
        'fields' => array(
            array(
                'key' => 'field_product_price',
                'label' => 'Price',
                'name' => 'product_price',
                'type' => 'number',
                'prefix' => '$',
                'prepend' => '$',
                'step' => 0.01,
                'required' => 1,
            ),
            array(
                'key' => 'field_product_sku',
                'label' => 'SKU',
                'name' => 'product_sku',
                'type' => 'text',
                'placeholder' => 'Enter SKU',
            ),
        ),
        'location' => array(
            array(
                array(
                    'param' => 'post_type',
                    'operator' => '==',
                    'value' => 'product',
                ),
            ),
        ),
    ));
}
add_action('acf/init', 'mytheme_register_acf_fields');

Field Group Array Structure

Complete Field Group Configuration:

acf_add_local_field_group(array(
    // Required
    'key' => 'group_unique_key',
    'title' => 'Field Group Title',

    // Optional settings
    'fields' => array(), // Field array
    'location' => array(), // Location rules
    'menu_order' => 0, // Order in edit screen
    'position' => 'normal', // normal, acf_after_title, side
    'style' => 'default', // default, seamless
    'label_placement' => 'top', // top, left
    'instruction_placement' => 'label', // label, field
    'hide_on_screen' => array(), // Hide WP metaboxes
    'active' => true, // Active state
    'description' => '', // Group description
));

Common Field Types

Text Field:

array(
    'key' => 'field_company_name',
    'label' => 'Company Name',
    'name' => 'company_name',
    'type' => 'text',
    'default_value' => '',
    'placeholder' => '',
    'maxlength' => '',
    'required' => 0,
    'prepend' => '',
    'append' => '',
)

Textarea Field:

array(
    'key' => 'field_description',
    'label' => 'Description',
    'name' => 'description',
    'type' => 'textarea',
    'rows' => 4,
    'new_lines' => 'wpautop', // wpautop, br, ''
)

Number Field:

array(
    'key' => 'field_quantity',
    'label' => 'Quantity',
    'name' => 'quantity',
    'type' => 'number',
    'min' => 0,
    'max' => 100,
    'step' => 1,
    'default_value' => 1,
)

Email Field:

array(
    'key' => 'field_contact_email',
    'label' => 'Contact Email',
    'name' => 'contact_email',
    'type' => 'email',
    'required' => 1,
)

URL Field:

array(
    'key' => 'field_website',
    'label' => 'Website URL',
    'name' => 'website',
    'type' => 'url',
    'placeholder' => 'https://',
)

Select Field:

array(
    'key' => 'field_category',
    'label' => 'Category',
    'name' => 'category',
    'type' => 'select',
    'choices' => array(
        'technology' => 'Technology',
        'design' => 'Design',
        'marketing' => 'Marketing',
    ),
    'default_value' => 'technology',
    'allow_null' => 0,
    'multiple' => 0,
    'ui' => 1, // Enhanced UI
    'return_format' => 'value', // value, label, array
)

Checkbox Field:

array(
    'key' => 'field_features',
    'label' => 'Features',
    'name' => 'features',
    'type' => 'checkbox',
    'choices' => array(
        'ssl' => 'SSL Certificate',
        'backup' => 'Daily Backups',
        'support' => '24/7 Support',
    ),
    'default_value' => array(),
    'layout' => 'vertical', // vertical, horizontal
    'toggle' => 0,
    'return_format' => 'value', // value, label, array
)

Radio Button Field:

array(
    'key' => 'field_status',
    'label' => 'Status',
    'name' => 'status',
    'type' => 'radio',
    'choices' => array(
        'active' => 'Active',
        'inactive' => 'Inactive',
        'pending' => 'Pending',
    ),
    'default_value' => 'active',
    'layout' => 'horizontal',
)

True/False Field:

array(
    'key' => 'field_featured',
    'label' => 'Featured',
    'name' => 'is_featured',
    'type' => 'true_false',
    'default_value' => 0,
    'ui' => 1, // Toggle UI
    'ui_on_text' => 'Yes',
    'ui_off_text' => 'No',
)

Image Field:

array(
    'key' => 'field_featured_image',
    'label' => 'Featured Image',
    'name' => 'featured_image',
    'type' => 'image',
    'return_format' => 'array', // array, url, id
    'preview_size' => 'medium',
    'library' => 'all', // all, uploadedTo
    'min_width' => 800,
    'min_height' => 600,
    'max_size' => 2, // MB
)

File Field:

array(
    'key' => 'field_download',
    'label' => 'Downloadable File',
    'name' => 'download_file',
    'type' => 'file',
    'return_format' => 'array',
    'library' => 'all',
    'mime_types' => 'pdf,doc,docx',
)

Wysiwyg Editor:

array(
    'key' => 'field_content',
    'label' => 'Content',
    'name' => 'custom_content',
    'type' => 'wysiwyg',
    'tabs' => 'all', // all, visual, text
    'toolbar' => 'full', // full, basic
    'media_upload' => 1,
    'delay' => 0,
)

Date and Time Fields

Date Picker:

array(
    'key' => 'field_event_date',
    'label' => 'Event Date',
    'name' => 'event_date',
    'type' => 'date_picker',
    'display_format' => 'd/m/Y',
    'return_format' => 'Y-m-d',
    'first_day' => 1, // 0 = Sunday, 1 = Monday
)

Date Time Picker:

array(
    'key' => 'field_publish_datetime',
    'label' => 'Publish Date & Time',
    'name' => 'publish_datetime',
    'type' => 'date_time_picker',
    'display_format' => 'd/m/Y g:i a',
    'return_format' => 'Y-m-d H:i:s',
    'first_day' => 1,
)

Time Picker:

array(
    'key' => 'field_opening_time',
    'label' => 'Opening Time',
    'name' => 'opening_time',
    'type' => 'time_picker',
    'display_format' => 'g:i a',
    'return_format' => 'H:i:s',
)

Relationship and Post Object Fields

Post Object Field:

array(
    'key' => 'field_related_post',
    'label' => 'Related Post',
    'name' => 'related_post',
    'type' => 'post_object',
    'post_type' => array('post', 'page'),
    'taxonomy' => array(),
    'allow_null' => 0,
    'multiple' => 0,
    'return_format' => 'object', // object, id
    'ui' => 1,
)

Relationship Field:

array(
    'key' => 'field_related_projects',
    'label' => 'Related Projects',
    'name' => 'related_projects',
    'type' => 'relationship',
    'post_type' => array('portfolio'),
    'taxonomy' => array(),
    'filters' => array('search', 'post_type', 'taxonomy'),
    'min' => 0,
    'max' => 5,
    'return_format' => 'object',
)

Repeater Field (ACF PRO)

Repeater Configuration:

array(
    'key' => 'field_team_members',
    'label' => 'Team Members',
    'name' => 'team_members',
    'type' => 'repeater',
    'layout' => 'block', // table, block, row
    'button_label' => 'Add Team Member',
    'min' => 0,
    'max' => 10,
    'sub_fields' => array(
        array(
            'key' => 'field_member_name',
            'label' => 'Name',
            'name' => 'name',
            'type' => 'text',
        ),
        array(
            'key' => 'field_member_position',
            'label' => 'Position',
            'name' => 'position',
            'type' => 'text',
        ),
        array(
            'key' => 'field_member_photo',
            'label' => 'Photo',
            'name' => 'photo',
            'type' => 'image',
            'return_format' => 'array',
        ),
    ),
)

Flexible Content Field (ACF PRO)

Flexible Content Configuration:

array(
    'key' => 'field_page_content',
    'label' => 'Page Content',
    'name' => 'page_content',
    'type' => 'flexible_content',
    'button_label' => 'Add Content Block',
    'min' => 0,
    'max' => 20,
    'layouts' => array(
        'text_block' => array(
            'key' => 'layout_text',
            'name' => 'text_block',
            'label' => 'Text Block',
            'display' => 'block',
            'sub_fields' => array(
                array(
                    'key' => 'field_heading',
                    'label' => 'Heading',
                    'name' => 'heading',
                    'type' => 'text',
                ),
                array(
                    'key' => 'field_content',
                    'label' => 'Content',
                    'name' => 'content',
                    'type' => 'wysiwyg',
                ),
            ),
        ),
        'image_block' => array(
            'key' => 'layout_image',
            'name' => 'image_block',
            'label' => 'Image Block',
            'display' => 'block',
            'sub_fields' => array(
                array(
                    'key' => 'field_image',
                    'label' => 'Image',
                    'name' => 'image',
                    'type' => 'image',
                    'return_format' => 'array',
                ),
            ),
        ),
    ),
)

Gallery Configuration:

array(
    'key' => 'field_project_gallery',
    'label' => 'Project Gallery',
    'name' => 'project_gallery',
    'type' => 'gallery',
    'return_format' => 'array',
    'library' => 'all',
    'min' => 1,
    'max' => 50,
    'insert' => 'append', // append, prepend
    'preview_size' => 'medium',
)

Group Field

Group Configuration:

array(
    'key' => 'field_contact_info',
    'label' => 'Contact Information',
    'name' => 'contact_info',
    'type' => 'group',
    'layout' => 'block', // block, table, row
    'sub_fields' => array(
        array(
            'key' => 'field_email',
            'label' => 'Email',
            'name' => 'email',
            'type' => 'email',
        ),
        array(
            'key' => 'field_phone',
            'label' => 'Phone',
            'name' => 'phone',
            'type' => 'text',
        ),
    ),
)

Location Rules

Single Location Rule:

'location' => array(
    array(
        array(
            'param' => 'post_type',
            'operator' => '==',
            'value' => 'product',
        ),
    ),
)

Multiple Location Rules (OR):

'location' => array(
    // Show on Products OR Pages
    array(
        array(
            'param' => 'post_type',
            'operator' => '==',
            'value' => 'product',
        ),
    ),
    array(
        array(
            'param' => 'post_type',
            'operator' => '==',
            'value' => 'page',
        ),
    ),
)

Multiple Conditions (AND):

'location' => array(
    array(
        // Show on Pages AND page template is "Full Width"
        array(
            'param' => 'post_type',
            'operator' => '==',
            'value' => 'page',
        ),
        array(
            'param' => 'page_template',
            'operator' => '==',
            'value' => 'template-full-width.php',
        ),
    ),
)

Common Location Parameters:

// Post Type
'param' => 'post_type'
'param' => 'post'
'param' => 'page'

// Page Template
'param' => 'page_template'

// Taxonomy
'param' => 'post_taxonomy'
'param' => 'post_category'

// User Role
'param' => 'current_user_role'

// Options Page
'param' => 'options_page'

Conditional Logic

Show Field Based on Another Field:

array(
    'key' => 'field_enable_feature',
    'label' => 'Enable Feature',
    'name' => 'enable_feature',
    'type' => 'true_false',
),
array(
    'key' => 'field_feature_settings',
    'label' => 'Feature Settings',
    'name' => 'feature_settings',
    'type' => 'text',
    'conditional_logic' => array(
        array(
            array(
                'field' => 'field_enable_feature',
                'operator' => '==',
                'value' => '1',
            ),
        ),
    ),
)

Multiple Conditions (AND):

'conditional_logic' => array(
    array(
        array(
            'field' => 'field_type',
            'operator' => '==',
            'value' => 'premium',
        ),
        array(
            'field' => 'field_active',
            'operator' => '==',
            'value' => '1',
        ),
    ),
)

Multiple Conditions (OR):

'conditional_logic' => array(
    array(
        array(
            'field' => 'field_color',
            'operator' => '==',
            'value' => 'red',
        ),
    ),
    array(
        array(
            'field' => 'field_color',
            'operator' => '==',
            'value' => 'blue',
        ),
    ),
)

Dynamic Field Registration

Generate Fields from Array:

function mytheme_generate_dynamic_fields() {
    $social_networks = array('facebook', 'twitter', 'instagram', 'linkedin');
    $fields = array();

    foreach ($social_networks as $network) {
        $fields[] = array(
            'key' => 'field_' . $network,
            'label' => ucfirst($network) . ' URL',
            'name' => $network . '_url',
            'type' => 'url',
        );
    }

    acf_add_local_field_group(array(
        'key' => 'group_social_links',
        'title' => 'Social Links',
        'fields' => $fields,
        'location' => array(
            array(
                array(
                    'param' => 'options_page',
                    'operator' => '==',
                    'value' => 'acf-options',
                ),
            ),
        ),
    ));
}
add_action('acf/init', 'mytheme_generate_dynamic_fields');

Best Practices

Unique Keys:

// Good - unique, descriptive keys
'key' => 'field_product_price'
'key' => 'group_product_details'

// Bad - generic, duplicate-prone keys
'key' => 'field_1'
'key' => 'group_1'

Organize in Separate Files:

theme/
├── inc/
│   └── acf/
│       ├── field-groups.php
│       ├── product-fields.php
│       ├── page-fields.php
│       └── options-fields.php

Include in functions.php:

require_once get_template_directory() . '/inc/acf/field-groups.php';

Use Constants for Keys:

define('MYTHEME_PRODUCT_GROUP', 'group_product_details');
define('MYTHEME_PRICE_FIELD', 'field_product_price');

acf_add_local_field_group(array(
    'key' => MYTHEME_PRODUCT_GROUP,
    'fields' => array(
        array(
            'key' => MYTHEME_PRICE_FIELD,
            // ...
        ),
    ),
));

Conclusion

Programmatic ACF field registration with acf_add_local_field_group() enables version-controlled field configurations eliminating manual UI setup and database dependencies. Register field groups with unique keys and comprehensive field arrays, implement location rules for targeted display, add conditional logic for dynamic field visibility, and organize field registrations in separate files for maintainability. Programmatic registration ensures consistent ACF deployments across environments while providing code review capabilities and automatic synchronization through version control systems.

  1. acf_add_local_field_group() Documentation
  2. Field Type Settings
  3. Location Rules
  4. Conditional Logic
  5. Local JSON Feature

Call to Action

Programmatic field configurations need backup protection. Backup Copilot Pro backs up your WordPress theme files and ACF code automatically. Safeguard your version-controlled fields—start your free 30-day trial today!

Related Articles