Prefixing

People who are new to WordPress will almost immediately see something that might at first seem confusing — or at least strange. I’m talking about “prefixing.” In WordPress, prefixes are used on many things: function names, class names and even PHP defines. But you might be wondering why.

The main reason is to avoid name collisions. If I’m writing a plugin that modifies the post content, I might use something like the following:

add_filter( 'the_content', 'filter_post_content' );

This seems fine. When I test my code it even works. So the plugin developer might think that everything is fine.

The problem comes when your plugin is used with another plugin that is also using a filter on ‘the_content’ and they just happen to use the same callback function filter_post_content(). Why is this a problem? Because in PHP (and just about every other programming language), you cannot have two functions with the same name. How do you avoid this problem? You use “prefixes.”

Instead of declaring your function as: function filter_post_content( $content ) you need to choose a prefix. Most often, developers choose a prefix that has something to do with their plugin, theme or project. Or maybe their company name. Or the developer’s initials. So if you’re writing a plugin called “Amazingly Useful Plugin”, you might choose a prefix of “aup_“. But this may not be unique enough. There are lots of plugins in the repository and there could still be a conflict. A longer prefix is less likely to be duplicated by someone else so adding your name would help. So a better prefix would be “aupdj_” – for the “Amazingly Useful Plugin by Dave Jesch”.

What needs to be prefixed? Any public name. As mentioned before, function names, classes and defines are all stored in the “global namespace.” Also be sure to prefix any global variables you might use. All global names need prefixes in order to guarantee that you will avoid any collisions with other programmers. So your code might look like the following:

<?php
define( 'AUPDJ_CONSTANT', 'necessary value' );

class AUPDJ_Main_Class
{
    public static function filter_something_here( $filter_value )
    {
        $filter_value .= AUPDJ_CONSTANT;
        return $filter_value;
    }
}

function aupdj_filter_post_content( $content )
{
    global $aupdj_global_value;

    $content = str_replace( 'some text', 'other text', $content ) .
        $aupdj_global_value;
    return $content;
}

You will notice that there is no prefix on the class method filter_something_here(). The prefix isn’t necessary because the class name is already unique. And since all methods declared within a class are unique because they’re within the class, there is no need for more prefixing. Besides, it would just get in the way.

If your plugin is also using some Javascript, any global variables, classes and functions use there will need the same treatment.

Using Namespaces

The PHP languages has implemented a Namespace declaration since version 5.9 in 2009. This affords you another way to avoid collisions. To use a Namespace, the very first line of code (comments are okay) in your file needs to be a Namespace declaration. Something like:

<?php
// declare our namespace
namespace AUPDJ;

function filter_post_content( $content )
{
    // get the title
    $post_title = \get_the_title();
    // modify content
    return $content;
}

\add_filter( 'the_content', 'AUPDJ\filter_post_content' );

Here we’re still using our unique name, AUPDJ. But we’re no longer prefixing the function. Our function name is unique because (hopefully) our Namespace name is unique. You’ll notice a couple things in the above code. First is the use of the \get_the_title(); function call to get the post’s title. Because we declared a Namespace, all function names defined and referenced are considered to be within the Namespace. We could have our own function called get_the_title(). So when we want to use WordPress’s version the function, which is declared in the Root Namespace, we need to prefix the global Namepace version of the function with a backslash which denotes this Root Namespace. The other difference is the name of the callback function that we’re using with the filter. Again, WordPress has the apply_filters() function declared in the root Namespace. That means that it’s running in the Root Namespace. So when providing the name of a callback function, it must be prefixed with your Namespace so that it’s full name is known when referencing it from the Root Namespace.

Which is better? Namespaces or prefixed functions? Well, that depends on a few things. It always depends. My first thought would be – what is the size of your project? If it’s a small plugin that is for a specific site, I would not use Namespaces. Just keep everything in the global space and use a unique prefix. The overhead (code writing and management in this case, not code execution or speed) of using Namespaces on a small project isn’t worth it in my opinion. If you have a bigger project in mind, then Namespaces might be worthwhile. But remember, using Namespaces requires that your function names and class names be prefixed with the Namespace. If you intend on others working with your code and integrating with it, this might cause confusion for developers that may not be as familiar with the Namespace feature of the language. So in this case, you should also consider the audience that will be using your code.

So those are my thoughts on prefixing and keeping your function names from colliding with others. If you have any questions, feel free to write some comments here or submit a question on my contact page and I’ll see if I can help make things clearer.