Preparing your plugins and your client sites for termmeta

The biggest hurdle in the introduction of metadata for taxonomy terms (#10142) is compatibility with existing plugins and customizations. In this post, I’ll outline the most significant concerns, along with recommendations for next steps.

This post has two audiences: authors of publicly available plugins and developers of client sites.

I’ve just completed a scan of all the plugins on that mention ‘termmeta’ or ‘term_meta’ (and boy, are my arms tired!). The numbers there are promising – it’s a fairly small number of plugins that will be affected, and many of them have just a few active installations. I’ll share the results of my scan at the end of this post.

Of greater concern are customizations that developers have built for clients. I know that many larger dev agencies, and many individual developers, have custom, in-house libraries that they use for client sites, and many of these libraries implement termmeta in one way or another. The best of these libraries will be unaffected by termmeta in core: they use prefixed functions, they store data in wp_options rather than a custom table, they use function_exists() where appropriate, and so on. However, I’m certain that there are many libraries – in use on many, many WordPress sites – that do not adhere to these best practices. Sites using these libraries will react in unexpected ways – some of which involve fatal errors – if preventative steps are not taken by the developers before termmeta is rolled into core. Developers should update their libraries and client deployments as necessary to avoid lost data or site downtime.

The primary reasons for concern, listed in order of severity, are as follows:

  1. Function name clashes. The proposed core implementation introduces a number of new functions likely to be used in third-party termmeta implementations: add_term_meta(), delete_term_meta(), get_term_meta(), update_term_meta(), and update_termmeta_cache(). (See the latest patches on the Trac ticket for details.) Plugin should either use a prefix (eg myplugin_add_term_meta()), wrap the definitions in function_exists() checks, or disable the termmeta portion of the plugin based on a WP version check.
  2. Termmeta table deletion. A number of plugins have been found that DROP $wpdb->termmeta on plugin deactivation. Aside from being bad general practice, this could be extremely bad in the case that $wpdb->termmeta becomes a core table. Plugins should not drop {$wpdb->prefix}termmeta under any circumstances.
  3. Non-matching function signatures. I haven’t found any specific examples of this, but plugins that define their own versions of unprefixed functions (using function_exists(), as described above, should be sure that the signatures match. For example, if your plugin defines get_term_meta( $term_id, $taxonomy, $key = '', $single = false ), it will break when moving to the core implementation, which has the signature get_term_meta( $term_id, $key = '', $single = false ). Plugin authors should double-check that their use of unprefixed _term_meta() functions matches the parameter order and default values described in the proposed core implementation.
  4. Non-matching table schemas. A number of plugins create tables called {$wpdb->prefix}termmeta. Most custom tables that I’ve seen are very close to the proposed core implementation, aside from a shortened index length on the meta_key column, introduced throughout core in 4.2. In fact, all implementations I’ve seen are close enough that it’s likely that core will be able to continue to use the tables, leaving data intact. However, if there are significant mismatches – for example, different field names – it will cause serious problems. Plugin author should verify that tables called {$wpdb->prefix}termmeta have a compatible schema with the core implementation.

Here’s a list of the plugins I identified from that will be affected by core termmeta (sorted most popular first). All of these plugins violate at least one of the maxims above. A few of them are OK except for a mismatched meta_key index the termmeta table; the current plan is for core to take care of this index automatically on upgrade. Most of the remaining violations have to do with unprefixed function names. If your plugin is listed below, you are strongly urged to put out an update as soon as possible that addresses the concerns described above. (Some of the plugins are very old, and may be inactive and/or unmaintained. In most cases, they should still be updated, in case of legacy sites.) Don’t hesitate to contact me, in the comments or privately, if you need more details about how a specific plugin in the list below will be affected.

It’s looking likely that termmeta will be introduced in WordPress 4.4 (or perhaps 4.5). The time to act is now. Be a good Citizen of the Internet, and fix your plugins sur-le-champ.

#4-4, #roadmaps, #taxonomy