Recently I switched from using a class to emulate a namespace in my WordPress plugins to actually using PHP’s namespace, which is available in PHP 5.3.0 or greater. I’m going to demonstrate some things that all my plugins thus far have in common.
1. Create a namespace
Right before your plugin meta data comment, you must lead with your namespace (otherwise PHP will complain):
1 | namespace CompanyName\PluginName; |
namespace CompanyName\PluginName;
I use a master namespace for everything I do (CompanyName
) and a sub-namespace for the specific plugin I’m working on (PluginName
).
2. Define a namespace constant
After the plugin meta data comment I define a constant, in other words, a shortcut to reference my namespace within WordPress hooks. It’s just less to type in the future and I can change my namespace without affecting plugin functionality.
1 | define(__NAMESPACE__ . '\NS', __NAMESPACE__ . '\\'); |
define(__NAMESPACE__ . '\NS', __NAMESPACE__ . '\\');
What this allows me to do is use a constant called NS
to render CompanyName\PluginName\
so that after leading with NS
in a WordPress hook callback, all I need to provide is my function name.
To create additional constants within your namespace, you can do that like so:
1 | define(NS . 'PS', 'plugin-slug'); |
define(NS . 'PS', 'plugin-slug');
3. Use your namespace constant in a WordPress hook
Here is what a function and a hook looks like in a namespaced environment:
1 2 3 4 5 6 7 8 | function initialize_plugin() { } add_action( 'init', NS . 'initialize_plugin' ); |
function initialize_plugin() { } add_action( 'init', NS . 'initialize_plugin' );
It’s really not that much different compared to not using a namespace and it certainly looks a lot cleaner than if you were using a class.
4. Use core WordPress functions
There are times where you need to use WordPress functions like the register_activation_hook
, for example. It’s important to remember to change the namespace back to the global namespace for those functions.
The way to do that is to precede the function with a backslash:
1 | \register_activation_hook(__FILE__, NS . 'register_activation_hook'); |
\register_activation_hook(__FILE__, NS . 'register_activation_hook');
This should get you started and if you have any questions, leave them in the comments below.
Dude I’ve been looking for this all over the place. Well done.
Nice.
Even if it work like that, I would have declared my namespace right before plugin meta data comment.
According to php manual : “A namespace definition is the first statement the PHP interpreter should encounter in a PHP file. The only statement allowed to occur above a namespace declaration is a declare statement, and then again, only if it declares the encoding of the script.”
Good point, Elium. I’ve updated my post to reflect this.
Actually bad point, comments and spaces are not statements…..
Agreed. After reading it again, I believe you are correct. Thanks for flagging that!
Pingback: WordCamp Baltimore 2013: Preventive Development |Rami Abraham
Thanks for the help!
Very nice article. You helped me get on the road.
I REALLY LOVE your trick for creating a spacename constant.
One thing: since comments are not interpreted by the PHP engine you may have comment before the namespace declaration I should think.
I was able to add a comment before the namespace, but like Elium mentioned, PHP’s documentation says:
It comes down to whether a comment is considered code or not.
A little further down, it does narrow it down to a code construct:
At the end of the day, it’s no problem to stay on the cautious side 🙂
instead of creating a namespace constant couldn’t you alias the namespace with the ‘use’ keyword?
http://www.php.net/manual/en/language.namespaces.importing.php
I don’t think so, because when WordPress queues and executes hooks, it would take the namespace and function name literally, i.e., it would have no knowledge of the alias in that context. The constant, on the other hand, provides WordPress with the full namespace. If you get it working though, I’d be interested in seeing how you did it!
Great help, thanks
Thanks! This really cleanes up the code for your plugin. Remove all those ugly prefixes for methods.
Hi.
Thank you for the trick.
I am a beginner.
Why adding
'__NAMESPACE__'
to the constant name ?Why not like so:
define('NS', __NAMESPACE__ . '\\');
?Thank you.
Hi Bruno,
You could do that, but then
NS
would be a global constant. Considering it’s such a general name, I only wanted it to work within the namespace.