Helper Functions

Every field type reads back through one of these. A terse signature table is in Reference → Functions.

Option panel values

Reading option panel values

Option values are theme_mods — read them with tpmeta_get_option() or plain get_theme_mod(), interchangeably.

PHP · theme template

// Both lines are equivalent for scalar fields.
$color = tpmeta_get_option( 'accent_color', '#000000' );
$color = get_theme_mod( 'accent_color', '#000000' );

// Switch saved as boolean → real PHP bool, safe to use directly.
if ( tpmeta_get_option( 'hero_enabled' ) ) {
    get_template_part( 'template-parts/hero' );
}

Why a string switch is a footgun

A legacy switch stores the string 'false', which is truthy in PHP. Fields configured with data_type => 'boolean' are cast to a genuine bool on read, so if (...) behaves as expected. Prefer boolean switches for new fields.

Metabox / post meta values

Reading post & user meta

Metabox values are post_meta — read them with tpmeta_field(), which also returns the field's configured default when nothing is saved.

PHP · single template

// Uses the global $post when no ID is passed.
$title = tpmeta_field( 'hero_title' );

// Or target a specific post.
$title = tpmeta_field( 'hero_title', $post_id );

if ( $title ) {
    echo esc_html( $title );
}

Returns false when empty

tpmeta_field() falls back to the field default, and returns false when there is no value and no default — so a simple if ( $val ) guard is enough.

Composite fields

Images, galleries & repeaters

Composite fields have dedicated helpers that hand you ready-to-use data.

Repeaters

For option-panel repeaters, tpmeta_get_repeater_rows() returns a decoded array ready to loop. Sub-field defaults are merged in and boolean switches are cast for you.

PHP

$rows = tpmeta_get_repeater_rows( 'team_members' );

foreach ( $rows as $row ) {
    echo esc_html( $row['name'] );
    echo $row['gradient']['css']; // nested array, not a JSON string
}

A metabox repeater is read through tpmeta_field(), which returns the same array-of-rows structure.

Images

Use the image helpers so portable URL tokens (e.g. {{theme_url}}/img/x.jpg) resolve and the configured return format is honored.

PHP

// Metabox image field → { id, url, alt } (or URL/ID per return_format).
$img = tpmeta_image_field( 'hero_image' );
if ( $img ) {
    printf( '<img src="%s" alt="%s">',
        esc_url( $img['url'] ), esc_attr( $img['alt'] ) );
}

// Option-panel image field (resolves tokens, honors return_format).
$logo = tpmeta_image_option( 'header_logo', '', 'medium' );

// Any attachment ID → [ url, alt ].
$src = tpmeta_image( $attachment_id, 'full' );

Galleries

PHP

$images = tpmeta_gallery_field( 'project_gallery' );
foreach ( (array) $images as $image ) {
    printf( '<img src="%s" alt="%s">',
        esc_url( $image['url'] ), esc_attr( $image['alt'] ) );
}

Helper cheat-sheet

tpmeta_get_option · get_theme_mod · tpmeta_get_repeater_rows · tpmeta_field · tpmeta_image_field · tpmeta_image_option · tpmeta_image · tpmeta_gallery_field · tpmeta_gallery_images