Introducing “Update URI” theme header in WordPress 6.1

WordPress 6.1 introduces a new headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. available for theme authors. This allows third-party themes to avoid accidentally being overwritten with an update of a theme of a similar name from the WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ Theme Directory.

Previously, any custom theme which used the same slug as a theme hosted on WordPress.org was taking a significant risk of being overwritten by an update of the latter.

WordPress 6.1 introduces a new Update URI theme header field. If the value of this new field matches any URI other than https://wordpress.org/themes/{$slug}/ or w.org/theme/{$slug}, WordPress will not attempt to update it.

If set, the Update URI header field should be a URI and have a unique hostname.

Some examples include:

  • https://wordpress.org/themes/example-theme/
  • https://example.com/my-theme/
  • my-custom-theme-name

Update URI: false also works, and unless there is code handling the false hostname, the theme will never get an update notification.

If the header is present, the WordPress.org APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. will currently only return updates for the theme if it matches the following format:

  • https://wordpress.org/themes/{$slug}/
  • w.org/theme/{$slug}

If the header has any other value, the API will not return a result and will ignore the theme for update purposes.

Additionally, WordPress 6.1 introduces the update_themes_{$hostname} filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output., which third-party themes can use to offer updates for a given hostname. They can be used to filter the update response in multiple use cases.

This new hook filters the update response for a given theme hostname. The dynamic portion of the hook name, $hostname, refers to the hostname of the URI specified in the Update URI header field.

The hook has four arguments:

  • $update: The theme update data with the latest details. Default false.
  • $theme_data: The list of headers provided by the theme.
  • $theme_stylesheet: The theme stylesheet.
  • $locales: Installed locales to look translations for.

Please note that authors of themes hosted by WordPress.org don’t need to use this new header.

For reference, see tickets #14179, and changeset [53933].

Special thanks to @audrasjb and @sergeybiryukov as this post closely plagarizes Introducing “Update URI” plugin header in WordPress 5.8 and the commit message. Thanks to @costdev and @pbiron for review.

#6-1, #dev-notes, #dev-notes-6-1