Skip to content

WordPress Debug Bar Plugin | BlackBox

Here is something that WordPress developers might find very useful. Recently when working with symfony i figured out it would awesome to have debug bar in WordPress, similar like symfony has since version 1.0. After Googling WordPress debug plugin it turned out there was no such solution so i decided to developed one myself.

Here is why you will find it helpful:

  • instantly inspect global variables (GET, POST, COOKIE, SERVER)
  • debug both frontend and admin area
  • executed MySQL queries and time it took to execute each query (useful for finding slow queries)
  • profiler for measuring performance of your plugins and themes
  • errors occurred when loading WordPress page

If you will decide to use the plugin please remember it’s not a perfect solution, it uses some workarounds, but it’s gets the job done, is lightweight and unobstrusive which i think is most important. Here is how it looks:

WordPress Debug Plugin

Basically the debug bar is attached to the top of the browser window. Using “Close Toolbar” you can close it if the plugin is bothering you, however on the next page refresh it will “popup” again until you disable the plugin. Other than “Close Toolbar” there are four other sections. Click on any of them to expand, second click hides expanded information.


Global Variables Dump

As the name says, Globals contains information about global variables. I find it one of the most useful features since i do not have to add print_r($_POST) everytime i want see if variables from the form were sent correctly or at all.

BTW. Syntax highlighting is done using highlight.js library, it highlights 35+ languages and comes with a lot of color schemes i really recommend it if you are looking for syntax highlighting library.


Debug Bar Profiler

Profiler is the one that is using a dirty work around, but let me say in my defence that i have a reason for this. Either way, first, let’s look at how to add new points to profiler to benchmark your code.

Another point is added with the following single line of code:

apply_filters("debug", "My new checkpoint");

Obviously, the second argument should be a name of function to execute, but it’s not. It’s simply a name/title that will be added to the profiler section.The reason i solved it this way is because i wanted to make something plugin-independent. If you disable BlackBox the code will still work so you do not have to worry about removing all the checkpoints from the code.

You probably noticed that by default there are three entries in the profiler. “Profiler Initiated” and “Profiler Stopped” are self explenationary, however “Profiler Noise” is not. “Profiler Noise” is the time that WordPress needs to execute hook, in other words if you measure the time between two checkpoints you need to keep in mind that you need to subs tract “noise” from it.

As for information you will find in profiler, these are: time passed since profiler was started and total memory WordPress was using when checkpoint was reached.


Debug Bar SQLThis is probably most useful feature of all. In SQL tab are listed all executed queries along with time (in milliseconds) it took to executed each of them.

Well actually, not all queries are listed. If the query was not executed using WP_Query object you won’t find it in the list, also if it was executed before BlackBox plugin index.php file was loaded it won’t be on the list as well. Keep this limitations in mind, however it’s very uncommon to to happen and probably might happen only if you are using a plugin created by beginner WordPress developer.


Debug Bar Errors

By default WordPress hides all strict errors, notices and warnings (or even fatal errors), it’s great for production but not really helpful when developing a website or plugin. Therefore in Error tab all errors are listed, if the error is a warning then it’s listed on red, so you can easily notice more important problems.

Notice that each error is listed only once, if the same code is executed twice or more and it raises some kind of problem, then on the list of errors, next to the error type there will be listed number of times error occurred.

Few final words

Currently there is no configuration for the plugin you must use it as is, or modify source code to fit your needs. If you need will find it useful or horrible please let me know in comments what you think and how can i improve the plugin.

Download BlackBox – WordPress Debug Bar

Published inGeneralWordPress


  1. Hi Greg,

    Great little plugin, really handy, just one piece of feedback. In the debug-bar.php file, on lines 21 and 22, instead of using bloginfo(“url”), use bloginfo(“wpurl”). This will ensure the paths are correct for standard and non-standard WP installations (for instance, I install WP in a “wordpress” subdirectory under the root).

    Otherwise, thanks a bunch. Like I said, very handy.

  2. @Dave, thanks i add that.

    @Otto, i had it developed for personal use, before first version of Debug Bar was released. Second i see there are already 4 developers while i prefer to work alone. I hope releasing plugin similar to what’s in repository is not a crime?

  3. Great insight. Thanks for the plugin. I was looking for some directions as to monitor errors.

  4. hi Greg, wonderful plugin!

    is there a way this can work/modified to work outside wordpress??

    i coded a custom cms which is now used in over 150 websites of our clients, i would like to add such debuging facilities to our cms out of the box to help us easily catch things.

    i have recently found an unoptimized sql query taking 2-3 seconds to run, with this i could have caught it from day 1!

  5. -S -S

    I just installed it in WP 3.1 / PHP 5.2 and I’m getting a stream of this:
    Notice: Use of undefined constant E_DEPRECATED – assumed ‘E_DEPRECATED’ in D:\users\barre\Web\\wp_bm\wp-content\plugins\blackbox-debug-bar\application\BlackBox.php on line 131

  6. Thanks man, really great plugin.

    To make it work on wp 2.9 changed line 52 in
    “memory” => memory_get_peak_usage()
    “memory” => ”

  7. i think it’s very useful wp plugin thank you very much.

  8. Hi @all, thanks for comments i will implement all suggestions soon in new version.

    @paris, i am afraid you won’t be able to use it without WP, since it’s highly dependable on WordPress API, however you can probably write your own debug bar, it’s rather simple script.

  9. Have just upgraded to 0.1.1. Could you plz fix it a bit?)
    In admin panel, where we have a list of all the installed plugins, if the BlackBox is active we get 2 #blackbox – one in the bar, another in the list.

    Also have a suggestion. I know its damn bad to use BlackBox on live site. But just in case there is my way to use it.

    Added to css: #blackbox{display:none}
    So an admin can toggle the visibility live via firebug.

    If no dev-plugins are installed – copy&paste this to browser adress bar


    Will work on jQuery enabled themes.

  10. @Dimas, thanks for the suggestions, i think i will actually use IP whitelisting to enable blackbox in the production.

    As for the bug report, i would like to fix it, but i am not sure what you mean by “2 #blackbox” – do you mean two elements with id=”blackbox”?

  11. Exactly.
    There are two elements with same ID on plugins page.
    Just try to enable the plugin and revisit WP plugins list page, you’ll see what I mean)

  12. Ok, thanks for the bug report, that’s fixed in latest version.

  13. Steve Wood Steve Wood

    Hey Greg,
    I just installed your version 0.1.2 and found several spelling and grammatical errors. I also found and corrected a CSS error you had. You’ll notice if you HOVER over the area, it does not change to opacity 1. It stays at 0.9. I also changed the colors from Black to Gray. I personally can’t stand seeing black backgrounds but maybe thats just me…setting the colors to gray makes it much more readable.
    I made some other changes that made the SQL formatting much more readable.
    If you are interested in these changes and errors I corrected, give me a reply back and I can send you a zip file.
    Also…I noticed that “Profiler Initiated” doesn’t seem to do anything. It always reads 0.0000 ms. Can you explain to us what this is supposed to be measuring and how we can use this information? In fact, explain the whole Profiler thing to us. I don’t know if its just me or many other people out there that don’t understand it.

    I think I found another error too. In the ERRORS readout. Instead of displaying Strict (5)….my readout is:

    Looks like maybe a is set too small in the CSS?

  14. Hey, this works great, especially collecting the errors and not outputting them. It’s light and not obtrusive. Like it more than debugbar.

  15. Great plugin!
    Our development team cannot start a project before they upload our plugin!

  16. Joshua Smith Joshua Smith

    Hi Greg,
    This is an excellent plugin! Thank you for sharing it.
    A question – Is there a way to restrict it to a specific user?

  17. Joshua Smith Joshua Smith

    Nevermind… :-)

    The short answer – in Hook.php, I just changed the is_super_admin() test to check for current user’s email address. (I’m on a dev site so I want to see the debug bar even when logged in as a plain ole subscribed member.)

    So I changed this …

    if (is_super_admin()) {
    apply_filters(‘debug’, ‘Profiler Stopped’);
    include_once BLACKBOX_DIR.”/application/debug-bar.php”;

    …. To this ….

    global $current_user;
    $debug_users = array(“”, “”);
    if (in_array($current_user->user_email, $debug_users))
    apply_filters(‘debug’, ‘Profiler Stopped’);
    include_once BLACKBOX_DIR.”/application/debug-bar.php”;

    Long answer – I initially put a get_currentuserinfo() in index.php and tested for email address. This worked fine, but it required me to include(wp-includes/pluggable.php), since pluggable isn’t included until after all the plugins. That wasn’t preferable because if some other plugin was overriding a function in pluggable.php and my plugin loaded before the other plugin, then their override wouldn’t be loaded.

    Anyhoo – not only did it work but this was a great learning exercise, thanks in no small part to a well coded plugin to begin with!


  18. Hello, thanks for making this, it’s great, very useful and better than anything else I could find. No idea why some above comments are being so negative, sad. Keep up the work.

Leave a Reply

Your email address will not be published. Required fields are marked *