PHP namespaces are a great way to escape any errors that are triggered due to having more than 1 function or class with the same name. In this tutorial, I will show you how to use PHP namespaces in WordPress Plugins.
PHP Namespaces Basics
Before we go into using them in WordPress plugins, I want to tell you about the basics of them. If you’re familiar with them already, you might want to skip this and move to the next section.
There is more to learn about namespaces than what I will tell you here, but this will be just essentials so you can follow my tutorial. If you want to learn everything about PHP namespaces, you can learn it here.
When coding with namespaces, just picture them in your mind as if you are working with folders or categories. Each namespace is a folder, each sub-namespace is another folder inside that one.
Define them on each file on the first lines
That is the first rule that you need to know. If you try to process any class, function or even HTML before the defined namespace, you will get an error.
<?php /** * This is a comment on the file to define what is it about. * This comment can be before or after the namespace. */ namespace My_Plugin;
With this definition, every function or class that is defined in this file will be considered as part of the namespace
Calling Functions or Classes
When you want to process a function or instantiate a class, you need to be aware of the namespaces. If a function is called in a file that is also under the same namespace, you can call it directly.
<?php namespace My_Plugin; /** * We have a function inside another file that is also under same namespace. */ $users = get_users(); // This function is define in another file under namespace My_Plugin.
Calling external Functions or Classes
If we want to call functions or classes that are outside of our namespace. For example, let’s say we will use the WordPress function
wp_insert_post(). How can we call that under our namespace?
<?php namespace My_Plugin; // This is fine if we don't have a function with the same name under our namespace. $post_id = wp_insert_post(); // This is fine since we are telling to look at the global space. $post_id = \wp_insert_post();
What if we have to call external functions that are also inside their own namespaces? That is almost the same.
<?php namespace My_Plugin; $external_namespaces_function = \Some_Namespace\function_name();
But, again, what if you want to call that function several times in the same file? Typing all that is a bit cumbersome. You can define that you will use that function at the beginning of the file.
<?php namespace My_Plugin; // If you are importing a class, you don't have to type "use class", just "use". use function Some_Namespace\function_name; // Now I can use that function directly $external_namespaces_function = function_name();
What if you have your own function with the same name under the current namespace? You have several approaches.
Approach #1: Just importing the function
<?php namespace My_Plugin; use function Some_Namespace\function_name; // Now I can use that function directly $external_namespaces_function = function_name(); // But I want to call my own function with the same name! $my_function = namespace\function_name();
Approach #2: Using aliases
<?php namespace My_Plugin; use function Some_Namespace\function_name as otherfunc; // Now I can use that function directly $external_namespaces_function = otherfunc(); // Our own function. $my_function = function_name();
Approach #3: Importing the namespace
This is useful if you have external (or yours) sub-namespaces.
<?php namespace My_Plugin; use Some_Namespace\functions; // Now I can use that function. $external_namespaces_function = functions\function_name(); // Our own function. $my_function = function_name();
PHP Namespaces in WordPress Plugins
Such namespaces can be also used in themes of course, but as I focus more on WordPress Plugins, I will talk about that.
For this tutorial, I will have a simple plugin with dummy functions. Those functions will be used to retrieve users from DB or from an API. I will use the same function name
get_users() for both and the namespace will define how the function will retrieve and process the data.
Create a folder for your plugin and then place the next code in the main file of that plugin. It can just be something like
test-plugin/test-plugin.php if you want.
Once you’ve done that, go to the Plugins menu and activate the plugin. If the plugin is activated, you can then easily see if there are any errors. At the beginning of the file, we have defined a namespace
My_Plugin. That means that everything in this file will be considered to be under that namespace.
Folders and Files
Let’s also create the necessary folders and files for this tutorial. As I’ve said before, if we are to think of namespaces as folders, we can also create such folders and organize our code even better.
Since we will have two more namespaces, for database and API functions or classes, we will have two folders
api. Put those folders under the folder
includes. After that, create a file inside the folder
db and name it
Do the same inside the folder
api and also create another file in there. Name it
class-api.php. We will now extend our main class and include all that.
Load our Plugin in a hook
Most of the content is just a showcase of classic usage of PHP namespaces, but this part is a specific one. This one will really show you how to use PHP namespaces in WordPress Plugins. Why? Because we will use WordPress hooks here and.
We will load our plugin inside the action hook
If you look closely, we are passing our function name together with the namespace under which the function
my_plugin_load is defined.
In older PHP, we might had to call the
\add_action since that function is in global space, but in newer PHP, if there is no definition of that function, it will look at the global space for it. If I am wrong here, please correct me in the comments below.
We have loaded our plugin, everything is ready. We need to define our database function that can retrieve the users from the database. Since this is just a showcase of using namespaces, that function is a dummy one. Open
includes/db/functions.php and add this code:
So, what have we done here?
- Defined a
- Defined a function to retrieve the users from database.
If we are to call that function outside of
DB, we would need to call it like
\My_Plugin\DB\get_users() or if we are under
My_Plugin namespace, then we can call it like
DB\get_users(). Neat, right? 🙂
API Functions & Class
includes/api/functions.php and add this code:
Pretty straightforward. It is the same as what we have done for the database functions. We now have the same function name
get_users() but the logic inside that function is different. We are also instantiating an object from
Since this class will be defined under the same namespace
My_Plugin\API, we can call it directly here. Let’s define it now. Open the file
includes/api/class-api.php and add the next code.
Again, this is just a dummy class to show how we could retrieve the users from an API. We are calling directly the WordPress functions because PHP will check the global space for them.
Getting the Users
Those functions are not used at all, anywhere in our code. To see the benefit of defining functions under namespaces, I want to show you a way to get those users from our main file. We will define a method for that. Add the next code to our main class.
We have a helper method
use_api(). This method could define if we are to retrieve the users from the database or the API.
Another neat thing here is that we don’t have to define the usage of functions from the sub-namespaces. We can call them directly by specifying the sub-namespace. That is what we have done by calling them with
Saving the Users from API in Database
What if we want to save all the users from the API inside our database? That is a possible scenario in some solutions. We will define such function inside the
DB sub-namespace because we might have to use several database functions (in a real solution).
That might raise an issue if we don’t know how to call the API functions from the other namespaces and sub-namespaces. But we now know that and let’s see how to do that.
We will use the class
API from our
API sub-namespace, so let’s define that we will use that class at the beginning of
Here is now an example on how to call that
PHP Namespaces in WordPress plugins can help you even with the organization with folders and files. By forcing yourself into using them more, you will force yourself to organize the code and maybe even make the whole architecture of your solution much better.
Even I have yet to start using them more. I plan to refactor all my plugins with namespaces and thus making the code more maintainable.
If you wish to get the whole code in the form of the plugin, I have a file here.