Customizer API

<?php
/**
 * Customizer settings for Lumen Classic.
 *
 * @package Lumen_Classic
 */

const LUMEN_CLASSIC_DEFAULT_ACCENT = '#a3271f';

/**
 * Registers the Lumen Classic panel, sections, settings, controls and partial.
 *
 * @param WP_Customize_Manager $wp_customize Customizer manager.
 */
function lumen_classic_customize_register( WP_Customize_Manager $wp_customize ) {
	$wp_customize->add_panel(
		'lumen_classic_options',
		array(
			'title'    => __( 'Lumen Classic', 'lumen-classic' ),
			'priority' => 130,
		)
	);

	$wp_customize->add_section(
		'lumen_classic_colors',
		array(
			'title' => __( 'Accent colour', 'lumen-classic' ),
			'panel' => 'lumen_classic_options',
		)
	);

	$wp_customize->add_section(
		'lumen_classic_footer',
		array(
			'title' => __( 'Footer', 'lumen-classic' ),
			'panel' => 'lumen_classic_options',
		)
	);

	$wp_customize->add_setting(
		'lumen_classic_accent_color',
		array(
			'type'              => 'theme_mod',
			'capability'        => 'edit_theme_options',
			'default'           => LUMEN_CLASSIC_DEFAULT_ACCENT,
			'sanitize_callback' => 'sanitize_hex_color',
			'transport'         => 'postMessage',
		)
	);
	$wp_customize->add_control(
		new WP_Customize_Color_Control(
			$wp_customize,
			'lumen_classic_accent_color',
			array(
				'label'   => __( 'Accent colour', 'lumen-classic' ),
				'section' => 'lumen_classic_colors',
			)
		)
	);

	$wp_customize->add_setting(
		'lumen_classic_footer_text',
		array(
			'default'           => __( 'Lumen Press, independent publishers since 1998.', 'lumen-classic' ),
			'sanitize_callback' => 'sanitize_text_field',
			'transport'         => 'postMessage',
		)
	);
	$wp_customize->add_control(
		'lumen_classic_footer_text',
		array(
			'label'   => __( 'Footer text', 'lumen-classic' ),
			'section' => 'lumen_classic_footer',
			'type'    => 'text',
		)
	);
	$wp_customize->selective_refresh->add_partial(
		'lumen_classic_footer_text',
		array(
			'selector'            => '.site-footer__text',
			'container_inclusive' => false,
			'render_callback'     => 'lumen_classic_render_footer_text',
			'fallback_refresh'    => true,
		)
	);

	$wp_customize->add_setting(
		'lumen_classic_show_catalogue_link',
		array(
			'default'           => true,
			'sanitize_callback' => 'lumen_classic_sanitize_checkbox',
		)
	);
	$wp_customize->add_control(
		'lumen_classic_show_catalogue_link',
		array(
			'label'   => __( 'Link to the book catalogue in the footer', 'lumen-classic' ),
			'section' => 'lumen_classic_footer',
			'type'    => 'checkbox',
		)
	);
}
add_action( 'customize_register', 'lumen_classic_customize_register' );

/**
 * Sanitizes a checkbox value to a strict boolean.
 *
 * @param mixed $checked Raw value sent by the control.
 */
function lumen_classic_sanitize_checkbox( $checked ) {
	return true === $checked || '1' === $checked || 1 === $checked || 'true' === $checked;
}

/**
 * Prints the footer text; also the render callback of the selective-refresh partial.
 */
function lumen_classic_render_footer_text() {
	echo esc_html( get_theme_mod( 'lumen_classic_footer_text', __( 'Lumen Press, independent publishers since 1998.', 'lumen-classic' ) ) );
}

/**
 * Builds the inline CSS that exposes the accent colour as a custom property.
 */
function lumen_classic_accent_css() {
	$accent = sanitize_hex_color( get_theme_mod( 'lumen_classic_accent_color', LUMEN_CLASSIC_DEFAULT_ACCENT ) );
	if ( empty( $accent ) ) {
		$accent = LUMEN_CLASSIC_DEFAULT_ACCENT;
	}
	return sprintf( ':root { --lumen-classic-accent: %s; }', $accent );
}

/**
 * Loads the live-preview script inside the preview iframe only.
 */
function lumen_classic_customize_preview_js() {
	wp_enqueue_script(
		'lumen-classic-customizer-preview',
		get_template_directory_uri() . '/js/customizer-preview.js',
		array( 'customize-preview' ),
		wp_get_theme()->get( 'Version' ),
		array( 'in_footer' => true )
	);
}
add_action( 'customize_preview_init', 'lumen_classic_customize_preview_js' );

<?php
/**
 * Lumen Classic theme setup: additions to the functions.php of the Themes Overview page.
 *
 * @package Lumen_Classic
 */

require get_template_directory() . '/inc/customizer.php';

// Inside lumen_classic_setup(), after the existing add_theme_support() calls:
add_theme_support( 'customize-selective-refresh-widgets' );

// Inside lumen_classic_enqueue_assets(), after wp_enqueue_style( 'lumen-classic-style', ... ):
wp_add_inline_style( 'lumen-classic-style', lumen_classic_accent_css() );

<?php /* index.php: the footer, between </main> and wp_footer(); the rest is unchanged. */ ?>
<footer class="site-footer">
	<p class="site-footer__text"><?php lumen_classic_render_footer_text(); ?></p>
	<?php if ( get_theme_mod( 'lumen_classic_show_catalogue_link', true ) ) : ?>
		<p><a href="<?php echo esc_url( home_url( '/books/' ) ); ?>"><?php esc_html_e( 'Browse the catalogue', 'lumen-classic' ); ?></a></p>
	<?php endif; ?>
</footer>

/* global wp */
( function ( api ) {
	// Accent colour: update the custom property without reloading the preview.
	api( 'lumen_classic_accent_color', function ( value ) {
		value.bind( function ( to ) {
			document.documentElement.style.setProperty( '--lumen-classic-accent', to || '#a3271f' );
		} );
	} );
} )( wp.customize );

docker compose exec cli wp theme mod get lumen_classic_accent_color
docker compose exec cli wp theme mod set lumen_classic_accent_color '#1f4e79'
docker compose exec cli wp theme mod set lumen_classic_footer_text 'Lumen Press, Bristol.'

key	value
lumen_classic_accent_color
Success: Theme mod lumen_classic_accent_color set to #1f4e79.
Success: Theme mod lumen_classic_footer_text set to Lumen Press, Bristol..

docker compose exec -d cli wp server --host=127.0.0.1 --port=8080
docker compose exec cli php -r '
  $c = stream_context_create( array( "http" => array( "header" => "Host: lumenpress.test\r\n" ) ) );
  $h = file_get_contents( "http://127.0.0.1:8080/", false, $c );
  preg_match_all( "#<style id=\"lumen-classic-style-inline-css\">.*?</style>|<p class=\"site-footer__text\">.*?</p>|Browse the catalogue#s", $h, $m );
  echo implode( "\n", $m[0] ), "\n";'

<style id="lumen-classic-style-inline-css">
:root { --lumen-classic-accent: #1f4e79; }
/*# sourceURL=lumen-classic-style-inline-css */
</style>
<p class="site-footer__text">Lumen Press, Bristol.</p>
Browse the catalogue

docker compose exec cli wp theme mod set lumen_classic_accent_color 'red;}body{display:none'

Success: Theme mod lumen_classic_accent_color set to red;}body{display:none.

<?php
// Saves values through a Customizer changeset, so validation and sanitize_callback run as in the UI.
require_once ABSPATH . WPINC . '/class-wp-customize-manager.php';

function lumen_publish( array $values ) {
	global $wp_customize;
	$wp_customize = new WP_Customize_Manager( array( 'changeset_uuid' => wp_generate_uuid4() ) );
	do_action( 'customize_register', $wp_customize );
	$data = array();
	foreach ( $values as $id => $value ) {
		$data[ $id ] = array( 'value' => $value );
	}
	$result = $wp_customize->save_changeset_post( array( 'status' => 'publish', 'data' => $data ) );
	if ( ! is_wp_error( $result ) ) {
		echo "published\n";
		return;
	}
	echo $result->get_error_code(), "\n";
	foreach ( $result->get_error_data()['setting_validities'] as $id => $validity ) {
		echo '  ', $id, ': ', true === $validity ? 'valid' : $validity->get_error_code(), "\n";
	}
}

lumen_publish( array( 'lumen_classic_accent_color' => 'red' ) );
lumen_publish(
	array(
		'lumen_classic_accent_color'        => '#2E5E4E',
		'lumen_classic_footer_text'         => '<b>Lumen Press</b>, Bristol & Bath',
		'lumen_classic_show_catalogue_link' => '',
	)
);
foreach ( array( 'lumen_classic_accent_color', 'lumen_classic_footer_text', 'lumen_classic_show_catalogue_link' ) as $mod ) {
	echo $mod, ' = ', var_export( get_theme_mod( $mod ), true ), "\n";
}

docker compose exec cli wp eval-file /themes/changeset.php --user=admin

transaction_fail
  lumen_classic_accent_color: invalid_value
published
lumen_classic_accent_color = '#2E5E4E'
lumen_classic_footer_text = 'Lumen Press, Bristol & Bath'
lumen_classic_show_catalogue_link = false