Those who have worked in object-oriented programming languages are likely familiar with namespacing and the benefits they provide when organizing a project. Unfortunately, namespaces in WordPress aren’t something that I’ve seen as much as in projects I’ve seen elsewhere.

Namespaces in WordPress: File Organization

And when I say “namespaces in WordPress,” I’m not talking about WordPress core. I’m talking about WordPress plugins. I think there are a variety of reasons developers don’t use namespaces (and may I’ll talk about those later); however, I’ve gotten curious about those who do use namespaces in their projects.

Specifically, I’ve been interested in the conventions that people follow, how they map their files to their namespaces, and so on.

Though there’s likely variation in some of the things we do, I think making sure our files map to a particular directory structure is helpful when dealing with projects (especially large projects).

Namespaces in WordPress

Nothing in this post assumes you use namespaces, but to make sure you know the definition off of which I’m working here’s the definition from the PHP manual:

PHP Namespaces provide a way in which to group related classes, interfaces, functions and constants.

Yeah, it’s fun to take a more nuanced approach and discuss just how far we should take this idea. But that’s for a face-to-face conversation with a fellow developer over coffee at a conference, right?

Though I’ve not always used namespaces in WordPress for many of my public projects, I do for those I work on for clients (and I’ll talk about this more in just a bit). And the more I’ve done this, the more I’m a fan of making sure that the namespaces also match the directory structure.

Directories and Namespaces

Sometimes, developers will refer to namespaces as “virtual paths” which assumes the file organization is the physical path. That’s yet another opportunity to be pedantic, but for the sake of conversation, I think it’s important to have that distinction.

For me, I like to organize my files in the project directory following the same hierarchy as the namespaces defined in the code.

Namespaces in WordPress: Project Files

This means that if a class is in the Acme_Project\Admin namespace, then I can find the file in the acme-project\admin directory.

Similarly, if I’m working with a file that renders a page in the WordPress administration area and it’s in the admin-project\admin\views directory, then it’s namespace should map to Acme_Project\Admin\Views.

This Isn’t To Scale

The example given is pretty simple (maybe it’s too simple?), but the benefits come when working on a large project with a lot of files, a lot of directories, and a lot of moving pieces.

It helps to have a convention that maps the project’s organization on disk to the project’s organization in code (and this is particularly useful when debugging).

If it’s something that’s defined from the outset, you almost intuitively know where to place the classes in the project as you work on the codebase.