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 
13 responses
As PHP 5.2 is EOL the WP community could just push to go forward and require a maintained PHP version. Then we could also use namespaces, traits and a lot of other nice features.
Reblogged this on Joan on WordPress.
Another Issue – what if two developers decide to name their theme Geen Hills. In that case prefixing as you suggest would /could still cause naming collisions. Wouldn’t a better practice be to add a company or developer prefix as well. So that If I develop a Gren Hills theme I use a prefix dl_green_hills and John Smith uses something like js_green_hills… or better… I prefix my WP code with sw0929_ it’s not too likely there will be a collision with that type of prefixing…
As @Khromov pointed out, there’s only one theme activate at a particular time, so name collisions between themes should not be an issue.
I agree with you though that adding a unique personal prefix is a good idea, particularly if you are developing a plugin. So in that case it would be personal_prefix_plugin_slug_function_name().
I would suggest putting everything in a class as opposed to prefixing. That way you can, for example create the class My_Plugin and create static methods inside that can be called as:
My_Plugin::output();
It’s not a replacement for namespaces, but it makes issues with duplicate function names disappear, you just have to make sure you name your class something unique.
I noticed neither _s, nor the default themes implement or encourage prefixing CSS classes (sort of a must for larger projects). Is there any specific reason why not?
Themes are what controls the front end, so CSS classes do not need to be prefixed.
I agree though with @Khromov that plugins absolutely need to prefix their CSS IDs and classes to avoid breaking theme styles.
@Khromov @Fränk Agreed that in plugins CSS prefixing should be a no-brainer.
That might be true for smaller projects whereas for larger sites or platforms some form of CSS namespacing/prefixing (BEM, OOCSS et al) is more or less required regarding maintainability. Just wanted to catch a comment if that’s in any form a case for themes distributed via wordpress.org. It doesn’t seemed to be (here and in general) which would validate the conclusion themes distributed via the repo generally are meant to be used on smaller/private sites only?
@Caspar
There is nothing stopping you from using OOCSS and preprocessors such as LESS or SASS. Themes on WP.org are contributed by the community, which mostly consists of people running personal sites and working with SMB:s. But I want to point out that there is no inherit flaw in using “vanilla” CSS for simple sites.
If you want to maintain a project that you know will span many hundreds of man hour, may I suggest starting with a starter theme. I recommend Roots: http://roots.io/starter-theme/
You will be able to utilize Grunt for building and managing assets, and it’s built on Bootstrap 3 so it’s easy to build complex layouts.
@Caspar
Themes are special – you only have one of them activated at a time, so they don’t have to be prefixed. Plugins that employ frontend CSS should use prefixes though.
are its different between Prefixing and WordPress Codex ?
Not all code samples in the Codex are correctly prefixed, they should be though.
Prefixing is very helpful. however not all plugin developers employ frontend CSS should use prefixes though. If we use prefixing in along with these plugins then definitely the prefixed theme would break.