How to setup your WordPress PHP Development environment

If you develop themes or plugins for WordPress you might still be doing this from an editor and FTP your changes to the server. This short guide shows you how to setup a more professional environment and will function as a link I can send around for people still developing PHP in an editor.

Just to show you some cool things to convince you why you should drop your regular text editor:

imageYou get warned about deprecated functions (they are striked through and on mouse-over it gives you the  relevant information).
imageMouse-over a method/function and you get the full WordPress Method information incl. the parameters you need to enter.
image… and by clicking it you jump to the declaration
imagePHP Doc Comments are automatically added including the parameters
imageTired of manually formatting? One-click format your code
imageEverywhere you type @todo ends up in a handy todo list
imageIntegrated version management (for WordPress Subversion but e.g. for you own development RTC) so you can directly check in new versions in the WordPress svn plugin directory and directly create the tags for versions to be released.

 

And much more like integrated debugging.

Getting all of this is not that hard, just follow the following steps and you will have a new cool shiny development environment setup:

 

1 Install Java

image imageBecause we are going to use an Integrated Development Environment that is build in the programming language Java you need to download Java first (unless you have it already installed). Nowadays more than 6,5 million developers are using Java and chances are, that if you are developing software, that you heard about it. Java used to fall under the umbrella of the company Sun but that company is now owned by Oracle.

I developed my first Java programs in 1996. I was pretty exited about the possibilites that you could do with it in browsers using ‘applets’. Unfortunately my road has taken me elsewhere and I never really developed anything more serious things in Java after that.

What you need to know about Java is that it runs on a Java Virtual Machine and by doing so is platform independent. It means that the IDE (the Integrated Development Environment) we are going to install runs on any platform.

If you look for the amount of downloads for Java you could get confused. However … if you just want to “run Java Applications” you need to install the “Java Runtime Environment (JRE)”. Nothing else is needed. If you want to try out developing some software in Java you can download the Java Development Kit (JDK). For our purpose it does not really matter.

You can download it here: http://www.java.com/nl/download/manual.jsp
More links:

2. Install Eclipse

imageimageWhile Microsoft Visual Studio was conquering the world as the main Integrated Development Environment people were thinking how they could compete with that one. (at that time nothing out there could compete with it).

So Eclipse was born. It was based on an older IDE called VisualAge and conceived by IBM. in 2001 it became open source and development is lead by the Eclipse foundation since 2004.

Eclipse has grown from a development IDE to a platform on which all kinds of sofware applications are written. A LOT. Which means that after you install Eclipse you can extend it with a lot of features (one of them is the PHP development environment).

There are 2 ways of getting to our goal: you can either download Eclipse standalone and then use the update option to get the PHP development environment or you download Eclipse+the PHP development environment in one go.

For this story I will assume the second, so you don’t need to download or install anything here.

More Eclipse Links:

3. Install Eclipse PDT

Several free PHP development platforms environments exist notably netbeans (from Oracle), PHP Eclipse, and more.

imageI thought about it for a while but I settled with Eclipse PDT, the Eclipse PHP development Tools project. (the professional version based on Eclipse PDT  is Zend Studio which offers A LOT more).

You can download Eclipse PDT from here: http://www.eclipse.org/pdt/.

The Installation guide can be found here: http://wiki.eclipse.org/PDT/Installation.

Please note that if you choose to download and install Eclipse beforehand you can use that Eclipse installation for extending it with PDT, if you download it all as one package you can just run that one without installing Eclipse first.

So take your time looking through the installation guide of PDT. I am sure you will succceed in installing it.

You can start Eclipse by running eclipse.exe in the root of the installation folder.

What you need to realize is that most of the GUI stuff is “Eclipse” and not PDT. So you need to get accustomed with Eclipse Terminology to understand the basics of what-the-heck you are working in. I will give you a short primer but please ‘Google’ around to find thousands of handy blog articles on how Eclipse works.

image

The workspace: when you first run the application it will ask you where you want to store the data of your workspace. A workspace is a nice concept: you can work in multiple projects and they are all managed by same workspace. If you jump to another set of related projects, you simply create a new workspace an work in there.

When you start your application it will ask you where you want to place your first workspace, the default user folder is a good choice. It will not store your data there just the meta information on the workspace (so the specific configuration for your workspace).

Perspective: a certain “view’ on your screen containing a configured set of windows. So that e.g. you development perspective contains your editor and your debugging perspective contains your variables list. You can find the available perspectives under “Window > Open Perspectives > Other”

You should now have  entered an empty Eclipse PDT environment. Before we continue with setting up your first PHP project. Let’s first get your local environment ready.

4. Installing XAMPP

imageWe want to develop and test locally so we want a local webserver and a local database. One of the easiest ways to get that run on your local host is by installing XAMPP. The philosophy behind XAMPP is to build an easy to install distribution for developers to get into the world of Apache. It was started by Kai Seidler (who now works at Oracle) and Kay Vogelgesang. They created it after writing their book “Apache for dummies” to create an easy-installer for Apache.

Download it here: http://www.apachefriends.org/en/xampp.html

XAMPP contains among others the Apache webserver, PHP and MySQL as database. Pretty handy. A short overview of three important parts which get installed with Xampp:

The Apache Software Foundation 
The Apache Software Foundation
      Apache HTTP Server
The Apache Software Foundation (ASF) hosts nearly 100 top level projects, one of them is the Apache HTTP Server (1994), based on the NCSa HTPD which ran most websites long ago (and which was based on the original httpd (1990) from Tim Berners Lee.
For WordPress you can run a diverse set of Webservers such Microsoft IIS or nginx where WordPress.com is running on. But… since Xampp is basically install and run, the Apache HTTP Server is easier to maintain on your local desktop. Unless you have a need for a specific webserver. In that case: install that one!
We need a local webserver to run our WordPress site locally and test and debug our code.
imageimageMySQL is the relational database management system  that WordPress uses to store its data. So you need to run that locally.
There are some ways to run other Database Systems with WordPress but at this moment in time, MySQL is still the preferred system.
MySQL was owned by MySQL AB but that company is now also owned by Oracle. You might find it handy to install the MySQL workbench tools also although Xampp has also phpmyadmin installed so that you can do simple administratopm MySQL via that web interface (install the MySQL workbench from here http://wb.mysql.com/)
PHPimageimagePHP the hypertext processor, is the scripting language in which WordPress is mainly written, originally made by Rasmus Lerdorf in 1994 as a set of Perl scripts for this personal homepage but greatly improved by Andi Gutmans and Zeev Suraski who wrote the Zen Engine under it and started Zen Technologies which in turn delivers Zend Studio…. which is the big brother of Eclipse PDT … so we are back on our topic.

But… Xampp contains much more, see the website for an overview. (i also liked this summary: http://www.ibm.com/developerworks/linux/library/l-xampp/)

After installation of Xampp you should be able to get a “hello world” application on your http://127.0.0.1/. If not , then read the Xampp instructions to get Xampp up and running: http://www.apachefriends.org/en/faq-xampp.html

imageYou can now download WordPress and extract it in a new subfolder of your htdocs directory e.g. c:\xampp\htdocs\wp2\

When you navigate to http://127.0.0.1/phpmyadmin/ you can use the phpmyadmin tool to create your first new database. (read more about phpmyadmin)

When you navigate in your browser to http://127.0.0.1/wp2 you should get the familiar WordPress setup screen and you can setup your first local WordPress installation.

If you have already have some plugins or themes that you developed in the WordPress repository simply install them now in this folder, so that we can pick them up later in this story.

Note that you can create /wp3, /wp4, /whatever and create zillions of test projects.

Now that you have a local WordPress installation let’s move back to our IDE

5. Create Your Project

Start Eclipse (eclipe.exe), choose your workspace and click on the left hand side on “create new project”.

Let’s suppose that you need to create a new plugin or want to work on your existing plugin, then
1. choose for the root folder the root of your plugin path e.g. in my example: c:\xampp\htdocs\wp2\wp-content\plugins\myplugin,

This will not overwrite the existing plugin in there. It just put it as root folder.

2. include as libraries the WordPress include and admin folders:

c:\xampp\htdocs\wp2\wp-includes\ and c:\xampp\htdocs\wp2\wp-admin this is handy for looking up definitions of functions.

Maybe a picture tells more than a 1000 words:

image  On the left you see my project “WP Favicons” it has subfolders such as “includes” and  “plugins”.

Underneath you see that it includes the 2 WordPress folders as libraries, this is handy while developing for looking up information about WordPress functions, filters, actions and who knows what more.

 

image

On the left you see an example of the information you get: I mouse over my line “register_activation_hook” and I get the information on that hook.

But ofcourse it is also handy to browse through the WP Code itself and see the outline on it in the outline panel.

 

6. Set up Subversion / Install SubClipse

SubversionimageSince WordPress uses Subversion as version management system. It would be handy if our plugin could be commited etc… to the WordPress Repository while developing (i’d rather work in RTC but WordPress forces me to use Subversion grin).

Because we use a Java based environment we need to install the SVNKit but luckily installation can be done with a few clicks using the Eclipse Update mechanism. On here: http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA you can find the URL which you have to refer to to install the subversion plugin e.g:

Eclipse update site URL: http://subclipse.tigris.org/update_1.6.x

in Eclipse you click Help > Install new Software > enter the repository url and select all packages you see (to make it easy):

image

After installation, you rightclick your project and select “TEAM” (version management always is under “Team”). You can now  connect to the WordPress repository. Since your plugin in the WordPress repository uses the CM pattern ‘tags’ and ‘trunk’ (where trunk is the location of the latest version) make sure you connect to the “trunk” location by choosing a custom url, so that the current contents of your local code corresponds to the contents of the trunk location (by default it pasts the  project name behind it, so you need to remove that). Here you see the one for my plugin:

image

While updating you will get a synchronization perspective where you can handle the differences between your version and the one on the server. You have now all options for version control with svn under your right mouse button:

image

Obviously this is a very basic CM setup: one trunk and one developer. When working with multiple developers on the same code you can add their names in the WordPress.org management screen and you might consider setting up subbranches for developers.

7. Setting up PHPDoc for Documentation

WordPress uses PHPDoc for documentation. So should you. There are some guidelines such as “do not use package WordPress in your plugins” in the WordPress CODEC.

It should be part of the XAMPP installation. However you can also download the package from the PHPDOC website and place it on your disk. Please note that in my download there were some files with the wrong extensions…  e.g. CSS files missing the second s and template files missing the wrong letter. So I had to change the file extensions back to the correct name to make my doc look as it should look.

You can set it up easily in the Eclipse PDT using the external Tools section.:

Click run > external tools > external tools configuration

And add a new tool by clicking the “New” button. Now… depending on how you would want your output to appear, you change the settings, I choose:

c:\xampp\phpdoc\phpdoc -d “${project_loc}” -t “${project_loc}\docs” -o HTML:Smarty:default -i “docs/”

image

You can now generate you documentation from the tools section and include it on your site:

image

The handy thing about Eclipse PDT is that it can auto document classes e.g. type “/**” before a class and it will provide you with the complete comment, that speeds things up!

If you have never used PHPDoc before, read the documentation and the WordPress standards for inline documentation:  http://codex.wordpress.org/Inline_Documentation

8. Install the Debugger

Having a debugger around in your IDE is like having a hamburger at the McDonalds.

The instructions on how to setup the debugger in PHP PDT are pretty clear described  from the PHP PDT site: http://www.eclipse.org/pdt/articles/debugger/os-php-eclipse-pdt-debug-pdf.pdf

Notice that the debugger is a seperate download.

9. You Only have Started

After you have played around the setup as above head for the PHP PDT wiki: http://wiki.eclipse.org/index.php/PDT and … grab some more interesting tools!

Comments