Category Archives: Tech Notes

Local Testing & Debugging: wp_mail()

I was recently developing a plugin which, among other things, creates and sends an HTML formatted email using the WordPress function wp_email(). However, I was debugging and testing on a local server which is not setup to send emails.

To get around this I wrote the following simple filter which writes the email to a file on the server which I can open and view with my browser.

function my_wp_mail_filter( $args ) {
    $file_name = '../test_email.html';
    file_put_contents($file_name, '<!DOCTYPE html><html><head><title>Test Email</title><meta charset="UTF-8"></head>');
    file_put_contents($file_name, 'NEW EMAIL from ' . get_bloginfo('name') . '. Created at ' . date("h:i:sa") . '<br><br><br>', FILE_APPEND);
    file_put_contents($file_name, 'Headers: ' . $args['headers'] . '<br><br>', FILE_APPEND);
    file_put_contents($file_name, 'To: ' . $args['to'] . '<br>', FILE_APPEND);
    file_put_contents($file_name, 'Subject: ' . $args['subject'] . '<br>', FILE_APPEND);
    file_put_contents($file_name, $args['message'] . '<br>', FILE_APPEND);
    return false;
} add_filter( 'wp_mail', 'my_wp_mail_filter' );

This filter code goes into the functions.php file of your theme. So now, each time I revise the output HTML email format and content, I can refresh my browser and see the results straightaway.

Debugging WordPress

Enable Debugging

WordPress provides a debug facility that is set up by editing the wp-config.php file in your WordPress directory as follows:

// Turns WordPress debugging on
define('WP_DEBUG', true);

// Tells WordPress to log everything to the /wp-content/debug.log file
define('WP_DEBUG_LOG', true);

// Doesn't force the PHP 'display_errors' variable to be on
define('WP_DEBUG_DISPLAY', false);

// Hides errors from being displayed on-screen
@ini_set('display_errors', 0);

A detailed explanation of debug settings is provided in the WordPress documentation. However, the settings shown above will result in all php errors, notices, and warning being written to the debug.log file in the wp-content directory.

Live Monitor the Debug Log

To monitor the content of the debug.log live in Linux, open a terminal and use the command:

tail -f debug.log

This will display additions to the log file as they occur. To terminate the monitoring press Ctrl+C.

Add your own debug messages to the log

Debugging in this way gets more useful when coupled with the facility to add your own debug messages to the log file. This can be done by adding the following function to the functions.php file in your theme.

function log_msg($message) {
    if ( WP_DEBUG === true ) {
        if ( is_array($message) || is_object($message) ) {
            error_log( print_r($message, true) );
         } else {
            error_log( $message );
         }
     }
}

Now you can use the log_msg($msg) function anywhere within your development code.

Plugin Boilerplate

Why Use Boilerplate?

One of the key issues with Open-Source software is the need for coding standards.  Coding standards help the development community to read and understand each others code and ensure the overall quality and security of the resultant software.

WordPress has a set of published coding standards for WordPress development including developing themes and plugins.  To help plugin developers get started with a new plugin that conforms to these standards, there is Plugin Boilerplate code that can be downloaded.  This provides the overall structure of the plugin code and a framework in which the developer can begin work.  To make it easier to get started with the Plugin Boilerplate there is a site that will generate the boilerplate code using your details and your chosen plugin name.

Boilerplate Download

The download is a zip file containing the plugin folder together with the boilerplate read-me and change-log files.

If you used the boilerplate generator, the plugin folder is given the plugin name you provided.  This folder contains:

If you compress the plugin folder into a zip file, you can add the plugin to WordPress from the Dashboard Plugin page using the Add New – Upload Plugin buttons.  This will install the plugin which can then be activated.  At this point your plugin does absolutely nothing!