In this tutorial, we're going to take a break from writing code and look at what PHP namespaces and autoloaders are, how they work, and why they are beneficial. Then we'll prepare to wrap up this series by implementing them in code.
If you're not caught up with everything we've covered in the series by this point, I recommend going back and reviewing what we've covered thus far. At the very least, review the previous article as it's going to lay the foundation for what we'll be talking about in the next two articles.
Now that you're caught up, you're aware of the plugin we've been working on, what it does, and how it works. Further, you should have a local development environment set up that allows you to work with the source code. If not, here's a quick rundown of everything that you need:
- A local development environment that includes PHP 5.6.20, the Apache web server, and a MySQL database server.
- A directory out of which WordPress 4.6 is being hosted.
- A text editor or IDE of your choice that you're comfortable using for writing a plugin.
- A working knowledge of the WordPress Plugin API.
Assuming you have all of that installed, set up, and ready to go along with the latest version of the plugin, then we're ready to resume our discussion on namespaces, autoloading, and WordPress plugins.
On Namespaces and Autoloading
For those who have worked in other modern programming languages, you may be familiar with the concept of namespaces. But even if you've worked with PHP, it's not likely that you've seen them much, at least in the context of WordPress.
For those of you who haven't heard of them or who have heard of them but haven't used them, that's what this particular article is all about. Specifically, we're going to talk about namespaces and autoloading and then, in the next tutorial, we'll see how it all fits together.
That is, we're going to take the work that we've done with our plugin thus far and then update it so that it uses namespaces and autoloading. This will give you a practical understanding of the concepts as well as a few new tools to add to your development repertoire for when you work on your next project.
What Are Namespaces?
As with most of my tutorials, I like to give the formal definition and then break it down into more conversational terms. The PHP manual defines namespaces like this:
In the broadest definition namespaces are a way of encapsulating items.
That doesn't necessarily help us much, does it? One could argue that classes do the same thing permitting attributes and functions can both be generalized as items. But the manual goes on:
PHP Namespaces provide a way in which to group related classes, interfaces, functions and constants.
That's a bit clearer, right? This means that when we have a group of related classes, we may be grouping them together in the same directory or similar directories on the filesystem, but there's no way to know that by looking at the code.
Namespaces give us the ability to do that.
Think of it this way: Imagine that you have a set of functionality related to working with CSVs.
- Perhaps you have a class that's responsible for reading a CSV file, parsing the contents, and reading the contents into an array.
- Then you have a class that's responsible for taking that array and writing data to the database based on what the array contains.
- After that, there's a class responsible for reading those options whenever a third-party object or another area in the code needs to read the data that was read, parsed, and saved earlier in the project's execution.
All of this functionality should span several classes. Depending on how object-oriented code your solution is, you may also have a set of interfaces that your classes implement. Furthermore, the classes may be organized in a /csv directory but broken down even further into their own subdirectories.
/read/write
Maybe you would opt to organize the structure a bit differently, but to keep the discussion as simple as possible, I thought this would make sense. So perhaps the class interface(s) would reside in the root of the /csv directory, the reader would reside in the /read directory, and the classes responsible for writing the data to the database would reside in the /write directory.
Nothing I've said thus far is out of the ordinary in terms of how we may organize our files. But this is where namespaces come into play.
Specifically, what if we were able to organize our classes so they also mapped to their physical location in the filesystem?
Think of it this way: Let's say your plugin is called Acme CSV, and the classes above are all organized in their directories and subdirectories and so on. What might the namespaces look like for these classes, and how would they be declared within the project?
Take a look at what we'll call the Parser class. This class is located in /csv/read.
<?php
namespace Acme_CSV\CSV\Read;
class Parser {
// Class Implementation
}
And then let's say we have our class that writes data to the database:
<?php
namespace Acme_CSV\CSV\Write;
class Serializer {
// Class Implementation
}
Finally, let's see what the namespace for the class is like that reads data from the database:
<?php
namespace Acme_CSV\CSV\Read;
class Reader {
// Class Implementation
}
Nothing terribly complicated, right? Though the standard above isn't how you have to organize your files, I like to try to map my classes to their location on disk. It makes it easier to refer to them in future work.
At this point, there's really nothing much more to see beyond declaring a type of organization of your classes at the top of their files. But when you begin to incorporate autoloading, this changes.
A Word on Packages and Subpackages
Before we talk about autoloading, though, I want to have a short digression on the @package and @subpackage tags that we're often so used to seeing in file comments.
For example, you've likely seen something like this with respect to our code above:
<?php /** * This is the file comment for the Serializer class. * * @package Acme_CSV * @subpackage Write */
But when you refer to the phpDocumentor documentation, you'll see the following about @subpackage:
This tag is considered deprecated and may be removed in a future version of phpDocumentor. It is recommended to use the @package tag’s ability to provide multiple levels.
So @subpackage is being deprecated, meaning that we likely shouldn't bother using it anymore. What about the @package tag?
The @package tag is used to categorize Structural Elements into logical subdivisions.
The support for multiple-level nesting now resides solely in that tag. Good to know, right? This means the code we see above could be written something like this:
<?php /** * This is the file comment for the Serializer class. * * @package Acme_CSV\Write */
Sure, it's a simple example, but it makes its point. I mention this because @subpackage is yet another tag that we often see in WordPress-based PHP that we need to avoid using if we want to begin adopting newer standards.
What Is Autoloading?
With that said, let's come back to the primary topics at hand. Since we've covered namespaces, let's look at autoloading. According to the PHP manual:
Many developers writing object-oriented applications create one PHP source file per class definition. One of the biggest annoyances is having to write a long list of needed includes at the beginning of each script (one for each class).
This couldn't be stated any better, could it? Still, it doesn't really explain what autoloading is. It just explains the problem it can solve.
In PHP 5, this is no longer necessary ... [it supports loading] classes and interfaces to be automatically loaded if they are currently not defined.
Sounds fantastic, right? But there's a caveat, and we're going to explore it in detail in the next tutorial. But until then, here it is: To gain this functionality, we have to implement a function that knows where to look for files to load and how to parse the directory structure of those files.
It sounds tedious, and it some cases it might be, but if you have a consistent way of organizing your work, your autoloading code can be portable. That is, you can take the function you write, drop it into any PHP-based project, and be ready to go all the same.
But this specific tutorial isn't about writing code. It's about covering the idea behind the concepts of the code that we'll be implementing in the next tutorial.
Why Is Any of This Relevant?
Depending on who you ask, you may view namespaces and autoloading as new to PHP. For some, this is true. For others, they've been working with these two concepts for a while now.
One of the things about WordPress that can hold it back from adopting newer features of PHP is its commitment to backward compatibility. This isn't necessarily a good thing or a bad thing—it's an attribute of the application.
But because WordPress has a minimum version of PHP on which it runs, newer language features aren't always adopted. And when that minimum version is adopted, it takes WordPress-specific developers a little while to begin using these features in their code.
And that's not a bad thing. In short, the developers are keeping pace with the application at the pace at which it matures.
But as WordPress continues to move forward or you have control over the environment in which your project runs, you may be interested in adopting some of the features of the language you didn't previously know existed or you didn't previously know were available.
Namespaces and autoloading are two powerful features of the language that go a long way in making the code more readable, more organized, and even a bit more maintainable. So if you've yet to use them in any of your work in WordPress, especially if you're working with WordPress plugins, then I urge you to consider doing so.
Conclusion
Namespaces give us the ability to organize our code in a way that makes the logical grouping of related classes much easier. Furthermore, autoloading gives our code more readability by reducing the number of include, include_once, require, or require_once statements that we need to use.
This makes the source code that we're writing clearer in that it's focused solely on the logic for which it's responsible, without having to do anything like import files, handle various directory structures, and be aware of more than it should (let alone the developer have to constantly retype everything just so they can access a file).
And for those who like to make sure the structure of their code follows the organizational structure of the files and directories on the disk, it gives us the ability to organize our projects exactly like that.
Even with all of that said, this is just one way and a few advantages of namespaces and autoloading. More advanced topics are covered in the PHP manual and in other open-source projects that I recommend you review if you have time.
In the next tutorial, we'll wrap up this series by applying what we've learned in this tutorial as we introduce namespaces and autoloading to our WordPress plugin. Until then, if you're looking for other WordPress-related material, you can find all of my previous tutorials on my profile page and you can follow me on my blog or on Twitter.
Don't hesitate to leave any outstanding questions you may have about namespaces, autoloading, or WordPress in the form below.
Comments