An important best practice when coding a WordPress theme or plugin is correct prefixing.
In this post, we’ll look at:
- Why prefixing is needed in PHP.
- Why prefixing is needed in WordPress specifically.
- How to prefix properly in your code.
Prefixing in PHP
Programming uses the concept of namespaces. It’s an abstract concept that can be explained as a type of container that contains all your code.
In PHP, all functions, classes, interfaces, constants and variables defined outside of functions and methods live by default in the global namespace.
This means that the names you give to these code constructs have to be unique.
Consider this code:
function output() {
echo 'this';
}
function output() {
echo 'that';
}
If you run this code (with error reporting enabled), you will get the following error:
Fatal error: Cannot redeclare output() (previously declared in /htdocs/prefixing-post.php:5) in /htdocs/prefixing-post.php:5 on line 10.
Although the functions are not identical, their names are, which creates a conflict. You could simply rename them, and you would be fine:
function output_this() {
echo 'this';
}
function output_that() {
echo 'that';
}
While this code runs without errors, the problem is that function names often aren’t unique. Imagine you’re writing software for blogging called Awesome Blogging. In this program you have an output() function that prints the page content.
Everything works fine until you include an external library to handle RSS feeds named Cool RSS. By chance, this code also includes a function named output() to print the RSS feed. Your program is now broken!
This is why it’s an established practice to add a prefix to all functions in a specific piece of code to avoid naming conflicts. In our example above, the first function would be named awesome_blogging_output() and the second one cool_rss_output(). No more conflicts!
You can imagine that prefixing all functions and classes and interfaces as well as constants and variables with global scope can become pretty tedious. This is why PHP introduced a namespaces feature with PHP 5.3.0, which allows you to create your own namespaces without the need for prefixing. Since WordPress currently only requires PHP 5.2.4, though, we can’t yet use this new PHP feature.
Prefixing in WordPress
Prefixing is important in WordPress plugins and themes, because WordPress Core itself does not consistently use prefixes. As of WordPress version 4.0, there are nearly 4950 functions in the Core codebase alone. Some functions and classes in WordPress Core use a wp_ or WP_ prefix, but not all of them. Since this doesn’t even take into account all existing plugins and themes, the potential for a name collision is high.
Prefixing in WordPress Themes
For themes, anything specific to the theme living in the global namespace or stored in the database should be prefixed.
This includes:
- functions
- classes
- actions and filters
- global variables
- database entries such as options and post meta
The prefix for these elements should correspond to the theme slug, which in turn should match the theme’s lowercase name, without any spaces or special characters. For functions, classes and global variables, the underscore character should be used. For actions and filters or database entries, the dash character can be used as a separator.
For example, if your theme name is Green Hills, then all functions, classes and global variables would be prefixed with green_hills_. Hooks and database entries would use green-hills- as a prefix.
An Important Best Practice
As we’ve seen in this tutorial, name collisions can result in PHP fatal errors that break entire sites. Proper prefixing lets us avoid these disasters before they happen.
If you have any questions, feel free to leave a comment. Happy theming!
ThemeShaper 