Custom Logo Implementation in WordPress 4.5

Custom Logo is one of the awesome features of WordPress 4.5. You can see release detail of WordPress 4.5 “Coleman” here. Detail of Custom Logo is here. This link gives you detailed explanation of declaring support for Custom Logo and parameters available.

I needed to update my theme to use Custom Logo. But my all themes has logo option available. Image field was provided in the Customizer for logo. In the implementation of this new feature, existing logo was not supposed to be lost. So, I had to add new update script which will import old logo if set by use in existing theme.

Earlier, logo was displayed like following. Logo was saved in theme mod with key site_logo.

<?php

function awesome_logo() {

    $site_logo = get_theme_mod( 'site_logo' );
    if ( ! empty( $site_logo ) ) {
        ?>
        <a href="<?php echo esc_url( home_url( '/' ) ); ?>">
            <img src="<?php echo esc_url( $site_logo ); ?>" alt="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" />
        </a>
        <?php
    }

}

Update script I used is given below. I have tried to comment each step as much as possible as inline comments.

<?php

/**
 * Import existing logo URL and set it to Custom Logo.
 */
function awesome_import_logo_field() {

    // Bail if Custom Logo feature is not available.
    if ( version_compare( $GLOBALS['wp_version'], '4.5-alpha', '<' ) ) {
        return;
    }

    // Fetch old logo URL.
    $site_logo = get_theme_mod( 'site_logo' );

    // Bail if there is no existing logo.
    if ( empty( $site_logo ) ) {
        return;
    }

    // Get attachment ID.
    $attachment_id = attachment_url_to_postid( $site_logo );

    if ( $attachment_id > 0 ) {
        // We got valid attachment ID.
        set_theme_mod( 'custom_logo', $attachment_id );
        // Remove old logo value.
        remove_theme_mod( 'site_logo' );
    }

}
add_action( 'after_setup_theme', 'awesome_import_logo_field' );

/**
 * Updated function to use new Custom logo.
 */
function awesome_logo() {

    if( function_exists( 'the_custom_logo' ) ) {
        the_custom_logo();
    }
    else {
        $site_logo = get_theme_mod( 'site_logo' );
        if ( ! empty( $site_logo ) ) {
            ?>
            <a href="<?php echo esc_url( home_url( '/' ) ); ?>">
                <img src="<?php echo esc_url( $site_logo ); ?>" alt="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" />
            </a>
            <?php
        }
    }

}

What is happening here?

• awesome_import_logo_field function is hooked to after_setup_theme.
• Function will bail if WordPress version is lower than 4.5.
• Existing logo is fetched. If there is existing logo then, find corresponding attachment ID and set it to Custom Logo. `custom_logo` key is used in theme mod by Custom Logo.
• You also need to remove old logo after successful import.

In latest release of WordPress 4.5, another striking feature is support of partial refresh in Customizer. See Selective Refresh in the Customizer. Good thing is that Custom Logo automatically support this feature. You may have noticed this in Customizer. When logo is changed or removed, whole page is not refreshed, only section of logo is changed. It is faster and provides better user experience.
One more thing
You have already declared support for Custom Logo. And you also have old logo option in Customizer. So, you may want to hide your old logo option with version compare. For WP >= 4.5, Logo field provided by core will be displayed. On lower version your theme option will work as earlier.

<?php

// You want to hide your old logo option in Customizer if WP >= 4.5.
if ( version_compare( $GLOBALS['wp_version'], '4.5-alpha', '<' ) ) {
    $wp_customize->add_setting( 'site_logo',
        array(
            'default'           => '',
            'capability'        => 'edit_theme_options',
            'sanitize_callback' => 'esc_url_raw',
            )
        );
    $wp_customize->add_control(
        new WP_Customize_Image_Control( $wp_customize, 'site_logo',
            array(
                'label'    => __( 'Logo', 'awesome' ),
                'section'  => 'title_tagline',
                'settings' => 'site_logo',
                )
            )
        );
}