This article, written to accord with WordPress 2.3, is now obsolete. Please take caution when following its contents, as many things may have changed.

Introduction

When a new major version of WordPress is released, such as WordPress 2.1 or 2.2, you may find that your Themes and Plugins no longer work the way you are used to. It could be that they are completely broken, because something in WordPress that was fundamental to them changed, but it's also possible that you can get them working again by updating some settings, or maybe just a small edit.

This article is part of a series on Migrating Plugins and Themes. It covers changes between WordPress Version 2.2 and Version 2.3, and what you need to do to Plugins and Themes to get them working in Version 2.3. You may also want to visit Migrating Plugins and Themes to 2.5 if you want to support later versions.

If you are the author of your Theme or Plugin, or if you have modified or customized your Theme, then this article will help you upgrade your Theme/Plugin for 2.3. If your Theme or Plugin is distributed publicly, after getting it working you may want to add it to the Compatibility lists above, so your users will know it is working and which version they should be running.

Fixing Up Your Theme or Plugin

Categories and Tags

The main change of importance to Plugins and Themes in Version 2.3 was the introduction of tagging as a core WordPress functionality.

If you want to add tags to your theme (e.g. to display the tags used on a post, or put a tag cloud into your sidebar), you will be interested in new the_tags and wp_tag_cloud template tag functions.

There were also quite a few new tag-related functions for use in plugins introduced in WordPress 2.3.

Also, as a side effect of introducing tags to WordPress, the underlying database table structure, in regards to storage of categories, was changed considerably. So, any plugins that ran queries using the category-related tables in the WordPress database will likely be broken; the queries will have to be completely rewritten. Plugins and Themes that used WordPress functions to access categories should be OK.

Canonical URLs

Another change in 2.3 that affects some plugins is the introduction of "canonical" URLs. The canonical URL system basically rewrites all URLs used in WordPress into "canonical" form, so that there is only one URL that points to a given display, and other URLs that could also point to that display are redirected to the "canonical" URL. Most plugins will not be affected by this change, but a plugin that adds suffixes to URLs could find that some of the URLs it generates are broken. Notably, a URL with a page number in it, such as example.com/page/2/ (to access the second page of older posts) must have the page section at the end of the URL. Prior versions of WordPress would have allowed example.com/page/2/suffix/ to work, but in WordPress 2.3, the URL must be generated as example.com/suffix/page/2 in order to function correctly.

Note that if you use a non-standard url/permalink structure that is necessary for the functioning of your site, the "canonical url" functionality can be turned off by adding the following to a plugin file or the functions.php file in your template folder:

remove_filter('template_redirect', 'redirect_canonical');

WordPress 2.5 will make a further filter available for choosing which canonical redirects are denied rather than forcing them to be all on or all off.