Debugging is one of the most important stage during the development of an application. It can be long, tedious and exhausting as it often requires reverse-engineering mechanism, which means reassembling the source code rather than unwinding it in a logical sense. This process requires more concentration and resources than typical coding.
In this guide we’ll learn how to set up a favorable environment in order to make it simpler and more bearable, following different steps:
We can never stress this enough: Backup your website. A good developer is a paranoid developer, because even a tiny change can have unpredicable consequences on other parts of the code.
Most of hosting providers provide a built-in backup solution. If that’s not your case, you can use the great Duplicator plugin. It is free and it will let you backup your website and migrate it on another server or your local environment with an easy installation process.
Some hosting solutions provide an easy staging migration tool. This feature will clone your website on a private URL, allowing developers to debug or make some tests. Please refer to your hosting provider documentation or contact its support for more information.
A local development environment is a web server that is installed on your computer. It will run your website just like a normal hosting provider, but the website will be only available to you. To setup such environment, we strongly recommend Laragon for Windows users.
This free application let you setup a fully-fleshed local environment which comes with dozen of handy features such as: Apache, PHP, version selector, PHPMyAdmin, Mailcatcher, nginx/memcache/redis services, NodeJS, local SSL support, Logs Viewer and more! For Mac users, MAMP is an excellent alternative.
While using a staging environment is fast and easy, having a proper local environment on your computer has some great advantages. To name a few: you have direct access to your files & database which means you don’t have to deal with FTP files/transfert, database access or rely on your Internet connection to test your code.
This removes a lot of hassle, since you can use your favorite code editor to edit your files, search specific terms within your source code etc. The downside is that you can’t easily share your environment with a third-party user or migrate from the development environment to production in one-click.
Once your website is installed on your development environment, you can enable the WP Debug mode using the following code in the wp-config.php file, right before the “Happy publishing” comment:
define('WP_DEBUG', true); // enable debug
define('WP_DEBUG_LOG', true); // enable error logs
define('WP_DEBUG_DISPLAY', false); // disable errors on screen
/* That's all, stop editing! Happy publishing. */Settings are pretty straight forward:
WP_DEBUG enable the usage of the following settingsWP_DEBUG_LOG tells WordPress to log errors in the file: /wp-content/debug.logWP_DEBUG_DISPLAY as false tells WordPress to hide errors on screenThat last setting is important because errors displayed on screen may break important websites features such as redirections.
Note: On staging environment, some hosting providers will bypass the default log file location and force errors to be logged somewhere else on your server. If you don’t see the default debug.log file, please contact your hosting support for further information.
If you have to debug JS errors, it is recommended to enable the SCRIPT_DEBUG constant in the wp-config.php file:
define('SCRIPT_DEBUG', true); // enable JS debug
/* That's all, stop editing! Happy publishing. */This constant tells WordPress to load unminified version of JavaScript files. Which means that instead of having hard to read errors in console such as:
Uncaught t ReferenceError not defined // function name: t
at script.min.js?ver=1.0:1:1557 // line 1, character 1557The console will display a more precise location instead:
Uncaught myFunction ReferenceError not defined // function name: myFunction
at script.js?ver=1.0:366:30 // line 366, character 30Now that your WordPress logs errors in a debug file, you can enjoy a nice feature which let you see new errors on-live, while browsing your website. This is particulary useful if you have warnings/errors that are only triggered in specific use case.
We recommend TailBlazer App for Windows users (which is bundled within Laragon). It will let you choose your debug file, and instantly watch errors.
Otherwise, you can run this command to watch a file in-live:
tail -f "C:/local/www/website.dev/wp-content/debug.log"You can also run the same command using your server SSH access on your staging environment:
tail -f "etc/www/website.com/wp-content/debug.log"Now you have a comfortable environment, you can actually debug your code. The most basic way to log a variable into the debug.log file is to use error_log(). But in this guide, we’ll focus on a derived function which is way more powerful.
ACF comes with a very handy function named acf_log() which lets you log any message/variable/array/object. It is the equivalent of the native PHP error_log() but it supports booleans, array and other complex types.
#Simple log:
acf_log('my message');[24-Oct-2022 17:41:22] my message#Multiple logs:
acf_log('my array', array('test'), 'my message');[25-Oct-2022 22:12:13] my array Array
(
[0] => test
) my message#Within hooks:
add_filter('acf/prepare_field/name=my_field', 'my_prepare_field');
function my_prepare_field($field){
acf_log($field);
return $field;
}[12-Jan-2022 04:31:00 UTC] Array
(
[ID] => 0
[key] => field_61d5cab9b6a3a
[label] => Text
[name] => text
[prefix] => acf
[type] => text
[value] =>
[menu_order] => 2
[instructions] =>
[required] => 0
[id] =>
[class] =>
[conditional_logic] => 0
[parent] => field_61d5cab2b6a39
[wrapper] => Array
(
[width] =>
[class] =>
[id] =>
)
[default_value] =>
[placeholder] =>
[prepend] =>
[append] =>
[maxlength] =>
[acfe_settings] =>
[acfe_validate] =>
[acfe_field_group_condition] => 0
[_name] => text
[_valid] => 1
)When developping or debugging a feature, you’ll often need to know how a small chunk of code is supposed to work, just to make sure the output is correct before going further. For examples when dealing with merged arrays with array_merge() or when doing queries with WP_Query.
You could test these small codes directly in your functions.php file and log the ouput with acf_log() as we’ve seen above. However, this process can be tedious, since you have to edit your file, refresh your browser and finally see the results in the logs.
There is an alternative approach which is called Tinkerwell. This application creates an isolated editor which evaluates your code and displays the result in live.
The beautiful part is that it is working within your local WordPress installation context, which means functions such as get_option('admin_email') or WP_Query() will work and display values from your database.
The counter-part of Tinkerwell for Javascript is called RunJS. It will let you test small JS code the same way, with live preview. There is a downside tho, as there is no way to add jQuery or the ACF JS API at the moment.