1. Why bother?
2. Starting out with Vim
3. PHP syntax highlighting
4. PHP syntax checking/linting
5. Tags and auto-completion
6. Codesniffer and mess detector support
7. PHPUnit support
8. Xdebug integration
9. Everything in a neat package

If you’re impatient and want to start tinkering straight away, jump to section 9 to install my Vim configuration.

1. Why bother?

I’ve used a number of IDEs for PHP projects over the past few years: Eclipse, Aptana, Komodo Edit/IDE, Netbeans and PHPStorm. The problem with many of them is speed and resource usage: they eat away at your memory and hog your CPU. Another problem is keyboard shortcuts and commands: it is impossible to do everything using the keyboard, and many things are quicker with the mouse, requiring you to constantly swap between keyboard and mouse. This may not sound like a big deal, but spend a few months learning Vim and it will be a big source of frustration.

So, the answer to that question is this: in the long run, you will be a lot more efficient. Jump to exactly the right place in a file in just a couple of key strokes; open a horizontal split window comparing two files with a command as simple as <Ctrl-w> + s; swap between open files by number (the order of opening); and my favourite – view and navigate a directory tree with all the usual Vim functionality.

2. Starting out with Vim

If you’ve never used Vim before, try the tutorial I mentioned at the top of this post. Also, take a look at the Vim cheat sheet.

The rest of this tutorial assumes that you have a working knowledge of Vim and know how to configure it on at least a basic level (i.e. you know where your vimrc file is, and you know how to install vim scripts). It also assumes that you’re running at least version 7.0 of Vim.

If you don’t know how to install Vim scripts I’d recommend using Vundle, which will manage all your plugins for you and make installing/removing a breeze.

3. PHP syntax highlighting

Vim understands PHP by itself, but you can get improved highlighting and basic syntax checking with the php.vim plugin. This will add better support for certain PHP keywords like define and static, etc., and will allow you to apply custom colours to these keywords. Also, it puts some basic checks in place for invalid syntax, and will highlight the line if you don’t close your brackets, for instance.

4. PHP syntax checking/linting

Most IDEs will run the PHP parser on the file periodically, and warn you of any errors such as invalid syntax and multiple declarations of classes/functions within the same file. One of the beautiful things about Vim is that you can run files through command line programs with total ease, so to check your PHP file you could just run:

:!php -l %

This prints out any error message to the screen. However, we can do better. Vim has a feature called signs, which are used to mark and highlight lines in a file. Wouldn’t it be nice if we could take the PHP parser’s error message and highlight the right line in the file?

It would be nice. And it is nice, because it’s been done. <shameless plug> I have a plugin that does it, called PHP QA tools </shameless plug>. Install this, and every time you write a file it will check it for syntax errors and highlight any offending lines in the file. It will also open a quickfix window that displays the error. This window is specially made for listing errors, and you can read about how to use it in the documentation.

PHP syntax errors are highlighted and shown in the quickfix window

The same plugin will be useful for some things that appear later, so read on…

5. Tags and auto-completion

Code-completion is a feature that most large IDEs provide, along with the ability to jump to class and function definitions within multiple files. All IDEs do this by creating a database of the definitions, and updating this database as you change the code. Many people think that this is a reason not to change to using Vim, as the support isn’t there; this isn’t true.

Omnicompletion is a feature of Vim 7+, and it works by reading a tag file generated by a command-line program called ctags. This file contains definitions for all the classes, functions and variables in your project. You then use <c-x><c-o> (read that as: Ctrl+x followed by Ctrl+o – that’s Vim’s way of showing a Ctrl modifier shortcut) to bring up a list of completions when you are in insert mode. Here’s a screenshot showing it at work:

Omnicompletion at work

A quick note

Before we go on, I’d just like to say that I don’t use omnicompletion. Instead, I use Vim’s local keyword completion. There are several reasons for this:

1. There’s a delay as the context for omnicompletion is determined, and the tags are collected together. This is the case in every IDE I’ve used – it makes logical sense that it as a project gets bigger, the impact on performance of autocompletion gets greater.
2. Local keyword completion is lightning fast, and in many cases saves me valuable seconds (or at least milliseconds!) in typing longer words. This is even more the case with the SuperTab plugin, which I’ll mention soon.
3. It only works for words defined in the current file, but it encourages me to be a better programmer by using consistent naming methods for functions and variables, for instance.

How to generate Ctags

ctags-exuberant -f php.tags --languages=PHP -R

This will create a file named php.tags, which contains a summary of all the definitions of PHP constructs in your project. You may need to tweak the parameters in this command: you may want to exclude certain files (e.g. build artefacts, documentation, etc.), or exclude whole languages like JavaScript from being parsed (--languages=+PHP,-JavaScript). When you’re happy with your tags file, you need to tell Vim to use it:

:set tags=~/path/to/php.tags

You can use more than one tag file at a time: I generate a tag file for my entire PHP include library (i.e. PEAR stuff), a tag file for the framework I’m using and then a tag file for each project, and set all three to be used with a comma separated list.

Now that you’ve set up your tags, try it out. Open up a new PHP file, set the tag file and start typing the name of a class that you know exists. After a few characters type <c-x><c-o> (insert mode) and the omnicompletion will kick in. Then, on the completed class name in command mode, type <c-]>. You will be taken to the class definition, or given a list of definitions if it matches more than one.

Another neat feature is jumping to a tag from the Vim command line. For example, if you know you need to get to the file containing the class MyLovelyClass, just type:

:tag MyLovelyClass

And hit return. You will be taken straight to it. This is almost always quicker than trying to navigate a file tree to find the file you want. Also, this supports tab completion, so you could just type :tag My<tab> and you would get a list of options.

If you’re going to use omnicompletion, definitely install the phpcomplete plugin, as this adds better context awareness for omnicompletion in PHP. I’d also recommend installing SuperTab, and adding this to your vimrc:

let g:SuperTabDefaultCompletionType = ""

Now you just press Tab to trigger omnicompletion.

6. Codesniffer and mess detector support

If you’re not familiar with these tools then you may want to skip this section, as you will only want this support if you already use them. Support for these comes bundled in the PHP QA tools plugin (view on github), which you will already have installed if you’re following each step of this tutorial. The plugin parses their output, puts the violations into a quickfix window and puts line markers in the file (uses the marker S> for codesniffer and M> for mess detector violations). Nice and simple.

Codesniffer and mess detector signs are shown in the margin, and messages in the quickfix window

Everyone who uses these programs has their own set of configuration rules, and happily this plugin allows you to change the configuration to suit. You can set various options in your vimrc file:

CODESNIFFER

" Pass arguments to phpcs binary
let g:phpqa_codesniffer_args = "--standard=Zend"
" Another example
let g:phpqa_codesniffer_args = "--standard=/path/to/xml/file.xml --tab-width=4"

" PHP codesniffer binary (default = phpcs)
let g:phpqa_codesniffer_cmd='/path/to/phpcs'

" Run codesniffer on save (default = 1)
let g:phpqa_codesniffer_autorun = 0

Mess detector

let g:phpqa_messdetector_ruleset = "/path/to/phpmd.xml"

" PHP mess detector binary (default = phpmd)
let g:phpqa_messdetector_cmd='/path/to/phpmd'

" Run mess detector on save (default = 1)
let g:phpqa_messdetector_autorun = 0

7. PHPUnit support

If you use PHPUnit then you can run tests from the Vim command window with another one of my plugins: PHPUnitQF (view on github). This parses the output from PHPUnit tests, and any failures or errors are put into a quickfix window, allowing you to easily jump to the tests that weren’t successful.

To run the tests, just execute:

:Test

Where <arg> is passed straight to the phpunit command. For example, if you would normally run phpunit MyClassTest from a command line, you run :Test MyClassTest from Vim. If you have a standard set of arguments that you pass to phpunit (e.g. a configuration file), you can set a variable in your vimrc file. Here are the available configuration options:

" Arguments to pass to the phpunit binary
let g:phpunit_args = "--configuration /path/to/config"

" Location of phpunit
let g:phpunit_cmd = "/usr/bin/mytest"

" Temporary file used by the plugin
" (shouldn't need to change unless runing on Windows)
let g:phpunit_tmpfile = "/my/new/tmp/file"

You can use any test wrapper whose output is the same format as PHPUnit. For instance, I sometimes use the CakePHP framework which has a wrapper around the PHPUnit command, so I just change g:phpunit_cmd as shown above.

You can also view the full output of the last test run with:

:TestOutput

This opens the output in a split window.

8. Xdebug integration

That’s right. You can use Vim as a debugger client with Xdebug, so it throws the same punches as the big boy IDEs. In fact, I think that the Xdebug plugin for Vim allows more flexibility and functionality than any other implementation I’ve found. It’s certainly easier to tweak and modify it. It’s also great out of the box, and you can get it up and running within a few minutes.

This plugin has a bit of a legacy: it started here, a script by Seung Woo Shin, and has been modified and forked like mad. It goes without saying that I have my own version of it, which you can get from the github repository.

Note: by all means use another version if you wish, but I have added quite a few features that I use all the time, so they might be useful to you too. Look at the README in the repository for a list of changes.

After installing the plugin you will need to set up Xdebug on your machine. To do this, follow step 1 and (optionally) 4 and 5 on my Xdebug, LAMP and Netbeans tutorial.

Now you can set breakpoints in your code with F1 or:

:Bp

Press F5 to make Vim try and connect to the debugger (on port 9000 by default), where it waits for 30 seconds before timing out. During the 30 seconds, if you load the webpage or run the script then the session will start. One of my changes is to open the session in a new tab, to not disrupt the window configuration in your current tab, so you will see a new tab and a few windows open up. It will look something like this:

Windows from left, going clockwise: source code pane, watch window, current stack trace, command window

The left window shows the source code and typically the current execution point. The watch window is one of the key features, as it shows the result of getting the context (i.e. all the variables and their values at the current execution point) and eval results.

To start stepping through the program line-by-line, press F3. The -> marker will move as the program moves on. Execution will pause at any breakpoints that you’ve set up. To step into a function on the current execution line press F2, and F4 to step back out.

To get the current context, press F11 – the watch window will show all variables and their values. You can also evaluate expressions, by typing:

e

(The Leader key is usually \ or ,) You can then type a PHP expression (e.g. a variable, or any valid expression like sqrt(100)), press enter, and the result will be printed in the watch window.

When you’ve finished, press F6 to end the session and close all the windows.

That’s enough to get you started, but you can read the README on the Github repository for more information.

9. Everything in a neat package

Maintaining a Vim configuration is a tricky business. Sometimes you make changes that you think will be helpful, find it annoying after a couple of weeks, and you want to revert back to an old version. That’s exactly why I keep mine under version control – you can view it here.

If you want to use this configuration, there are a couple of things you’ll need to install. You’ll need exuberant-ctags, as talked about in section 5. I’d also recommend installing the Anonymous Pro font if you’re using GVim, as it’s the best code font I’ve come across.

To install, clone the repository to ~/.vim, and initialize the submodule. Then, install the Vundle bundles:

git clone git://github.com/joonty/myvim.git ~/.vim --recurse-submodules
vim +BundleInstall +qall

What’s in the package? Along with everything mentioned in this tutorial, it has the following plugins:

• NERDTree: shows the directory tree, and allows for navigation and modification. Completely essential in my eyes.
• MiniBufExpl: (Mini buffer explorer) shows the open buffers in a kind of tab format, allowing you to easily manage multiple files.
• Tag List:  show definition summaries of classes, functions, variables, etc. for all open files.
• Fugitive: the definitive Git plugin.
• Command-T: super-fast file finding and opening.
• EasyMotion: quickly jump to any word or character in a file.

To use Command-T you need to install a C library – follow the instructions on the plugin’s webpage to install on your system. Trust me, it’s worth it.

Here’s a word of warning: this is my configuration, and it’s likely to change on a fairly regular basis. I don’t guarantee that it will work on your system, and I certainly don’t guarantee that you’ll like it. Feel free to chop and change it as you please.

The Final Word

Hopefully this has been helpful. If you have any suggestions for things I should add to this list then just add a comment.

May the Vim be with you.

Check out http://vim.wikia.com/wiki/Use_Vim_like_an_IDE and http://arstechnica.com/open-source/guides/2009/05/vim-made-easy-how-to-get-your-favorite-ide-features-in-vim.ars for more on that.

I now use Vim as my main PHP editor, and one thing that I’ve managed to get working better than any other IDE I’ve used is integration with quality assurance tools like PHP code sniffer, PHP mess detector and clover code coverage (produced from PHPUnit tests). I’ve written phpqa (vim script #3980), a plugin for Vim that integrates these three tools with your code by highlighting and marking lines with violations and code coverage output. Here are some screenshots showing it at work:

Showing PHP syntax error caused by a missing semicolon

Showing code coverage and code sniffer violations. The lines covered by tests have a yellow "C>" marker, and lines not covered have a red marker.

For more information, including installation, configuration and usage, visit the github page.

Hopefully this plugin will be useful to others, and maybe even convert some people to using it as their IDE replacement! (I know, I’m a dreamer)

The plugin is a meme generator. Don’t know what a meme is? Take a look at memegenerator.net, and any one of those pictures is a meme. The plugin creates a new meme if your project’s build fails, using the memegenerator.net API, and posts it on the project page. Who broke the build? No more hiding – they’re immortalised in an image. Just a bit of fun.

If you fancy giving it a go, sign up for a free account at memegenerator.net and install the plugin from the update center in your Jenkins instance.

• Wiki page: https://wiki.jenkins-ci.org/display/JENKINS/Meme+Generator+Plugin
• Source code: https://github.com/jenkinsci/memegen-plugin

If you don’t agree with me about vim, or you don’t know what I’m talking about, read this article: Why, oh WHY, do those #?@! nutheads use vi?

Two worlds are about to collide: there’s a fantastic plugin for Netbeans called jVi (http://jvi.sourceforge.net/), which allows you to work with all the features of Netbeans and edit code as if you were using Vim. You can install it from Tools -> Plugin in your Netbeans. It works beautifully, and any Vim user will immediately feel at home. In fact, I’m forgetting what it’s like to live without it.

If you give it the time it deserves, I promise you that you won’t want to go back to the way things used to be!

I’ve written this tutorial using Ubuntu 11.10 with Netbeans IDE version 7. It’s recommended that you have this version of Netbeans, as certain things change pretty drastically from version to version. This tutorial mentions CakePHP specific set-up from time to time, but will work for non-Cake projects. I assume that you have a working LAMP environment (Linux, Apache, MySQL and PHP) with PHP 5+. If not, Google it ^_^

1. Install Xdebug

If you’re using Ubuntu, this is as gloriously easy as typing this in a terminal:

$ sudo apt-get install php5-xdebug

If you’re not, don’t worry – you can install it using pecl. (Having said that, I’ve frequently found that pecl doesn’t work the way it’s supposed to, and have had to compile extensions manually. Drop a comment if you have problems.)

$ sudo pecl install xdebug

Providing that one of the two previous commands worked, you need to add some configuration settings so that PHP can use Xdebug. Edit or create the file /etc/php5/conf.d/xdebug.ini, adding the following lines:

xdebug.remote_enable=on
xdebug.remote_handler=dbgp
xdebug.remote_host=localhost
xdebug.remote_port=9000

Xdebug should now be working – running php -m on its own should list xdebug as one of the loaded extensions.

2. Configure Netbeans IDE

Go to Tools -> Options, then click the PHP tab. Under “Debugging”, the following options should be set:

• Debugger port: 9000
• Session ID: netbeans-xdebug
• Stop at first line: (ticked)

This is all that’s needed to set up Netbeans in general, but it’s slightly more complex configuring each project.

3. Configure Netbeans project

There’s a huge variety of ways that you can set up a web project on your LAMP configuration, so I’ll try to make it clear what each option means. To edit the settings for an individual project, right click on the project in the Projects side bar, and choose Properties.

This panel has several categories on the right, and should have Sources selected. On this panel, set the Web Root to the directory containing your index.php file (for CakePHP projects this should be app/webroot - this is essential for making it work).

Next, select the Run Configuration panel. This is where you set up profiles for running your web application. You can have multiple profiles for different configurations, which can come in handy if you are using a framework that also supports command line execution. Choose “Local Web SIte (running on local web server)” as the Run As option, and then enter the local URL of your project (this could be http://localhost, or whatever host name you’ve given). The panel should now look like this:

Run Configuration panel in project properties

Note: many people have one local website running at a time (i.e. http://localhost), and swap the Apache document root as and when they need. I prefer to set my sites up as virtual hosts, and give them each internal host names (e.g. http://joncairns.local).

Now, on the same panel, click “Advanced”, which will open up a new window. The most important thing you should do here is add “localhost” as the debugger proxy at the bottom of the window. Another thing that you would probably like to do is choose “Ask Every Time”  for the debug URL, which will ask you to specify the URL when running the debugger, otherwise it will always go to the root URL.

You should now be ready to run the debugger. Click on a line number somewhere in your code (a line that you know will be executed) to mark it as a breakpoint; this means that the execution will pause when it gets to this line. This is what a breakpoint looks like:

Click on the line number to activate a breakpoint

One of the buttons at the top of the Netbeans window, below the menu, is the button to start the debugger (tooltip “Debug Main Project”) – click it. Your browser should open a tab with your project URL, and hang. You will then see that the breakpoint that you set has changed colour, meaning that the debugger has reached that point. You can use the debug windows to browse any variables in the current scope, which is totally awesome! I’ll leave it to you to use its full potential. When you’re ready to move on, click the icon that looks like a white arrow in a green circle, at the top of the Netbeans window. This will tell the debugger to move to the next breakpoint, or complete the execution if there aren’t any more set. You can stop the debugger at any point by clicking the big red square icon.

4. Integrating with Chrome/Firefox (optional)

Currently we can kick off a debug session from Netbeans, which opens a browser window. But what about if we want to go the other way, starting with our browser, and wake the debugger by reloading our website? This is possible for Google Chrome or Firefox, using plugins.

Google CHrome

This is my personal choice, and there’s a neat plugin called Xdebug helper that does a good job of linking your sites with Netbeans and Xdebug. Download and install, then go to Tools -> Extensions and open the options for Xdebug helper. Under Domains, enter the domain of your site (e.g. localhost or joncairns.local). Then open up a tab with your site and click the little bug icon in the far right of the URL bar until he turns green. Start up the debugger in Netbeans, and leave it running. Now, every time you load your site it will use Xdebug.

Firefox

To be perfectly honest I haven’t tried it in Firefox, but I know that an extension exists – try Easy Xdebug. If anyone fancies giving a step-by-step guide, then that would be welcome.

5. Command-line debugging

To start a debugging session from a command line script you need to set an environment variable before the PHP executable starts. I find that the easiest way to do this is to create a bash script that starts PHP with this variable set, and put it in /usr/bin/php-xdebug:

#!/bin/bash
export XDEBUG_CONFIG="idekey=netbeans-xdebug"
/usr/bin/php "$@"

Run chmod +x on the new file and run the PHP script with:

php-xdebug myscript.php

Happy debugging!

Mickey Mouse's hat from the Sorcerer's Apprentice

The recently updated Star Wars ride was our first port of call (believe it or not, this was a mutual decision and not my doing), which was another simulator. As good as it was, these simulators had a habit of making us both feel slightly ill. They’re almost worse than real roller-coasters, as you have the illusion of movement without actually moving. We then went to the Indiana Jones stunt show, which was absolutely fantastic: you’re given an insight into the way that stunts are executed in films, all within the context of the first Indiana Jones film, and with some amusing audience participation.

Mickey and a broomstick

A stand-out show was “Lights, Motors, Action!”, which featured stunt driving by professionals who do the car chases in films. It was pretty amazing to see how they did certain things: for instance, long periods of driving in reverse were done in a specially modified car that had the driving direction flipped, so that the driver was looking out the back window. Five cars at a time span around at high speed, synchronising their movements to the point where they passed each other with only inches to spare. Plus they had the usual cool stuff like explosions and driving through fire.

Another highlight was the Beauty and the Beast show, which was a beautifully crafted musical following the story of the classic film. As clichéd as it might seem, the best word for it is “enchanting”.

Lots of people holding spoons

The finale was “Fantasmic”, a spectacle containing fireworks, walls of water, giant dragons and everyone’s favourite Disney characters. It was set in an outdoor theatre that held up to 7,000 people, and it was completely full when we were there. Even waiting for the show to start was entertaining, as the crowd managed to get a Mexican wave going: at its peak it looked like everyone was joining in, which is pretty impressive for a group that size. The show was a very memorable end to our theme park visits, and simply defies description (so I won’t try).

I think that we both felt like we’d seen enough after our sixth park. There was no way that we could have visited a park every day and, even though we could have fit another one in before the end of the holiday, we elected to spend the last day and a half by the pool at our resort. We will probably (elbow nudge from Joy) definitely go back in the future, and I’m sure we’ll see some of the things that we didn’t see this time, like the Kennedy Space Centre and Magic Kingdom. We’ve come away with lots of great memories of rest and relaxation, but also of discovery and new experiences.

Fin.

A manta ray waving at us.

There were three main shows that we wanted to see: Clyde and Seamore Take Pirate Island, which was a seal, walrus and otter show; Blue Horizons, containing dolphins and people doing acrobatics; and the main event, Believe, with killer whales (and the iconic Shamu).

We saw the seal show first, which was great fun. The slapstick humour and silly story were just a platform for the animals showing their amazing talents and (almost) unvarying obedience to their trainers. Diving, back-flipping and even dancing were just a few of the things they were more than happy to do to earn a fishy snack. The walrus, due to its size, was less agile – in fact, it could barely move!

Seal staring competition

Blue Horizons was amazing for dolphin lovers (like my wife) and the ambivalent (like me) alike. One of the most impressive tricks was when two dolphins would push a trainer (person, not a shoe) around under the water, eventually surfacing to throw them ten feet up into the air. This was mixed in with people doing acrobatics above the water, and divers jumping from unbelievable heights.

"Help, my upper body has turned into a dolphin"

“Believe” is the park’s main attraction, and features half a dozen killer whales performing tricks in a water tank sitting in a stadium that seats five thousand people. We preceded it by buying pretzels in the shape of a killer whale, as we’d heard good things about American pretzels. To say they were a disappointment is an understatement; it was made entirely of thick, tasteless dough. Most of it wasn’t salted, and the tiny area that was seasoned was covered in gigantic shards of salt.

Fortunately, the show was fantastic. The whales were so obedient to their trainers, and seemed to experience human-like enjoyment when splashing the audience with large amounts of water. You can definitely see why it’s the iconic Sea World show.

We finished off the day by going on the Polar Express simulator, which was less impressive than the section afterwards that was like a miniature zoo of Arctic animals, containing seals, whales and polar bears.

All in all, Sea World was a more relaxed experience compared to the other parks, and unusually you came away with full use of your legs.

Next: Day Thirteen – Disney’s Hollywood Studios