acf-field-group-development

ACF field group development

Treat an ACF field definition as a versioned data contract. The field key is ACF's identity, the field name becomes the storage/API name, the field type determines raw and formatted value shapes, and location rules decide where the editing UI appears. Changing any of these can be a data migration even when the admin screen still looks correct.

Choose the ownership model

Do not register the same group independently in PHP and JSON. Pick one canonical owner, or make the precedence and sync workflow explicit.

Register a plugin-owned group

Register on acf/init. Do not wrap registration in is_admin(): frontend calls to get_field() need the same definitions for field lookup and formatting.

add_action( 'acf/init', static function (): void {
    if ( ! function_exists( 'acf_add_local_field_group' ) ) {
        return;
    }

    acf_add_local_field_group( array(
        'key'   => 'group_acme_event_details',
        'title' => __( 'Event details', 'acme-events' ),
        'fields' => array(
            array(
                'key'          => 'field_acme_event_start',
                'label'        => __( 'Start time', 'acme-events' ),
                'name'         => 'acme_event_start',
                'type'         => 'date_time_picker',
                'display_format' => 'Y-m-d H:i',
                'return_format'  => 'Y-m-d H:i:s',
                'required'       => 1,
            ),
            array(
                'key'   => 'field_acme_event_summary',
                'label' => __( 'Summary', 'acme-events' ),
                'name'  => 'acme_event_summary',
                'type'  => 'textarea',
                'rows'  => 4,
            ),
        ),
        'location' => array(
            array(
                array(
                    'param'    => 'post_type',
                    'operator' => '==',
                    'value'    => 'acme_event',
                ),
            ),
        ),
        'show_in_rest' => 1,
    ) );
} );