WordPress Bits

Hacking WordPress. Keeping the bits together.

Navigating WordPress source code

Posted by Leonid Mamchenkov on August 14, 2007

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.

23 Responses to “Navigating WordPress source code”

  1. Reading source code of scripts like WordPress is actually how I came to learn PHP. I didn’t read a single book — just existing PHP scripts and function lookups in the PHP manual.

    It’s also a really good way to learn coding standards and stuff like that, especially when using a well coded project like WordPress.

    *thumbs up*

  2. Viper007Bond,

    indeed! I somehow managed to omit PHP manual while writing the post. Thanks for the reminder. The post is updated now with this handy link. Of course, I use it myself on the daily basis too. ;)

  3. maki said

    am starting my own site about wordpress themes and this will gonna help me a lot. thanks.

  4. Maki,

    glad to hear that. The more content we have about WordPress, the better. Good luck with your new project. :)

  5. An interactive PHP debugger can be very usefull while exploring WordPress inner workings (and irreplacable when trying to fix bugs).
    Most of the time this requires the creation of a local WordPress installation (I am using XAMMP on WinXP) but this has the added advantage of beeing able to preview/test changes without worrying about causing any problems to the main server.
    Finding an user friendly interactive PHP debugger allowing to step through a “live session” in WordPress under Windows is the difficult part.
    I have tried unsuccessfuly many freeware/open source products but failed to find a working server module/user program combination :-( . Any suggestions are welcomed :-)

  6. Nick,

    no suggestion from me, sorry. I don’t use any debuggers or anything like that. Just a browser and a text editor. ;)

    For my debugging needs, I use the plain old approach:

    print "DEBUG: I'm here"

  7. Skeddy said

    Excellent article. I’m in the process of creating a theme, and this will help me to further understand what calls & hooks I need to ensure I cover. Cheers!

  8. I know :-) I am still using similar statements but sometimes things get more complicated when working on the remote server with output buffering / caching enabled so I preffer to output debug in log files:

    If($MyDebug == true){
    //Debug Code
    $fp = fopen("../../debug.log","a+");
    $date = gmdate("Y-m-d H:i:s ");
    fwrite($fp, "\n\n".$date."[Pos xxx] (Message) $var1 ...");

    However debuggers are quite addicting ;-) Once you get used to them going back to log files / echo & print is hard…

  9. Nick,

    yeah, I heard that before from other debugger users. :)

    BTW, if you work with PHP5, then file_put_contents() will make you code snippet much smaller.

  10. BoltPress said

    WordPress source code guide

    WordPress Bits today posted an interesting article (among all its interesting articles) to show you how you can get started getting to know WordPress inside out. That is, its source code.

  11. Aaron said

    You can find the search-able source code here

    The links to functions and references make it an invaluable tool, and once you get used to it, you can find things you need just by starting at a few main functions.

  12. Aaron,

    thanks for the link! It’s a newer version and a better one too – link to the source and provides Summary on the side, not the vice versa. I’ve updated both the post and the sidebar.

  13. […] WordPress – Navigating WordPress source code […]

  14. ladynada said

    good article for me to bookmark. I learned to code php on SMF forum which prepared me to tinker with WordPress.


  15. […] from within The Loop?  Now that’s a touch question.  There are quite a few, but one has to dig through WordPress source code to find them all.  Looking through theme files is an alternative, but a rather limited one – most […]

  16. […] 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 […]

  17. Aizat said

    I am searching for WordPress source code.. hurm.. how do i explain this..

    hehe.. nice article btw..

  18. […] Bits today posted an interesting article (among all its interesting articles) to show you how you can get started getting to know WordPress […]

  19. […] wordpress open source code By whyissit https://wpbits.wordpress.com/2007/08/14/navigating-wordpress-source-code/ […]

  20. Hi All.

    Can any one me please help? Just started a blogg on wordpress and cant add the HTML code given by adsense.
    How do you add the code your get given from Google Adsense to your wordpressblog?
    I have tried firebug and adding the code in a text widget and still it wont work, can any help?

    Thanks and kind regards

  21. Brixter said

    I found the WordPress comments pretty clean to use:

    * Function…
    * @returns val

  22. Excelent post.

    I have been looking for a theme that will do everything that I want it to do without success. This post and a few others I have found have given me the confidence to attempt to create my own custom theme from scratch.

    Keep up the good work and thanks for the links to all the coding resources.

  23. sdmshah said

    u can use a simple online app, TOHTML 

    here u can enter the source code , select the language and style and get html code ,that u can paste in the editor to get a formatted code, i have used it and it also highlights different syntax.. check a post for demo a post for demo here

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: