When WordPress 4.3 was released, it added the ability for users to set a site icon, also known as a favicon, in the Customizer. In the past, users had to either add this manually, through a plugin, or through the theme options (if their theme included this functionality).

In this post, I’m looking at the last of those scenarios. What should theme authors do now that WordPress itself offers the equivalent functionality?

What Theme Authors Should Do

If you’re a theme author, you should probably start planning to remove your theme’s favicon code. There’s no point duplicating what is now in WordPress core, unless you are extending it in some way, and this is probably one of those things that doesn’t have a lot of scope for extension.

Also, note this from the Site Icons announcement post:

Site Icons work out of the box, are theme independent, and don’t require theme support.

That means that if a user goes into the Customizer and adds a site icon, it’s code is going to be added to the source, right next to your favicon code. It’ll look like this (the first 4 lines of favicon code come from core, the last 2 come from the theme):

Not good! So you should be removing your favicon code. However, I think it makes sense for this to be done in a backwards compatible manner.

Backwards Compatibility

Rather than just ripping your theme’s favicon right out of the theme, you should probably keep it for users who can’t yet use site icons. There are two parts to this:

1. Allowing a user to add a favicon via theme options
2. Outputting the code for the favicon to the page

Ideally we want to allow both of these for versions of WordPress prior to 4.3.

For users on 4.3, we want to restrict the use of number 1, getting them to add their favicon via site icons instead. However for number 2, we should probably keep outputting the favicon code until the user sets up a site icon (more on this later).

Input – Adding A Favicon Via Theme Options

Some of your users are probably not on WordPress 4.3 yet and won’t be able to use the site icons feature. To provide those users with your favicon theme option, but to prevent users on 4.3 from using it, you’d do something like this:

[sourcecode language=”php”]
// if the `wp_site_icon` function does not exist (ie we’re on < WP 4.3)
if ( ! function_exists( ‘wp_site_icon’ ) ) {
// show the user your favicon theme option
}
else {
// display a message advising the user to use the site icon feature
}
[/sourcecode]

This shows the theme’s favicon option to users who are on versions of WordPress older than 4.3. Users who are on WordPress 4.3 or above will be told to use the site icon feature. The message telling the user to user the site icon feature is a nicety to be sure. You could leave the else statement out and just not display anything (but you may get more support requests that way).

Output – Adding Favicon Code To The Source

Right, we’ve stopped people using your theme’s favicon option when they have the core site icon feature available. Now we need to control the output of your theme’s favicon code.

There’s a temptation to use the same if statement as above, checking for the existence of wp_site_icon, but there is a problem with this. This only checks whether the user is on WordPress 4.3 or above, it doesn’t check whether the user has actually set up the site icon.

If they haven’t then WordPress won’t be outputting any favicon code. By wrapping your favicon code in if ( ! function_exists( 'wp_site_icon' ) ), your theme won’t be outputting any favicon code either.

End result: The site icon will be added to the page if it exists, but the theme’s favicon code will only be output on versions prior to 4.3. Users on 4.3 without the site icon set will have no favicon code on the page at all.

The problem? Users will update to WordPress 4.3 and all of a sudden their favicon will disappear. Many will not realise that they need to re-add their favicon as a site icon. Bad for the user, bad for the length of your support queue.

Fortunately WordPress 4.3 gives us the has_site_icon function, which tells us whether a site icon has been set up or not. So we can use this code instead:

[sourcecode language=”php”]// If the `has_site_icon` function doesn’t exist (ie we’re on < WP 4.3) or if the site icon has not been set
if ( ! ( function_exists( ‘has_site_icon’ ) && has_site_icon() ) ) {
// output your theme favicon code to the page source
}
[/sourcecode]

This outputs the theme’s favicon code only if the user has not set a site icon (or if they are on versions of WordPress older than 4.3). If they have set a site icon, then the theme’s favicon code will not be included in the page, so there will be no duplication.

End result: There will always be one set of favicon code on the page. Priority will be given to the core site icon if it’s set, falling back to the theme’s favicon code if necessary.

What Theme Authors Shouldn’t Do

It is possible to remove the Site Icon section from the Customizer. I strongly recommend you don’t do that. This feature will be standard across all WordPress installations and removing it will only confuse people.

Final Thoughts

Now that site icons are in core, themes should be phasing out their favicon functionality. By using the code above to provide backwards compatibility, we can ensure that end users have a smooth transition from the old method to the new, without their favicon being lost.

There may be an alternative point of view that we should just let things break, as that will drive awareness and adoption of the new core feature (and encourage people to update). There will also be those who say, it’s just a favicon!

Both are right to a degree, but personally I think backwards compatibility is more important. What do you think?

Note: Credit goes to Kailoon Chan who had a long discussion with me about this, helping me polish these ideas.