Advanced Custom Fields PRO

https://github.com/wordpress-premium/advanced-custom-fields-pro
Admin
Advanced Custom Fields PRO (ACF) is a powerful WordPress plugin that allows users to customize...
Tokens:6,765
Snippets:38
Trust Score:9
Update:10 months ago
Show doc for...
Tokens:
Raw
### Create Custom Options Pages with ACF in PHP

Source: https://context7.com/wordpress-premium/advanced-custom-fields-pro/llms.txt

Demonstrates how to register custom options pages and sub-pages for site-wide settings using ACF. Includes examples of adding main pages, sub-pages, and retrieving/updating option values from the database.

```php
<?php
// Register a simple options page
if (function_exists('acf_add_options_page')) {
    acf_add_options_page(array(
        'page_title' => 'Theme Settings',
        'menu_title' => 'Theme Settings',
        'menu_slug' => 'theme-settings',
        'capability' => 'edit_posts',
        'icon_url' => 'dashicons-admin-generic',
        'position' => 30,
    ));
}

// Register options page with sub pages
if (function_exists('acf_add_options_page')) {
    acf_add_options_page(array(
        'page_title' => 'Site Settings',
        'menu_title' => 'Site Settings',
        'menu_slug' => 'site-settings',
        'capability' => 'manage_options',
        'redirect' => false,
    ));

    acf_add_options_sub_page(array(
        'page_title' => 'Header Settings',
        'menu_title' => 'Header',
        'parent_slug' => 'site-settings',
    ));

    acf_add_options_sub_page(array(
        'page_title' => 'Footer Settings',
        'menu_title' => 'Footer',
        'parent_slug' => 'site-settings',
    ));

    acf_add_options_sub_page(array(
        'page_title' => 'Social Media',
        'menu_title' => 'Social Media',
        'parent_slug' => 'site-settings',
    ));
}

// Retrieve options page values
$header_logo = get_field('header_logo', 'option');
$footer_text = get_field('footer_copyright', 'option');
$facebook_url = get_field('facebook_url', 'option');

// Update options page values
update_field('site_email', 'contact@example.com', 'option');
update_field('maintenance_mode', true, 'option');
?>
```

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

### Handle ACF Flexible Content Layouts in WordPress

Source: https://context7.com/wordpress-premium/advanced-custom-fields-pro/llms.txt

Provides examples for iterating through and displaying content from ACF flexible content fields. It shows how to identify the current layout and retrieve sub-field values specific to each layout type.

```php
<?php
// Loop through flexible content layouts
if (have_rows('page_sections')) {
    while (have_rows('page_sections')) {
        the_row();
        $layout = get_row_layout();

        if ($layout === 'text_section') {
            echo '<div class="text-section">';
            echo '<h2>' . get_sub_field('heading') . '</h2>';
            echo '<div>' . get_sub_field('content') . '</div>';
            echo '</div>';
        } elseif ($layout === 'image_gallery') {
            $images = get_sub_field('images');
            echo '<div class="gallery">';
            foreach ($images as $image) {
                echo '<img src="' . esc_url($image['url']) . '" alt="' . esc_attr($image['alt']) . '" />';
            }
            echo '</div>';
        } elseif ($layout === 'call_to_action') {
            echo '<div class="cta">';
            echo '<h3>' . get_sub_field('cta_heading') . '</h3>';
            echo '<a href="' . get_sub_field('button_link') . '" class="button">';
            echo get_sub_field('button_text');
            echo '</a>';
            echo '</div>';
        }
    }
}
?>
```

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

### Register Custom ACF Blocks in PHP

Source: https://context7.com/wordpress-premium/advanced-custom-fields-pro/llms.txt

This snippet demonstrates how to register custom Gutenberg block types using Advanced Custom Fields Pro in PHP. It includes examples for a testimonial block using a template file and a hero banner block with a render callback function. Ensure ACF is active and the specified template files or callback functions exist.

```php
<?php
// Register a testimonial block
add_action('acf/init', 'register_acf_blocks');
function register_acf_blocks() {
    if (function_exists('acf_register_block_type')) {
        acf_register_block_type(array(
            'name' => 'testimonial',
            'title' => __('Testimonial'),
            'description' => __('A custom testimonial block.'),
            'render_template' => 'template-parts/blocks/testimonial.php',
            'category' => 'formatting',
            'icon' => 'admin-comments',
            'keywords' => array('testimonial', 'quote', 'review'),
            'supports' => array(
                'align' => true,
                'mode' => true,
                'jsx' => true,
            ),
        ));

        acf_register_block_type(array(
            'name' => 'hero-banner',
            'title' => __('Hero Banner'),
            'description' => __('A hero banner with image and text.'),
            'render_callback' => 'render_hero_banner_block',
            'category' => 'layout',
            'icon' => 'cover-image',
            'keywords' => array('hero', 'banner', 'header'),
            'supports' => array(
                'align' => array('wide', 'full'),
                'anchor' => true,
            ),
        ));
    }
}

// Render callback for hero banner block
function render_hero_banner_block($block, $content = '', $is_preview = false) {
    $heading = get_field('heading');
    $subheading = get_field('subheading');
    $background_image = get_field('background_image');
    $button_text = get_field('button_text');
    $button_link = get_field('button_link');

    $class = 'hero-banner';
    if (!empty($block['className'])) {
        $class .= ' ' . $block['className'];
    }
    if (!empty($block['align'])) {
        $class .= ' align' . $block['align'];
    }
    ?>
    <div class="<?php echo esc_attr($class); ?>" style="background-image: url('<?php echo esc_url($background_image['url']); ?>');">
        <div class="hero-content">
            <h1><?php echo esc_html($heading); ?></h1>
            <p><?php echo esc_html($subheading); ?></p>
            <?php if ($button_text && $button_link): ?>
                <a href="<?php echo esc_url($button_link); ?>" class="button">
                    <?php echo esc_html($button_text); ?>
                </a>
            <?php endif; ?>
        </div>
    </div>
    <?php
}
?>

```

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

### Modify ACF Field Values with PHP Hooks and Filters

Source: https://context7.com/wordpress-premium/advanced-custom-fields-pro/llms.txt

This PHP code illustrates how to customize the behavior of Advanced Custom Fields using WordPress hooks and ACF's filter system. It shows examples for modifying field values before loading and saving, populating select field choices dynamically, formatting output, validating input, and performing actions after saving a post. These filters and actions require ACF to be installed and active.

```php
<?php
// Modify value before loading from database
add_filter('acf/load_value/name=price', 'format_price_on_load', 10, 3);
function format_price_on_load($value, $post_id, $field) {
    return floatval($value);
}

// Modify value before saving to database
add_filter('acf/update_value/name=email', 'sanitize_email_on_save', 10, 3);
function sanitize_email_on_save($value, $post_id, $field) {
    return sanitize_email($value);
}

// Modify field settings
add_filter('acf/load_field/name=my_select', 'populate_select_choices', 10, 1);
function populate_select_choices($field) {
    $field['choices'] = array();

    $posts = get_posts(array('post_type' => 'product', 'posts_per_page' => -1));
    foreach ($posts as $post) {
        $field['choices'][$post->ID] = $post->post_title;
    }

    return $field;
}

// Format value for display
add_filter('acf/format_value/type=text', 'uppercase_text_fields', 10, 3);
function uppercase_text_fields($value, $post_id, $field) {
    return strtoupper($value);
}

// Validate field input
add_filter('acf/validate_value/name=phone', 'validate_phone_number', 10, 4);
function validate_phone_number($valid, $value, $field, $input) {
    if ($valid !== true) {
        return $valid;
    }

    if (!preg_match('/^[0-9\-\+\(\) ]+$/', $value)) {
        return 'Please enter a valid phone number';
    }

    return $valid;
}

// Save post hook
add_action('acf/save_post', 'my_acf_save_post', 20);
function my_acf_save_post($post_id) {
    // Check if specific field was updated
    if (get_field('featured_product', $post_id)) {
        // Perform custom action
        do_action('featured_product_updated', $post_id);
    }

    // Clear cache
    wp_cache_delete('custom_cache_key');
}
?>

```

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

### Register ACF Field Groups Programmatically in PHP

Source: https://context7.com/wordpress-premium/advanced-custom-fields-pro/llms.txt

Defines how to register Advanced Custom Fields (ACF) field groups using PHP code. This allows for version control of field structures. It supports various field types like number, text, true/false, gallery, and select, along with location rules and conditional logic.

```php
<?php
// Register a field group with multiple fields dilakukan_acf_add_local_field_group(array(
    'key' => 'group_product_details',
    'title' => 'Product Details',
    'fields' => array(
        array(
            'key' => 'field_price',
            'label' => 'Price',
            'name' => 'price',
            'type' => 'number',
            'required' => 1,
            'min' => 0,
            'step' => 0.01,
            'prepend' => '$',
        ),
        array(
            'key' => 'field_sku',
            'label' => 'SKU',
            'name' => 'sku',
            'type' => 'text',
            'placeholder' => 'Enter product SKU',
        ),
        array(
            'key' => 'field_in_stock',
            'label' => 'In Stock',
            'name' => 'in_stock',
            'type' => 'true_false',
            'default_value' => 1,
            'ui' => 1,
        ),
        array(
            'key' => 'field_product_images',
            'label' => 'Product Images',
            'name' => 'product_images',
            'type' => 'gallery',
            'min' => 1,
            'max' => 10,
            'return_format' => 'array',
        ),
    ),
    'location' => array(
        array(
            array(
                'param' => 'post_type',
                'operator' => '==',
                'value' => 'product',
            ),
        ),
    ),
    'menu_order' => 0,
    'position' => 'normal',
    'style' => 'default',
    'label_placement' => 'top',
    'instruction_placement' => 'label',
));

// Register field group with conditional logic dilakukan_acf_add_local_field_group(array(
    'key' => 'group_event_details',
    'title' => 'Event Details',
    'fields' => array(
        array(
            'key' => 'field_event_type',
            'label' => 'Event Type',
            'name' => 'event_type',
            'type' => 'select',
            'choices' => array(
                'online' => 'Online',
                'in-person' => 'In Person',
            ),
        ),
        array(
            'key' => 'field_venue',
            'label' => 'Venue',
            'name' => 'venue',
            'type' => 'text',
            'conditional_logic' => array(
                array(
                    array(
                        'field' => 'field_event_type',
                        'operator' => '==',
                        'value' => 'in-person',
                    ),
                ),
            ),
        ),
        array(
            'key' => 'field_meeting_link',
            'label' => 'Meeting Link',
            'name' => 'meeting_link',
            'type' => 'url',
            'conditional_logic' => array(
                array(
                    array(
                        'field' => 'field_event_type',
                        'operator' => '==',
                        'value' => 'online',
                    ),
                ),
            ),
        ),
    ),
    'location' => array(
        array(
            array(
                'param' => 'post_type',
                'operator' => '==',
                'value' => 'event',
            ),
        ),
    ),
));
?>
```

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

### Work with ACF Repeater Fields in WordPress

Source: https://context7.com/wordpress-premium/advanced-custom-fields-pro/llms.txt

Demonstrates how to loop through and manage data within ACF repeater fields. This includes iterating through rows, accessing sub-field values, adding rows programmatically, and retrieving the row count.

```php
<?php
// Loop through repeater field
if (have_rows('team_members')) {
    echo '<div class="team-list">';
    while (have_rows('team_members')) {
        the_row();
        $name = get_sub_field('member_name');
        $title = get_sub_field('member_title');
        $photo = get_sub_field('member_photo');

        echo '<div class="team-member">';
        if ($photo) {
            echo '<img src="' . esc_url($photo['url']) . '" alt="' . esc_attr($name) . '" />';
        }
        echo '<h3>' . esc_html($name) . '</h3>';
        echo '<p>' . esc_html($title) . '</p>';
        echo '</div>';
    }
    echo '</div>';
}

// Nested repeater fields
if (have_rows('departments')) {
    while (have_rows('departments')) {
        the_row();
        echo '<h2>' . get_sub_field('department_name') . '</h2>';

        if (have_rows('employees')) {
            echo '<ul>';
            while (have_rows('employees')) {
                the_row();
                echo '<li>' . get_sub_field('employee_name') . '</li>';
            }
            echo '</ul>';
        }
    }
}

// Add repeater row programmatically
$row = array(
    'member_name' => 'John Doe',
    'member_title' => 'Developer',
    'member_email' => 'john@example.com'
);
add_row('team_members', $row, $post_id);

// Get repeater row count
$count = count(get_field('team_members', $post_id));
echo 'Total team members: ' . $count;
?>
```

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

### PHP: Retrieve ACF Field Object Data

Source: https://context7.com/wordpress-premium/advanced-custom-fields-pro/llms.txt

Fetches the complete field configuration object, including its label, type, instructions, and current value. Allows for conditional logic based on field properties and can retrieve data without loading the value.

```php
<?php
// Get complete field object with value
$field_object = get_field_object('email_address');

if ($field_object) {
    echo 'Label: ' . $field_object['label'];
    echo 'Type: ' . $field_object['type'];
    echo 'Value: ' . $field_object['value'];
    echo 'Instructions: ' . $field_object['instructions'];

    // Check field type and display accordingly
    if ($field_object['type'] === 'select') {
        echo 'Choices: ' . print_r($field_object['choices'], true);
    }
}

// Get field object without loading value
$field_config = get_field_object('my_field', false, false, false);

// Get with escaped HTML value
$safe_field = get_field_object('user_bio', get_the_ID(), true, true, true);
?>
```

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

### Query Posts by ACF Field Values in PHP

Source: https://context7.com/wordpress-premium/advanced-custom-fields-pro/llms.txt

This PHP code snippet demonstrates how to query WordPress posts (e.g., 'product' or 'event' post types) using ACF field values. It shows filtering by numeric ranges, exact matches, dates, and using OR/AND relations for complex conditions. Dependencies include the Advanced Custom Fields PRO plugin and WordPress environment.

```php
<?php
// Query posts by custom field value
$args = array(
    'post_type' => 'product',
    'posts_per_page' => 10,
    'meta_query' => array(
        array(
            'key' => 'price',
            'value' => array(10, 100),
            'compare' => 'BETWEEN',
            'type' => 'NUMERIC',
        ),
        array(
            'key' => 'in_stock',
            'value' => '1',
            'compare' => '=',
        ),
    ),
    'orderby' => 'meta_value_num',
    'meta_key' => 'price',
    'order' => 'ASC',
);

$products = new WP_Query($args);

if ($products->have_posts()) {
    while ($products->have_posts()) {
        $products->the_post();
        echo '<h3>' . get_the_title() . '</h3>';
        echo '<p>Price: $' . get_field('price') . '</p>';
        echo '<p>SKU: ' . get_field('sku') . '</p>';
    }
    wp_reset_postdata();
}

// Complex meta query with multiple conditions
$args = array(
    'post_type' => 'event',
    'meta_query' => array(
        'relation' => 'AND',
        array(
            'key' => 'event_date',
            'value' => date('Y-m-d'),
            'compare' => '>='',
            'type' => 'DATE',
        ),
        array(
            'relation' => 'OR',
            array(
                'key' => 'event_type',
                'value' => 'online',
                'compare' => '=',
            ),
            array(
                'key' => 'venue_city',
                'value' => 'New York',
                'compare' => '=',
            ),
        ),
    ),
);

$events = new WP_Query($args);

// Working with relationship fields
$related_posts = get_field('related_articles');
if ($related_posts) {
    echo '<ul class="related">';
    foreach ($related_posts as $post) {
        setup_postdata($post);
        echo '<li>';
        echo '<a href="' . get_permalink() . '">' . get_the_title() . '</a>';
        echo '<p>' . get_the_excerpt() . '</p>';
        echo '</li>';
    }
    echo '</ul>';
    wp_reset_postdata();
}
?>
```

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

### PHP: Retrieve All ACF Fields for a Post

Source: https://context7.com/wordpress-premium/advanced-custom-fields-pro/llms.txt

Retrieves all custom field values associated with a specific post ID, options page, or other supported content types. The data is returned as an associative array, allowing iteration and access by field name.

```php
<?php
// Get all fields from current post
$fields = get_fields();

if ($fields) {
    foreach ($fields as $name => $value) {
        echo '<p><strong>' . esc_html($name) . ':</strong> ' . esc_html($value) . '</p>';
    }
}

// Get all fields from specific post
$post_fields = get_fields(456);

// Get all fields from options page
$options = get_fields('option');
echo 'Site Email: ' . $options['site_email'];
echo 'Phone: ' . $options['contact_phone'];

// Get with HTML escaping for safe output
$safe_fields = get_fields(123, true, true);
?>
```

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

### PHP: Retrieve Custom Field Values with ACF

Source: https://context7.com/wordpress-premium/advanced-custom-fields-pro/llms.txt

Retrieves custom field values for a given field name or key and post ID. Supports various sources like posts, options pages, users, and taxonomies. Can return formatted, unformatted, or escaped HTML values.

```php
<?php
// Get a simple text field from the current post
$company_name = get_field('company_name');
echo $company_name; // Output: "Acme Corporation"

// Get an image field from a specific post, formatted as array
$image = get_field('hero_image', 123, true);
if ($image) {
    echo '<img src="' . esc_url($image['url']) . '" alt="' . esc_attr($image['alt']) . '" />';
}

// Get field from options page
$site_logo = get_field('site_logo', 'option');

// Get field from user
$bio = get_field('biography', 'user_' . get_current_user_id());

// Get field from taxonomy term
$term_color = get_field('color', 'term_' . $term_id);

// Get unformatted value (raw database value)
$raw_value = get_field('my_field', 123, false);

// Get escaped HTML value (safe for output)
$safe_value = get_field('user_content', 123, true, true);
?>
```

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

### PHP: Display Custom Field Values with ACF

Source: https://context7.com/wordpress-premium/advanced-custom-fields-pro/llms.txt

Outputs a custom field value with automatic HTML escaping, ensuring safe display in templates. Can retrieve values from specific posts or use default formatting.

```php
<?php
// Display field value with automatic escaping
the_field('company_name');

// Display from specific post
the_field('company_name', 123);

// Display unformatted value (still escaped)
the_field('price', get_the_ID(), false);

// Example in template
?>
<h1><?php the_field('page_title'); ?></h1>
<div class="content">
    <?php the_field('page_description'); ?>
</div>
```

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

### PHP: Update Custom Field Values with ACF

Source: https://context7.com/wordpress-premium/advanced-custom-fields-pro/llms.txt

Updates or creates a custom field value for a specified field name or key, post ID, user, or taxonomy term. Supports updating complex fields like repeaters and allows using field keys for greater reliability.

```php
<?php
// Update field on current post
update_field('company_name', 'New Company Inc.');

// Update field on specific post
update_field('status', 'active', 123);

// Update options page field
update_field('site_email', 'info@example.com', 'option');

// Update user field
update_field('favorite_color', 'blue', 'user_' . $user_id);

// Update term field
update_field('term_icon', 'star', 'term_' . $term_id);

// Update complex field (repeater row)
$rows = array(
    array('title' => 'Item 1', 'content' => 'Description 1'),
    array('title' => 'Item 2', 'content' => 'Description 2')
);
update_field('repeater_field', $rows, $post_id);

// Update with field key (more reliable)
update_field('field_5f8a3b2c1d4e6', 'value', $post_id);
?>
```

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

### Check ACF Field Existence and Value in WordPress

Source: https://context7.com/wordpress-premium/advanced-custom-fields-pro/llms.txt

Verifies if an Advanced Custom Field has a value assigned to it. This can be done using `have_rows()` for repeatable fields or `get_field()` for checking general field existence and retrieving its value.

```php
<?php
// Check if field has value on current post
if (have_rows('gallery_images')) {
    // Field exists and has rows
}

// Using get_field to check existence
$value = get_field('optional_field');
if ($value !== false && $value !== null && $value !== '') {
    echo 'Field has value: ' . $value;
}

// Check specific post
if (get_field('custom_field', 456)) {
    echo 'Field exists on post 456';
}
?>
```

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

### Delete ACF Field Value in WordPress

Source: https://context7.com/wordpress-premium/advanced-custom-fields-pro/llms.txt

Removes a custom field value from the WordPress database for a specific post, options page, or user. It utilizes the `delete_field()` function provided by ACF.

```php
<?php
// Delete field from current post
delete_field('temporary_field');

// Delete field from specific post
delete_field('old_data', 123);

// Delete from options page
delete_field('deprecated_option', 'option');

// Delete from user
delete_field('temp_setting', 'user_' . $user_id);
?>
```
Tokens:
Raw