acf-custom-field-type

ACF custom field type

The acf_field extension API is available in ACF Free and PRO. A custom field type should solve a distinct input/value contract, not merely restyle a Text or Select field. Prefer a built-in field plus targeted filters when its raw value, validation, and return format already fit.

Register after the field API exists

add_action( 'acf/include_field_types', static function ( $api_version ): void {
    if ( ! class_exists( 'acf_field' ) ) {
        return;
    }

    require_once __DIR__ . '/includes/class-acme-acf-field-json.php';
    acf_register_field_type( 'Acme_ACF_Field_JSON' );
} );

Keep registration idempotent and feature-detect ACF. The hook receives ACF's field API version; do not confuse it with the plugin version.

In ACF 6.8.10 the base constructor calls initialize(). Set properties there instead of replacing __construct() and accidentally skipping base hook registration.

Define the field contract

final class Acme_ACF_Field_JSON extends acf_field {
    public function initialize() {
        $this->name        = 'acme_json';
        $this->label       = __( 'JSON object', 'acme-addon' );
        $this->category    = 'advanced';
        $this->description = __( 'Stores a validated JSON object.', 'acme-addon' );
        $this->defaults    = array(
            'rows' => 8,
        );
        $this->show_in_rest = true;
    }

    public function render_field_settings( $field ) {
        acf_render_field_setting( $field, array(
            'label' => __( 'Rows', 'acme-addon' ),
            'name'  => 'rows',
            'type'  => 'number',
            'min'   => 3,
        ) );
    }

    public function render_field( $field ) {
        $value = is_array( $field['value'] )
            ? wp_json_encode( $field['value'], JSON_PRETTY_PRINT )
            : (string) $field['value'];

        printf(
            '<textarea name="%s" rows="%d">%s</textarea>',
            esc_attr( $field['name'] ),
            max( 3, (int) $field['rows'] ),
            esc_textarea( $value )
        );
    }

    public function validate_value( $valid, $value, $field, $input ) {
        if ( true !== $valid || '' === $value || is_array( $value ) ) {
            return $valid;
        }

        json_decode( (string) $value, true );
        return JSON_ERROR_NONE === json_last_error()
            ? true
            : __( 'Enter valid JSON.', 'acme-addon' );
    }

    public function update_value( $value, $post_id, $field ) {
        if ( is_array( $value ) || '' === $value || null === $value ) {
            return $value;
        }

        $decoded = json_decode( (string) $value, true );
        return JSON_ERROR_NONE === json_last_error() ? $decoded : null;
    }
}