7 Cool, Undocumented WordPress Functions

by on May 28, 2011

Recently, I was working on a plugin that needed to extract the first and last names of the site admin on which the plugin was activated. I was fairly confident that I'd have to query the database to extract the information, cross-referencing tables.

However, I discovered a new, robust WordPress 3.1 function, get_users() that can be used to gather the needed data. After coding a wrapper around it, I then discovered three older functions (one undocumented) that get this information much easier. We'll discuss those functions and their usage in an upcoming article.

But, for now, this quest reminded me of some other useful, undocumented WordPress functions. Let's take a look…

number_format_i18n

location: wp-includes/functions.php

The number_format_i18n() function has been around for a while … so it's surprising that it's still not officially documented. It's similar to the PHP function number_format(), formatting a number with grouped thousands. However, this WordPress function automatically formats the number with the correct locale thousands separator. The first parameter is the number; the optional second parameter is the decimal place precision. In case you're wondering, “i18n” is shorthand for “internationalization” … there are 18 characters between the “i” and the “n”.

Interestingly, a similar function for dates, date_i18n(), is documented.

Here's an example usage:

Code: PHP (plus WordPress)number_format_i18n()

$nbr_fmt = number_format_i18n(1234567.345, 2);
echo '</br>' . $nbr_fmt . '<br/>';
// output in America is: 1,234,567.35

 

size_format

location: wp-includes/functions.php

The size_format() function converts a number of bytes to largest unit it will fit into … TB, GB, MB, kB, or B. The first parameter is the number of bytes. And, the optional second parameter is the number of decimal places for the output.

Here are a couple of examples:

Code: PHP (plus WordPress)size_format()

$sz_fmt = size_format(1234567, 2);
echo '</br>' . $sz_fmt . '<br/>';
// output is: 1.18 MB
 
$sz_fmt = size_format(12345, 1);
echo '</br>' . $sz_fmt . '<br/>';
// output is: 12.1 kB

 

normalize_whitespace

location: wp-includes/formatting.php

The normalize_whitespace() function converts whitespace in a string (tabs and linefeeds) to blank spaces. Then, it converts all concatenated blank spaces into a single space.

Here's an example usage:

Code: PHP (plus WordPress)normalize_whitespace()

$test1 = "now \nis the\t\ttime for all  good  men to...";
$test2 = normalize_whitespace($test1);
// test2 is: "now is the time for all good men to..."

 

wp_count_terms

location: wp-includes/taxonomy.php

The wp_count_terms() function returns the quantity of terms in a specified taxonomy. As demonstrated by these examples, it's useful for site stats calculations. Here, we use the three default taxonomies.

Code: PHP (plus WordPress)wp_count_terms()

echo wp_count_terms('post_tag') . '<br/>'; // # of blog tags
echo wp_count_terms('category') . '<br/>'; // # of blog categories
echo wp_count_terms('link_category') . '<br/>'; // # of blogroll link categories

 

screen_icon

location: wp-admin/includes/template.php

The screen_icon() function can be used with plugins and themes. It displays one of 12 icons (32×32) from a css sprite image (/wp-admin/images/icons32-vs.png).

Each icon represents a major section of the Dashboard menu system. The function takes one parameter, a slug that identifies the specific icon to use. And … you guessed it … these 12 slug names are not documented either.

But … we dug through the code to get the data. Here are the slugs and the icon that each displays. The associated files are in the wp-admin folder.


Slug Name Description File Association
'edit' push pin icon (as with “Posts”) edit.php
'edit-comments' speech bubble icon (as with “Comments”) edit-comments.php
'edit-pages' pages icon (as with “Pages”) edit.php?post_type=page
'link' link icon (as with “Links”) link-manager.php
'index' house icon (as with “Dashboard”) index.php
'ms-admin' keys icon (as with “Network -> Sites”) network/sites.php
'options-general' sliders icon (as with “Settings”) options-general.php
'plugins' plug icon (as with “Plugins”) plugins.php
'themes' properties icon (as with “Appearance”) themes.php
'tools' (or 'admin') tools icon (as with “Tools”) tools.php
'upload' media icon (as with “Media”) upload.php
'users' people icon (as with “Users”) users.php

plugin_dir_url and plugin_dir_path

location: wp-includes/plugin.php

When developing plugins, it's often necessary to obtain either their path or url … plugin_dir_url() and plugin_dir_path() help obtain this information.

Oddly … the related functions plugins_url() and plugin_basename() are documented.

Code: PHP (plus WordPress)

$file = dirname(__FILE__) . '/this-plugin-file.php';
// result like: /home/mysite/public_html/wp-content/plugins/my-plugin-folder/this-plugin-file.php
$plugin_url = plugin_dir_url($file);
// result like: http://mysite.com/wp-content/plugins/my-plugin-folder/
$plugin_path = plugin_dir_path($file);
// result like: /home/mysite/public_html/wp-content/plugins/my-plugin-folder/

If the plugin you're using this code in happens to be in a subfolder of the plugin folder (such as admin or php), you'd have to make a minor change in order to get the root folder for your plugin.

In this case use dirname(dirname(__FILE__)) instead of dirname(__FILE__). Also, note that both of these functions DO return the trailing backslash.

 

Share This Article: “7 Cool, Undocumented WordPress Functions”

(Also Available: Press CTRL+D to Bookmark this Page)

Comments

Share Your Thoughts  4 Responses to “7 Cool, Undocumented WordPress Functions”
  1. 1
    Antoine says:

    Bonnes découvertes. Please post others if you find them.

  2. 2
    Bristol says:

    It seems like WP would eventually document these functions. Maybe your article will be a reminder.

  3. 3
    Jim Donahey says:

    I’ve studied several of your detailed articles including this one on undocumented wp functions. You have a wealth of good snippets here! Best wishes for continued growth.

  4. 4

Share Your Thoughts

(Some editor features are restricted unless you're logged in.)

(When replying to a specific comment, your browser may require Shift+Enter instead of just Enter.)


(get a gravatar)


Notify me of followup comments via e-mail. You can also subscribe without commenting.