Add Custom Plugin Update Messages in WordPress

In the dynamic world of WordPress plugin development, ensuring that users are well-informed about updates is crucial. Clear and concise update messages not only help users to know about the updates but also, reduce confusion and support queries. In this blog post, we’ll explore how to add user-friendly plugin update messages in WordPress using the powerful in_plugin_update_message-{file} hook.

This one is the screenshot from the Elementor update message. It has a clear message about the update and direct instructions to users before they push the update button. It will help to reduce the break site (you will have a backup to restore the site if it crashes) after the update and reduce support queries.

Benefits of Custom Update Messages

Custom update messages provide clear and relevant information to users, making the update process smoother and more transparent.

By detailing what’s included in an update, you can better communicate the value of the new version to your users. Informative update messages can answer users’ questions about the update, reducing the need for support intervention.

You can also show the compatibility of third-party dependent plugins like Elementor or WooCommerce do in its update message.

But now the question is, how to add a plugin update message like in the image above?

Add Plugin Update Message for Your Plugin

You can add simple as well as complex plugin update messages for your plugin. To add the update message there is a wordpress hook we are going to use –

do_action( "in_plugin_update_message-{$file}", array $plugin_data, object $response )

You can use this hook to display the update message for your plugin. Below is an example of how to use this hook –

function eramits_plugin_update_message( $plugin_data, $new_data ) {

	if ( isset( $plugin_data['update'] ) && $plugin_data['update'] ) { ?>

		<hr class="eramits-update__separator">
		<div class="eramits-update-message">
			<div class="info-icon">
				<span class="dashicons dashicons-info"></span>
			</div>
			<div>
				<div class="update-title">
					<?php echo esc_html__( 'Please backup before upgrade!', 'eramits' ); ?>
				</div>
				<div class="update-message">
					<?php
					printf(
						/* translators: %1$s Link open tag, %2$s: Link close tag. */
						esc_html__( 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur at ornare ipsum. Pellentesque %1$s tempus pellentesque risus %2$s, a porttitor diam posuere quis. Suspendisse potenti.', 'eramits' ),
						'<a href="https://eramits.com/">',
						'</a>'
					);
					?>
				</div>
			</div>
		</div>

	<?php }
}
add_action( 'in_plugin_update_message-your-plugin/your-plugin.php', 'eramits_plugin_update_message', 10, 2 );

Here you can adjust the condition to display the plugin update message and, it is totally up to you how and when you want to display the update message.

But Wait, What if Multisite Installation?

The above method works well for single-site and multisite installations where the plugin is network-enabled. However, additional code will be necessary to ensure proper functionality if your plugin is installed on a multisite network but only activated on individual sites.

In this scenario, a different hook is used: after_plugin_row_{file}. This After Plugin Row hook allows you to add a new row to the plugin’s table, providing the necessary functionality for multisite installations where the plugin is activated on a site-by-site basis.

do_action( "after_plugin_row_{$plugin_file}", string $plugin_file, array $plugin_data, string $status )

Now by using the above hook, you can add an update message for multisite installation, and below is the example code of how you can do it.

function eramits_ms_plugin_update_message( $file, $plugin ) {
    
    if ( is_multisite() && version_compare( $plugin['Version'], $plugin['new_version'], '<') ) {
        $wp_list_table = _get_list_table( 'WP_Plugins_List_Table' );

        $message = sprintf(
            '<div class="update-message">
                <h4>%s</h4>
                <p>%s</p>
            </div>',
            esc_html__( 'Please backup before upgrade!', 'eramits' ),
            esc_html__( 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur at ornare ipsum. Pellentesque tempus pellentesque risus, a porttitor diam posuere quis. Suspendisse potenti.', 'eramits' )
        );

        printf(
            '<tr class="plugin-update-tr">
                <td colspan="%s" class="plugin-update update-message notice inline notice-warning notice-alt">%s</td>
            </tr>',
            $wp_list_table->get_column_count(),
            $message
        );
    }
}
add_action( 'after_plugin_row_your-plugin/your-plugin.php', 'eramits_ms_plugin_update_message', 10, 2 );

Adjust the code as per your need to display the update message for your custom plugin.

Styling Your Update Messages

To maintain consistency with your plugin’s design, add CSS styles to your plugin’s stylesheet. This ensures that your update messages blend seamlessly with the WordPress admin interface.

Conclusion

Enhancing plugin update messages in WordPress through custom hooks provides you with a powerful tool to improve user communication and site management. By leveraging hooks like in_plugin_update_message and after_plugin_row_{file}, you can display informative messages that guide users through important updates, highlight new features, emphasize the importance of site backup, and avoid potential site crashes.

By following the examples and best practices outlined in this post, you can level up your plugin update notifications, contributing to a smoother, more user-friendly WordPress experience overall.