Navigating WordPress source code

If you really want to know how WordPress works, if you want to know what you can do with it and what you can’t, if you want to understand how to solve your problems with WordPress, there is one thing that you absolutely have to do. No matter how many plugins you play with. No matter how many themes you install. No matter how many tips and tricks you read about. You have to look inside WordPress. Spend some time with its source code.

But not to worry! I probably made it sound much more scary than it is. In this post, we’ll look at a few ways of how to get familiar with WordPress source code and what resources are out there to help us in the process.

First of all, WordPress source code is quite easy to get. It’s an open source application, so all you have to do to get the code is simply download it from the web site. Here, you have it. Done.

This is one of the good things about open source software. You don’t have to pay any royalties, or fill in any lengthy forms, or sign any non-disclosure agreements (NDAs) to get the sources.
Now that you have the code, what do you do with it? Sure, experienced hackers will find there way around it. But if it’s your first application to examine, or if you just don’t have the slightest idea of where to start, let’s take a first few steps together.

Another good thing about WordPress is that it is a web application. Web applications are much easier to study, because there is a correlation of source code with URLs that you access with your browser.

You’ll need two windows open side by side. Your browser in one window, and file manager (FTP program or local filesystem explorer) in another window. Point your filesystem exporer to the folder with WordPress installation and navigate your browser to the URL of your WordPress web site. If you see your web site at http://yourserver.com/blog/ and you have your WordPress installed in a directory /blog/ on your web host, you have everything in sync.

We start with index.php . This is the file which is executed if no other file is specified in the URL. Now you can open index.php in your favourite text editor and see what it does. It’s a short one. It defines a constant, and calls upon another file – wp-blog-header.php . Open that one, and you’ll see that does some things and than calls upon other files. And so on, and so forth, until everything needed to display a page for you is done.

At first, it will take you much longer to trace the whole process, because you don’t have the knowledge of how things are done and what actually needs to be done by WordPress. But slowly-slowly, you’ll learn the workings and will be able to open just that one file that you are interested in.

There are many files in your WordPress folder. And you can call any one of them in your browser. In most of the cases, you won’t see much, as these files are designed to be called as parts of other files, not directly. But with some luck and persistence you can discover something useful. Like the wp-admin/options.php file that I mentioned the other day.

Tracing through the source code can be fun, but it’s not something that we want to start with (although it appears we did). For starters, we want to have some overview of the system. Which directories are there, which files, and what they do. Things like that.

Of course, most of the directories and files are named so that you can get a rough idea of their purpose. For example, I don’t even have to look inside the file called wp-admin/import/livejournal.php to guess what it does. I’d bet you money that it handles the import of data from LiveJournal and into WordPress. And once I know about this file, I can quickly guess which other systems can WordPress import from. Because there are blogger.php, textpattern.php, and a few others in the same wp-admin/import/ directory.

There are a few resources online that can save us a lot of time in this process. Here are a few that I found helpful. If you know of any others, please let us all know in the comments.

The PHP Classes and Functions of WordPress 2.2 – this is the best overview of WordPress source code that I came across so far. There you’ll see a list of all files in your WordPress installation, with a list of PHP classes and functions defined in each file. And it’s all on one page. So, by just scrolling through that list a couple of times and reading the names of files, classes, and functions, you’ll have a good idea of WordPress source code organization. It’ll also come handly later, when you know what you are looking for, but don’t remember where it is (a function definition for example).

Hyperlinked WordPress Source Code – (Update: new link, thanks to Aaron)this is pretty much the same as WordPress source that you have, but much easier to navigate around. You can see included files by simply clicking on their names in the source code. There are useful summaries, which show you where from a file is included, and things like that.

WordPress Hooks – this is an attempt to document all WordPress hooks. Even if the documentation is missing for many of the listed hooks, the resource is still helpful. Once you know the hook exists and how it’s called, it’s easy to find it in the source code and see how it works.

WordPress Codex – this is WordPress documentation project. It covers grounds for any type of WordPress user – a blogger, a theme designer, a plugin developer, an administrator… It has plenty of useful information and explanations of how different parts of WordPress work and where to look for things in the source code. One thing that could have been better about Codex, is its search facility, but we already saw how to overcome it in this post.

PHP Manual – (Update: how did I manage to leave it out? Kudos to Viper007Bond). WordPress is written in PHP, so a functional reference for this language is something you’d need to have nearby. Not only will it tell you what a function does and which parameters it accepts, but it will also provide code examples of how the function can be used in different ways, as well as alternative approaches to solving similar problems.

With these tools you have all you need to get into the heart of WordPress and see what makes it beat.