HowTo: Upgrade Notification for WordPress Plugins

Notify your users!#

Sometimes, your WordPress plugin will have a major release which may causes groundbreaking API changes.

In the past, WordPress displays the “Upgrade Notice” section from readme.txt directly to the users but it seems currently broken – i’ve got no notification for any plugin in the last few month. Therefore i’ve carried out some investigations of the WordPress sourcecode to find an easy solution for plugin developers.

This tutorial gives you the ability to add arbitrary notifications to the user based on the “Upgrade Notice” section.

Sneak Preview#

Example Upgrade Section#

## Upgrade Notice ##

### 2.6 ###
Renamed the EnlighterJS files to `EnlighterJS.min.css` and `EnlighterJS.min.js`. In case you have applied custom modifications these changes may broke your setup and you need to change it!
Added [EnlighterJS v2.5](https://enlighterjs.andidittrich.de/) with some optimization.

### 2.4 ###
Removed WordPress 3.8 Visual Editor compatibility - Enlighter now requires WordPress >= 3.9 including TinyMCE 4

### 2.2 ###
Full Visual-Editor (TinyMCE4) Integration including codeblock-settings (WordPress >= 3.9 required)

 

Workaround using the Changelog#

As a current workaround you can add some text in top of your changelog. It’s simple but requires a user interaction: you have to clock on the “View version xxx details” link. Most professional users will do this and test plugin upgrades in their development/staging environment.

The big problem are beginners or better say “unexperienced user” which just invoke the update and hope “it will work”. As a plugin developer, you should take care of such people.

Changelog Example#

Not elegant but simple and convenient

 

The silver bullet#

Imagine, you can show your upgrade notification directly below the update notice of the admin plugin page like in previous WordPress versions! This requires are special action hook which gives you the ability to add content to the plugin update notice.

Plugin Page Notification#

Of course, that’s the perfect location to display important upgrade notifications/warnings!

 

Magic action hook#

The required action hook is called in the end of of wp_plugin_update_row() located in wp-admin/includes/update.php. It gives you the ability to append arbitrary HTML content into the notification row. It tooks some time of research to locate the required hook within the WordPress sourcecode. For better understanding of the available parameters, here is a small code-snippet:

/**
 * Fires at the end of the update message container in each
 * row of the plugins list table.
 *
 * The dynamic portion of the hook name, `$file`, refers to the path
 * of the plugin's primary file relative to the plugins directory.
 *
 * @since 2.8.0
 *
 * @param array $plugin_data {
 *     An array of plugin metadata.
 *
 *     @type string $name         The human-readable name of the plugin.
 *     @type string $plugin_uri   Plugin URI.
 *     @type string $version      Plugin version.
 *     @type string $description  Plugin description.
 *     @type string $author       Plugin author.
 *     @type string $author_uri   Plugin author URI.
 *     @type string $text_domain  Plugin text domain.
 *     @type string $domain_path  Relative path to the plugin's .mo file(s).
 *     @type bool   $network      Whether the plugin can only be activated network wide.
 *     @type string $title        The human-readable title of the plugin.
 *     @type string $author_name  Plugin author's name.
 *     @type bool   $update       Whether there's an available update. Default null.
 * }
 * @param array $r {
 *     An array of metadata about the available plugin update.
 *
 *     @type int    $id           Plugin ID.
 *     @type string $slug         Plugin slug.
 *     @type string $new_version  New plugin version.
 *     @type string $url          Plugin URL.
 *     @type string $package      Plugin update package URL.
 * }
 */
do_action( "in_plugin_update_message-{$file}", $plugin_data, $r );

Available Plugin Data#

The available data looks like this. And of course – HERE – you can find the upgrade notice from your readme.txt file! A closer look into the comments of the code snippet atop don’t let you find the required key “upgrade notice” – it’s an undocumented feature.

Im currently not sure why the $plugin_data array contains also the available plugin update data from $r – it’s strange because it’s redundant and some extra code is used to grab the $r data…but … it’s WordPress … there are many strange and incoherent parts in the sourcecode. Therefore i recommended to use the $r variable to grab the wanted data!

$plugin_data(
    [id] => 22006
    [slug] => cryptex
    [plugin] => cryptex/Cryptex.php
    [new_version] => 5.0
    [url] => https://wordpress.org/plugins/cryptex/
    [package] => https://downloads.wordpress.org/plugin/cryptex.5.0.zip
    [upgrade_notice] => A new Javascript decoder is used - this will break custom user modifications! Please test it before upgrading
    [Name] => Cryptex - E-Mail Address Protection
    [PluginURI] => http://andidittrich.com/go/cryptex
    [Version] => 4.0
    [Description] => Advanced Graphical EMail Obfuscator which provides image based email address protection using wordpress shortcode and integrated encryption/decryption of addresses
    [Author] => Andi Dittrich
    [AuthorURI] => http://andidittrich.com
    [TextDomain] => 
    [DomainPath] => 
    [Network] => 
    [Title] => Cryptex - E-Mail Address Protection
    [AuthorName] => Andi Dittrich
    [update] => 1
)
$r(
    [id] => 22006
    [slug] => cryptex
    [plugin] => cryptex/Cryptex.php
    [new_version] => 5.0
    [url] => https://wordpress.org/plugins/cryptex/
    [package] => https://downloads.wordpress.org/plugin/cryptex.5.0.zip
    [upgrade_notice] => A new Javascript decoder is used - this will break custom user modifications! Please test it before upgrading
)

Add the Message#

Adding the message is quiet easy. The plugin specific action hook contains of the prefix in_plugin_update_message- followed by your plugin main file including the directory. Within the callback function you can output arbitrary HTML including the upgrade message.

I’ve added some basic styling following the WordPress standard theme colors. For security reasons, don’t forget to add the esc_html function to escape special characters.

// add plugin upgrade notification
add_action('in_plugin_update_message-cryptex/Cryptex.php', 'showUpgradeNotification', 10, 2);

function showUpgradeNotification($currentPluginMetadata, $newPluginMetadata){
   // check "upgrade_notice"
   if (isset($newPluginMetadata->upgrade_notice) && strlen(trim($newPluginMetadata->upgrade_notice)) > 0){
        echo '<p style="background-color: #d54e21; padding: 10px; color: #f9f9f9; margin-top: 10px"><strong>Important Upgrade Notice:</strong> ';
        echo esc_html($newPluginMetadata->upgrade_notice), '</p>';
   }
}

The Result#

Looks perfect or do you like other style ? Feel free to change it. And keep in mind that you need 2 plugin releases until it becomes visible to end users!

Postface#

It’s very weird that’s the Upgrade Notice is missing in the current version and that the required array-key “upgrade_notice” is undocumented. Something must totally gone wrong.

I hope that these feature will return to the core or the solution above will adopted.