ACF Options Page Helper — Global Theme Settings PHP

// ACF options page helper — production-tested PHP snippet by Mosharaf Hossain
<?php
// BAD: get_field(..., 'option') repeated across every template.
// No fallback. No type safety. If the field is empty, the page breaks silently.

$logo        = get_field( 'site_logo', 'option' );        // ACF field type: Image
$footer_text = get_field( 'footer_text', 'option' );      // ACF field type: Text
$social_fb   = get_field( 'facebook_url', 'option' );     // ACF field type: URL
$analytics   = get_field( 'analytics_code', 'option' );   // ACF field type: Textarea

// In three months you will have 40 get_field calls across 15 files
// and no way to know which ones have fallbacks and which ones don't.

// ACF options page helper
<?php
/**
 * Step 2 — One function, one fallback pattern.
 *
 * New in this step:
 *   theme_option() wraps get_field(..., 'option') with a default value.
 *   If the admin hasn't set the field, your theme still has something to show.
 *   You'll find this helper at the end of this section.
 */

// ACF field type: Text — footer copyright line.
$footer = theme_option( 'footer_text', '© ' . date( 'Y' ) . ' All rights reserved.' );
//         Returns the ACF value if set, otherwise the default string.

echo esc_html( $footer );

// ── The helper ──────────────────────────────────
function theme_option( string $field, mixed $default = '' ): mixed {
    $value = get_field( $field, 'option' );
    return $value !== null && $value !== '' ? $value : $default;
}

// ACF options page helper
<?php
/**
 * Step 3 — One helper per type, with the right escaping built in.
 *
 * New in this step:
 *   theme_option_text()     → returns string, pre-escaped with esc_html()
 *   theme_option_url()      → returns string, pre-escaped with esc_url()
 *   theme_option_wysiwyg()  → returns string, safe for wp_kses_post()
 *
 * You never think about the right escaping — the helper handles it.
 * You'll find the full helpers at the end of this section.
 */

// ACF field type: Text.
$phone = theme_option_text( 'contact_phone', 'Call us' );

// ACF field type: URL  — returns a raw URL field from ACF.
$facebook = theme_option_url( 'facebook_url' );

// ACF field type: WYSIWYG  — returns rich text, safe for output.
$footer_rich = theme_option_wysiwyg( 'footer_content', '<p>Footer default.</p>' );

if ( $phone ) : ?>
    <a href="tel:<?php echo esc_attr( str_replace( ' ', '', $phone ) ); ?>">
        <?php echo $phone; // Already escaped by theme_option_text(). ?>
    </a>
<?php endif;

if ( $facebook ) : ?>
    <a href="<?php echo $facebook; ?>" target="_blank" rel="noopener">Facebook</a>
<?php endif;

if ( $footer_rich ) : ?>
    <div class="footer-content"><?php echo $footer_rich; ?></div>
<?php endif;

// ACF options page helper
<?php
/**
 * Step 4 — Complex field types with complete return structures.
 *
 * New in this step:
 *   theme_option_image()    → returns [url, alt, width, height] or null.
 *   theme_option_repeater() → returns the repeater rows, or empty array.
 *
 * These wrap ACF's native return types so template code doesn't need to
 * know that image fields return IDs and repeater fields return arrays.
 * You'll find the helpers at the end of this section.
 */

// ACF field type: Image  — returns Image ID.
$logo = theme_option_image( 'site_logo' );

// ACF field type: Repeater
$socials = theme_option_repeater( 'social_links' );

if ( $logo ) : ?>
    <img src="<?php echo esc_url( $logo['url'] ); ?>"
         alt="<?php echo esc_attr( $logo['alt'] ); ?>"
         width="<?php echo esc_attr( $logo['width'] ); ?>"
         height="<?php echo esc_attr( $logo['height'] ); ?>" />
<?php endif;

if ( $socials ) :
    foreach ( $socials as $s ) : ?>
        <a href="<?php echo esc_url( $s['platform_url'] ?? '' ); ?>">
            <?php echo esc_html( $s['platform_name'] ?? '' ); ?>
        </a>
    <?php endforeach;
endif;

// ACF options page helper
<?php
/**
 * ACF Options Page Helper — type-safe access with defaults and escaping.
 *
 * Place in inc/helpers.php and require from functions.php.
 * All helpers share one pattern: read from 'option', return a default
 * if the field is empty, escape based on the expected type.
 */

function theme_option( string $field, mixed $default = '' ): mixed {
    $value = get_field( $field, 'option' );
    return ( $value !== null && $value !== '' ) ? $value : $default;
}

function theme_option_text( string $field, string $default = '' ): string {
    $value = theme_option( $field, $default );
    return is_string( $value ) ? esc_html( $value ) : $default;
}

function theme_option_url( string $field, string $default = '' ): string {
    $value = theme_option( $field, $default );
    return is_string( $value ) ? esc_url( $value ) : $default;
}

function theme_option_wysiwyg( string $field, string $default = '' ): string {
    $value = theme_option( $field, $default );
    return is_string( $value ) ? wp_kses_post( $value ) : $default;
}

function theme_option_textarea( string $field, string $default = '' ): string {
    $value = theme_option( $field, $default );
    return is_string( $value ) ? esc_textarea( $value ) : $default;
}

function theme_option_image( string $field ): ?array {
    $image_id = theme_option( $field, 0 );
    if ( ! $image_id || ! is_numeric( $image_id ) ) return null;

    $img = wp_get_attachment_image_src( (int) $image_id, 'full' );
    if ( ! $img ) return null;

    $alt = get_post_meta( (int) $image_id, '_wp_attachment_image_alt', true );
    return [
        'url'    => $img[0],
        'width'  => $img[1],
        'height' => $img[2],
        'alt'    => $alt ?: '',
        'id'     => (int) $image_id,
    ];
}

function theme_option_repeater( string $field ): array {
    $rows = theme_option( $field, [] );
    return is_array( $rows ) ? $rows : [];
}

// ── Usage ────────────────────────────────────────
// $logo     = theme_option_image( 'site_logo' );
// $phone    = theme_option_text( 'contact_phone', 'N/A' );
// $facebook = theme_option_url( 'facebook_url' );
// $footer   = theme_option_wysiwyg( 'footer_about' );
// $socials  = theme_option_repeater( 'social_links' );