Tag: deprecated functions

Akismet case study: Maintaining support for legacy versions

Automattic‘s Akismet, the awesome spam-fighting plugin, needs to maintain support for the oldest of WordPress installations. That poses an issue when new APIs are introduced and old APIs are deprecated. I recently patched up the plugin to make it work great with 3.0 while still supporting far older versions. It also fixed a few minor bugs. I’ve sent the patch over to the Akismet team, but there were a few parts to the patch I figured I would share.

if ( !function_exists('esc_url') ) {
	function esc_url( $url ) { return clean_url( $url ); }
}
if ( !function_exists('esc_html') ) {
	function esc_html( $html ) { return wp_specialchars( $html ); }
}
if ( !function_exists('esc_attr') ) {
	function esc_attr( $attr ) { return attribute_escape( $attr ); }
}

There, now go ahead and use esc_url(), esc_html(), and esc_attr() throughout your plugin. Make sure you always check each function individually, even though these were all introduced in the same version — what if another plugin used the same technique? (What I mean by that is, if you just check esc_url() and define esc_html() and esc_url() with it, but another plugin checks esc_html() and that plugin is loaded first, your plugin will cause a fatal error for trying to redeclare esc_html(), because you didn’t check it first.) And, use the 2.8 widget API if possible, because it’s the Right Thing to do:

if ( function_exists( 'wp_register_sidebar_widget' ) && function_exists('wp_register_widget_control') ) {
	wp_register_sidebar_widget( 'akismet', 'Akismet', 'widget_akismet' );
	wp_register_widget_control( 'akismet', 'Akismet', 'widget_akismet_control', array( 'height' => 75 ) );
} else {
	register_sidebar_widget('Akismet', 'widget_akismet', null, 'akismet');
	register_widget_control('Akismet', 'widget_akismet_control', null, 75, 'akismet');
}

It should be noted, of course, that Akismet already employs this technique for other functions. The goal here is to just catch it up to functions introduced in 2.8.

Complete diff available for download here. It also fixed a few notices caused by unset variables and unchecked indexes, and discovered some unreachable code.

Akismet also assumed the $pagenow global would always be set. This is true — except on activation. (See the notes on the Codex page.) WordPress 3.0 also has stricter activation checks now (which I imagine I will cover in a post soon), which thus prevents Akismet from activating when WP_DEBUG is enabled. The $pagenow issue was handled a few days ago in Akismet trunk, so the patch just cleans up deprecated function use and a few minor notices at this point.

Deprecated functions and WP_DEBUG

(Updated June 27, 2010: You may wish to check out my Log Deprecated Notices plugin.)

In every major version, the WordPress developers send functions to the graveyard. Many developers continue to use deprecated functions in their pluigns, or may even begin to use a function after it was already deprecated.

Deprecated functions cannot be relied upon to work efficiently or correctly and may be disabled by default or entirely removed in future versions of WordPress. But really, I would think about it like this: By using them, you’re likely missing out on new features afforded by the new function.

There are various reasons we deprecate functions:

  • We may decide to change or improve how it the function works, but doing so might break backwards compatibility. So we deprecate the old function and come up with a new one.
  • We may rename a function to standardize its name with other functions or to clarify its usage. Developers tend to like APIs standardized as much as possible, as it means we can work faster.
  • We may consolidate functions — for example, the_author_meta($meta) and get_the_author_meta($meta) replaced 25 functions.[1] Yes, 25. And it can return any usermeta field. current_user_can(), likewise, replaced a bunch of functions along the lines of user_can_create_draft() and user_can_edit_post_date(). In another example, we’re consolidating category and tag operations under term/taxonomy operations.
  • We may remove functions that no longer do anything. (Why do we keep a function that doesn’t do anything? If a plugin tries calling a function that no longer exists, you’ll get a fatal error. Also, if a plugin uses the same function name in a later version, the plugin would be incompatible on an old version that has the function.)
  • When merging in WordPress MU in 3.0, we removed dozens of functions, in many cases to merge them with their non-MU counterparts.

We normally don’t deprecate functions when we change front-end terminology, as we trust developers to make the connection, and we’re not nuts enough to rename functions just for the sake of renaming them.

What else do we deprecate?

We also don’t have just deprecated functions. We have deprecated files and, as of 3.0, deprecated function arguments.

Deprecated files: MagpieRSS (wp-includes/rss.php) has not been developed for years, and is deprecated in favor of Simplepie (wp-includes/class-simplepie.php). Most others were files that have been renamed, but we had to keep the old one because they were ones often included directly by plugins. In these cases, the old file includes the new files, so you don’t lose functionality. Deprecated files include:

  • wp-includes/rss-functions.php, now wp-includes/rss.php (also deprecated; use Simplepie)
  • wp-includes/registration-functions.php, now wp-includes/registration.php
  • wp-admin/upgrade-functions.php, now wp-admin/includes/upgrade.php (contains wp_install(), dbDelta(), etc.)
  • wp-admin/admin-functions.php, now wp-admin/includes/admin.php
  • WordPress does not support the legacy my-hacks.php file

Deprecated arguments: (new in 3.0) In nearly all cases, deprecated function arguments no longer have any functionality tied to them and often don’t have alternatives available. If we later add an argument to that function, though, we don’t want to take the spot of an argument that used to be there, in case a plugin developer still tried using the original argument.

Where we keep them

Deprecated files and arguments are scattered throughout core, but we consolidate deprecated functions so developers can reference those files. In 2.9, the file was wp-includes/deprecated.php. In 3.0, we now have five files:

  • wp-includes/deprecated.php — Regular WordPress functions available everywhere.
  • wp-admin/includes/deprecated.php — For WordPress functions only usable in the administration area.
  • wp-includes/ms-deprecated.php — Functions from WordPress MU, loaded only when running multisite.
  • wp-admin/includes/ms-deprecated.php — Functions from WordPress MU only usable in the administration area.
  • wp-includes/pluggable-deprecated.php — Pluggable functions. Because pluggable functions are defined later (so a plugin can override them), we can’t put these in the normal deprecated.php file. Moving them into its own file allows us to lower their profile.

Keeping track of deprecated usage

As of right now in 3.0, we have 131 deprecated functions and 39 deprecated arguments. How should you, a plugin developer, keep up with them all?

define( 'WP_DEBUG', true );

If you’re a plugin or theme developer and you don’t know what the WP_DEBUG is, you’re missing out. (If you do know what it is and you don’t use it during development, you’re crazy.)

The WP_DEBUG constant, which you would define as true in wp-config.php, does two things. First, it tells PHP to report more errors, specifically “notices.” (WordPress normally instructs PHP to only report warnings and fatal errors.)

This means you will see potential problems in your code, such as unchecked indexes (empty() and isset() are your friend) and undefined variables. (You may even find problems in WordPress itself, in which case you should file a bug report.)

Second, WP_DEBUG exposes debug messages generated by WordPress, such as:

  • When a deprecated function or function argument is used, or a deprecated file is included.
  • When user levels are used instead of the roles and capabilities system.
  • When old APIs are utilized instead of new ones, such as the Settings API (register your settings!).

In a nutshell, there’s an entire API devoted to informing you of the best practices and the latest APIs. Here’s two example notices:

Notice: options.php was called with an argument that is deprecated since version 2.7! The “your_option_name” setting is unregistered. Unregistered settings are deprecated. See http://codex.wordpress.org/Settings_API

Notice: get_category_rss_link is deprecated since version 2.5! Use get_category_feed_link() instead.

You can suppress notices if you prefer, by using the WP_DEBUG_LOG and WP_DEBUG_DISPLAY constants (see the inline documentation I wrote here). You can also use hooks and filters in the Deprecated API (view the functions). (To know where functions are being run, you could run a backtrace on one of those hooks, for example.)

Many even run WP_DEBUG on their production websites. Generally, they log it (using either WP_DEBUG_LOG or a server PHP error log) and force the hiding of errors, using:

define( 'WP_DEBUG', true ); // turn on debug mode
define( 'WP_DEBUG_LOG', true ); // log to wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false ); // don't force display_errors to on
ini_set( 'display_errors', 0 ); // hide errors

“But I need to support old versions”

Honestly, I wished you didn’t ask that. But if you must support a legacy version, conditionally check for the new functions and use those if available.

// esc_url() introduced 2.8
$cleaned_url = ( function_exists( 'esc_url' ) )
	? esc_url( $url )
	: clean_url( $url );

 // introduced 2.8
if ( function_exists( 'wp_register_sidebar_widget' ) )
	wp_register_sidebar_widget( 'widget-id', 'My Widget', 'my_widget_callback' );
// introduced 2.2, if you must check
elseif ( function_exists( 'register_sidebar_widget' ) )
	register_sidebar_widget('My Widget', 'my_widget_callback' );

Just remember: friends don’t let friends develop plugins without WP_DEBUG.

[1] These functions were deprecated in favor of get_the_author_meta(): get_author_name(), get_the_author_ID(), get_the_author_aim(), get_the_author_description(), get_the_author_email(), get_the_author_firstname(), get_the_author_icq(), get_the_author_lastname(), get_the_author_login(), get_the_author_msn(), get_the_author_nickname(), get_the_author_url(), get_the_author_yim(). In favor of the_author_meta(): the_author_ID(), the_author_aim(), the_author_description(), the_author_email(), the_author_firstname(), the_author_icq(), the_author_lastname(), the_author_login(), the_author_msn(), the_author_nickname(), the_author_url(), the_author_yim().